@mintlify/cli 4.0.1725 → 4.0.1727

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mintlify/cli",
-  "version": "4.0.1725",
+  "version": "4.0.1727",
   "description": "The Mintlify CLI",
   "engines": {
     "node": ">=18.0.0"
@@ -45,12 +45,12 @@
   },
   "dependencies": {
     "@inquirer/prompts": "7.9.0",
-    "@mintlify/common": "1.0.1301",
-    "@mintlify/link-rot": "3.0.1528",
+    "@mintlify/common": "1.0.1302",
+    "@mintlify/link-rot": "3.0.1529",
     "@mintlify/models": "0.0.378",
-    "@mintlify/og": "0.0.100",
-    "@mintlify/prebuild": "1.0.1467",
-    "@mintlify/previewing": "4.0.1546",
+    "@mintlify/og": "0.0.101",
+    "@mintlify/prebuild": "1.0.1468",
+    "@mintlify/previewing": "4.0.1547",
     "@mintlify/validation": "0.1.943",
     "adm-zip": "0.6.0",
     "chalk": "5.2.0",
@@ -82,7 +82,7 @@
     "keytar": "7.9.0"
   },
   "devDependencies": {
-    "@mintlify/editor": "0.0.571",
+    "@mintlify/editor": "0.0.572",
     "@mintlify/ts-config": "2.0.2",
     "@tsconfig/recommended": "1.0.2",
     "@types/detect-port": "1.3.2",
@@ -101,5 +101,5 @@
     "vitest": "2.1.9",
     "vitest-mock-process": "1.0.4"
   },
-  "gitHead": "12237800a5c6539d34436035b01cacb5896ec15e"
+  "gitHead": "0acd59c1a76613a44dab176301efe476263b8f51"
 }

package/src/agent-deployment.ts

@@ -34,6 +34,13 @@ const writeTokenSchema = z.object({
   tokenExpiresAt: z.iso.datetime(),
 });
 
+const trustedReposSchema = z.object({
+  subdomain: z.string().min(1),
+  trustedRepos: z.array(
+    z.object({ repositoryId: z.string(), repository: z.string(), branch: z.string() })
+  ),
+});
+
 export type AgentSite = z.infer<typeof readySchema>;
 export type AgentWriteToken = z.infer<typeof writeTokenSchema>;
 export type AgentSiteSettings = { subdomain: string; orgName?: string };
@@ -73,3 +80,31 @@ export async function getAgentWriteToken(
     writeTokenSchema
   );
 }
+
+export async function getGithubActionsWriteToken(
+  apiUrl: string,
+  oidcToken: string,
+  subdomain: string
+): Promise<AgentWriteToken> {
+  return agentResponse(
+    await agentRequest(`${apiUrl}/api/agent/deployments/github-actions/token`, {
+      method: 'POST',
+      headers: { Authorization: `Bearer ${oidcToken}`, 'Content-Type': 'application/json' },
+      body: JSON.stringify({ subdomain }),
+    }),
+    writeTokenSchema
+  );
+}
+
+export type TrustedRepo = { repositoryId: string; repository: string; branch: string };
+
+export async function trustGithubRepo(apiUrl: string, accessToken: string, repo: TrustedRepo) {
+  return agentResponse(
+    await agentRequest(`${apiUrl}/api/agent/deployments/trusted-repos`, {
+      method: 'POST',
+      headers: { Authorization: `Bearer ${accessToken}`, 'Content-Type': 'application/json' },
+      body: JSON.stringify(repo),
+    }),
+    trustedReposSchema
+  );
+}

package/src/cli.tsx

@@ -24,6 +24,8 @@ import { comingSoon } from './comingSoon.js';
 import { setTelemetryEnabled } from './config.js';
 import { getConfigValue, setConfigValue, clearConfigValue } from './config.js';
 import { API_URL } from './constants.js';
+import { deployFromGithubActions, isGithubActions } from './deploy-github-actions.js';
+import { formatGithubSetup, setupGithubDeployment } from './deploy-github-setup.js';
 import { DEPLOY_HELP, deploymentInstructions } from './deploy-instructions.js';
 import { formatDeployment, prepareAgentDeployment } from './deploy.js';
 import { formatHandler } from './format.js';
@@ -175,15 +177,63 @@ export const cli = ({ packageName = 'mint' }: { packageName?: string }) => {
               type: 'string',
               description: 'User email for an optional claim link',
             })
+            .option('github', {
+              type: 'boolean',
+              default: false,
+              description:
+                'Trust this GitHub repository to deploy the site and write a GitHub Actions workflow',
+            })
+            .option('force', {
+              type: 'boolean',
+              default: false,
+              description: 'With --github, overwrite an existing .github/workflows/mintlify.yml',
+            })
+            .conflicts('github', 'email')
             .example('$0 deploy --subdomain my-docs', 'Provision a site without signing in')
             .example(
               '$0 deploy --email you@example.com',
               'Get repository access and a claim link for the current site'
             )
             .example('$0 deploy --new --subdomain another-site', 'Create another anonymous site')
+            .example(
+              '$0 deploy --github --subdomain my-docs',
+              'Deploy the site from GitHub Actions on every push to the default branch'
+            )
+            .example(
+              '$0 deploy --subdomain my-docs',
+              'In GitHub Actions with id-token: write, push the current commit to a trusted site'
+            )
             .epilog(DEPLOY_HELP),
         async (argv) => {
           try {
+            if (isGithubActions()) {
+              const siteUrl = await deployFromGithubActions(
+                { apiUrl: API_URL, directory: argv.directory, subdomain: argv.subdomain },
+                (message) => process.stderr.write(`${message}\n`)
+              );
+              process.stdout.write(
+                `Pushed to ${argv.subdomain}; the build starts now.\nSite: ${siteUrl}\n`
+              );
+              await terminate(0);
+              return;
+            }
+            if (argv.github) {
+              const setup = await setupGithubDeployment(
+                {
+                  apiUrl: API_URL,
+                  directory: argv.directory,
+                  subdomain: argv.subdomain,
+                  orgName: argv.orgName,
+                  newSite: argv.new,
+                  force: argv.force,
+                },
+                (message) => process.stderr.write(`Warning: ${message}\n`),
+                (message) => process.stderr.write(`${message}\n`)
+              );
+              process.stdout.write(`${formatGithubSetup(setup)}\n`);
+              await terminate(0);
+              return;
+            }
             const result = await prepareAgentDeployment(
               {
                 apiUrl: API_URL,

package/src/deploy-github-actions.ts

@@ -0,0 +1,139 @@
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+import { z } from 'zod';
+
+import { getGithubActionsWriteToken, type AgentWriteToken } from './agent-deployment.js';
+import { AgentApiError } from './agent-http.js';
+import { agentSiteUrl } from './deploy.js';
+
+const oidcSchema = z.object({ value: z.string().min(1) });
+
+export type GithubActionsDeployOptions = {
+  apiUrl: string;
+  directory: string;
+  subdomain?: string;
+};
+
+export function isGithubActions(env: NodeJS.ProcessEnv = process.env): boolean {
+  return env.GITHUB_ACTIONS === 'true';
+}
+
+async function getGithubOidcToken(env: NodeJS.ProcessEnv, audience: string): Promise<string> {
+  const requestUrl = env.ACTIONS_ID_TOKEN_REQUEST_URL;
+  const requestToken = env.ACTIONS_ID_TOKEN_REQUEST_TOKEN;
+  if (!requestUrl || !requestToken) {
+    throw new Error(
+      'GitHub Actions did not provide an OIDC token. Add `permissions: id-token: write` to the workflow or job.'
+    );
+  }
+  let response: Response;
+  try {
+    response = await fetch(`${requestUrl}&audience=${encodeURIComponent(audience)}`, {
+      headers: { Authorization: `Bearer ${requestToken}` },
+      signal: AbortSignal.timeout(30_000),
+    });
+  } catch {
+    throw new Error('Could not request a GitHub Actions OIDC token. Retry the workflow.');
+  }
+  const parsed = oidcSchema.safeParse(await response.json().catch(() => null));
+  if (!response.ok || !parsed.success) {
+    throw new Error(
+      `Could not get a GitHub Actions OIDC token (HTTP ${response.status}). Check that the workflow has \`permissions: id-token: write\`.`
+    );
+  }
+  return parsed.data.value;
+}
+
+function git(args: string[], cwd: string, env: NodeJS.ProcessEnv): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const child = spawn('git', args, { cwd, env, stdio: ['ignore', 'pipe', 'inherit'] });
+    let out = '';
+    child.stdout.on('data', (chunk: Buffer) => (out += chunk.toString()));
+    child.on('error', reject);
+    child.on('close', (code) =>
+      code === 0 ? resolve(out.trim()) : reject(new Error(`git ${args[0]} failed`))
+    );
+  });
+}
+
+async function commitDirectory(directory: string, env: NodeJS.ProcessEnv): Promise<string> {
+  const prefix = await git(['rev-parse', '--show-prefix'], directory, env);
+  const tree = await git(['rev-parse', `HEAD:${prefix}`], directory, env);
+  const [name = '', email = '', date = '', sha = '', subject = ''] = (
+    await git(['log', '-1', '--format=%an%n%ae%n%aI%n%H%n%s'], directory, env)
+  ).split('\n');
+  const repository = env.GITHUB_REPOSITORY ? `${env.GITHUB_REPOSITORY}@` : '';
+  return git(
+    ['commit-tree', tree, '-m', subject, '-m', `Deployed from ${repository}${sha}`],
+    directory,
+    {
+      ...env,
+      GIT_AUTHOR_NAME: name,
+      GIT_AUTHOR_EMAIL: email,
+      GIT_AUTHOR_DATE: date,
+      GIT_COMMITTER_NAME: name,
+      GIT_COMMITTER_EMAIL: email,
+    }
+  );
+}
+
+function pushCommit(
+  directory: string,
+  commit: string,
+  write: AgentWriteToken,
+  env: NodeJS.ProcessEnv
+): Promise<void> {
+  const index = Number(env.GIT_CONFIG_COUNT) || 0;
+  const credentials = Buffer.from(`x-access-token:${write.token}`).toString('base64');
+  return new Promise((resolve, reject) => {
+    const child = spawn(
+      'git',
+      ['push', '--force', write.remote, `${commit}:refs/heads/${write.branch}`],
+      {
+        cwd: directory,
+        stdio: ['ignore', 'inherit', 'inherit'],
+        env: {
+          ...env,
+          GIT_CONFIG_COUNT: String(index + 1),
+          [`GIT_CONFIG_KEY_${index}`]: `http.${write.remote}.extraHeader`,
+          [`GIT_CONFIG_VALUE_${index}`]: `Authorization: Basic ${credentials}`,
+        },
+      }
+    );
+    const failed = () => reject(new Error('git push to the site repository failed.'));
+    child.on('error', failed);
+    child.on('close', (code) => (code === 0 ? resolve() : failed()));
+  });
+}
+
+export async function deployFromGithubActions(
+  options: GithubActionsDeployOptions,
+  progress: (message: string) => void = () => {},
+  env: NodeJS.ProcessEnv = process.env
+): Promise<string> {
+  const { apiUrl, subdomain } = options;
+  if (!subdomain) throw new Error('Pass the site name with --subdomain <name>.');
+  const directory = path.resolve(options.directory);
+  const commit = await commitDirectory(directory, env).catch(() => {
+    throw new Error(
+      `Could not read ${options.directory} from the checked-out commit. Run mint deploy after actions/checkout, with --directory inside the repository.`
+    );
+  });
+  progress('Requesting a GitHub Actions identity token...');
+  const oidcToken = await getGithubOidcToken(env, apiUrl);
+  progress('Getting repository write access...');
+  let write: AgentWriteToken;
+  try {
+    write = await getGithubActionsWriteToken(apiUrl, oidcToken, subdomain);
+  } catch (error) {
+    if (error instanceof AgentApiError && error.status === 403) {
+      throw new Error(
+        `This repository/branch isn't trusted to deploy ${subdomain}. Run \`mint deploy --github\` locally from this repository to trust it.`
+      );
+    }
+    throw error;
+  }
+  progress('Pushing to the site repository...');
+  await pushCommit(directory, commit, write, env);
+  return agentSiteUrl(apiUrl, subdomain);
+}

package/src/deploy-github-setup.ts

@@ -0,0 +1,189 @@
+import { execFile } from 'node:child_process';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { z } from 'zod';
+
+import { trustGithubRepo } from './agent-deployment.js';
+import { CLAIM_INSTRUCTIONS } from './deploy-instructions.js';
+import { agentSiteUrl, prepareAgentDeployment, type DeployOptions } from './deploy.js';
+
+const githubRepoSchema = z.object({
+  id: z.number().int().positive(),
+  full_name: z.string().regex(/^[\w.-]+\/[\w.-]+$/),
+  default_branch: z.string().min(1),
+});
+
+export type GithubRepo = z.infer<typeof githubRepoSchema>;
+
+export const GITHUB_WORKFLOW_PATH = path.join('.github', 'workflows', 'mintlify.yml');
+
+function run(command: string, args: string[], cwd: string): Promise<string> {
+  return new Promise((resolve, reject) => {
+    execFile(command, args, { cwd }, (error, stdout) =>
+      error ? reject(error) : resolve(String(stdout).trim())
+    );
+  });
+}
+
+export function parseGithubRemote(remote: string): { owner: string; repo: string } | null {
+  const match = remote
+    .trim()
+    .match(
+      /^(?:https:\/\/(?:[^@/]+@)?github\.com\/|ssh:\/\/git@github\.com(?::\d+)?\/|git@github\.com:)([\w.-]+)\/([\w.-]+?)(?:\.git)?\/?$/
+    );
+  return match?.[1] && match[2] ? { owner: match[1], repo: match[2] } : null;
+}
+
+export function githubWorkflow(branch: string, subdomain: string, docsPath = ''): string {
+  const directory = /^[\w./-]+$/.test(docsPath) ? docsPath : JSON.stringify(docsPath);
+  return [
+    'name: Deploy to Mintlify',
+    'on:',
+    '  push:',
+    `    branches: [${JSON.stringify(branch)}]`,
+    ...(docsPath
+      ? [`    paths: [${JSON.stringify(`${docsPath}/**`)}, ".github/workflows/mintlify.yml"]`]
+      : []),
+    'permissions:',
+    '  id-token: write',
+    '  contents: read',
+    'concurrency:',
+    '  group: mintlify-deploy',
+    '  cancel-in-progress: true',
+    'jobs:',
+    '  deploy:',
+    '    runs-on: ubuntu-latest',
+    '    steps:',
+    '      - uses: actions/checkout@v4',
+    `      - run: npx mint@latest deploy --subdomain ${subdomain}${docsPath ? ` --directory ${directory}` : ''}`,
+    '',
+  ].join('\n');
+}
+
+async function readFileIfExists(file: string): Promise<string | undefined> {
+  return fs.readFile(file, 'utf8').catch((error: NodeJS.ErrnoException) => {
+    if (error.code === 'ENOENT') return undefined;
+    throw error;
+  });
+}
+
+export async function writeGithubWorkflow(
+  root: string,
+  contents: string,
+  force = false
+): Promise<'created' | 'unchanged' | 'updated'> {
+  const file = path.join(root, GITHUB_WORKFLOW_PATH);
+  const existing = await readFileIfExists(file);
+  if (existing === contents) return 'unchanged';
+  if (existing !== undefined && !force) {
+    throw new Error(
+      `${GITHUB_WORKFLOW_PATH} already exists with different contents. Pass --force to overwrite it.`
+    );
+  }
+  await fs.mkdir(path.dirname(file), { recursive: true });
+  await fs.writeFile(file, contents);
+  return existing === undefined ? 'created' : 'updated';
+}
+
+export async function findGitRoot(directory: string): Promise<string> {
+  try {
+    return await run('git', ['rev-parse', '--show-toplevel'], directory);
+  } catch {
+    throw new Error('--github requires a Git repository. Run it inside your docs repository.');
+  }
+}
+
+export async function resolveGithubRepo(root: string): Promise<GithubRepo> {
+  const remote = await run('git', ['remote', 'get-url', 'origin'], root).catch(() => {
+    throw new Error('This repository has no origin remote. Add a github.com origin and retry.');
+  });
+  const parsed = parseGithubRemote(remote);
+  if (!parsed) throw new Error(`The origin remote (${remote}) is not a github.com repository.`);
+  const output = await run(
+    'gh',
+    [
+      'api',
+      `repos/${parsed.owner}/${parsed.repo}`,
+      '--jq',
+      '{id: .id, full_name: .full_name, default_branch: .default_branch}',
+    ],
+    root
+  ).catch((error: NodeJS.ErrnoException) => {
+    if (error.code === 'ENOENT')
+      throw new Error('The GitHub CLI (gh) is required. Install it and run `gh auth login`.');
+    throw new Error(
+      `Could not read ${parsed.owner}/${parsed.repo} with gh. Run \`gh auth login\` with access to the repository and retry.`
+    );
+  });
+  try {
+    return githubRepoSchema.parse(JSON.parse(output));
+  } catch {
+    throw new Error('gh returned an unexpected repository response.');
+  }
+}
+
+export type GithubSetupResult = {
+  siteUrl: string;
+  subdomain: string;
+  repository: string;
+  branch: string;
+  workflowPath: string;
+  workflow: 'created' | 'unchanged' | 'updated';
+};
+
+export async function setupGithubDeployment(
+  options: DeployOptions & { force?: boolean },
+  warn: (message: string) => void,
+  progress: (message: string) => void = () => {}
+): Promise<GithubSetupResult> {
+  const directory = path.resolve(options.directory);
+  const root = await findGitRoot(directory);
+  const [realRoot, realDirectory] = await Promise.all([fs.realpath(root), fs.realpath(directory)]);
+  const docsPath = path.relative(realRoot, realDirectory).split(path.sep).join('/');
+  if (!(await readFileIfExists(path.join(directory, 'docs.json')))) {
+    throw new Error(`No docs.json in ${directory}. Pass the docs folder with --directory.`);
+  }
+  progress('Resolving the GitHub repository...');
+  const repo = await resolveGithubRepo(root);
+  const result = await prepareAgentDeployment(options, warn, progress);
+  if (result.status === 'claimed') {
+    throw new Error(
+      'This site has been claimed. Setting up GitHub deploys for claimed sites is not supported yet; connect the repository from the Mintlify dashboard.'
+    );
+  }
+  const accessToken = result.credentials.accessToken;
+  if (!accessToken) throw new Error('Agent authentication did not return an access token.');
+  progress(`Trusting ${repo.full_name}@${repo.default_branch} to deploy...`);
+  await trustGithubRepo(options.apiUrl, accessToken, {
+    repositoryId: String(repo.id),
+    repository: repo.full_name,
+    branch: repo.default_branch,
+  });
+  const workflow = await writeGithubWorkflow(
+    root,
+    githubWorkflow(repo.default_branch, result.site.subdomain, docsPath),
+    options.force
+  );
+  return {
+    siteUrl: agentSiteUrl(options.apiUrl, result.site.subdomain),
+    subdomain: result.site.subdomain,
+    repository: repo.full_name,
+    branch: repo.default_branch,
+    workflowPath: GITHUB_WORKFLOW_PATH,
+    workflow,
+  };
+}
+
+export function formatGithubSetup(result: GithubSetupResult): string {
+  return [
+    `Site: ${result.siteUrl}`,
+    `Trusted repository: ${result.repository} (branch ${result.branch})`,
+    `Workflow: ${result.workflowPath} (${result.workflow})`,
+    '',
+    'Next steps:',
+    `1. Commit and push ${result.workflowPath} to ${result.branch}.`,
+    `2. Every push to ${result.branch} then deploys ${result.subdomain} through GitHub Actions. No secrets are stored in the repository.`,
+    '',
+    ...CLAIM_INSTRUCTIONS,
+  ].join('\n');
+}

package/src/deploy-instructions.ts

@@ -8,8 +8,15 @@ export const DEPLOY_HELP = [
   'Pass --email to obtain a claim link for the user. If it is absent, ask the user for their email and rerun with --email from the same directory. Never invent an email address.',
   'To claim an existing site without provisioning, run mint claim --email <email>. Show the link to the user and ask them to return the displayed code. Then run mint claim --code <code>. Use the original documentation directory for both commands, or pass --directory.',
   'The output contains a short-lived write token. Do not paste it into public logs or save it in a Git remote.',
+  'Pass --github from the root of a GitHub repository to deploy on every push: it trusts the repository (via the gh CLI and the origin remote) to deploy the site and writes .github/workflows/mintlify.yml. Commit and push that workflow. Pass --directory to deploy a docs subdirectory of the repository as the site root. Use --force to overwrite a different existing workflow.',
+  'In GitHub Actions (GITHUB_ACTIONS=true), no agent credentials are used: the workflow needs `permissions: id-token: write`, --subdomain is required, and the current commit is force-pushed to the site from a trusted repository and branch.',
 ].join('\n\n');
 
+export const CLAIM_INSTRUCTIONS = [
+  'Ask the user for the email address they want to use to claim this site. Never invent an email address.',
+  'After they provide it, run mint deploy --email <their-email> from the same documentation directory (or repeat --directory). This reuses the site and returns its claim link.',
+];
+
 export function deploymentInstructions(result: DeployResult, claimUrl?: string): string {
   if (result.status !== 'ready') return '';
   return [
@@ -33,9 +40,6 @@ export function deploymentInstructions(result: DeployResult, claimUrl?: string):
           'Show this link to the user. Ask them to open it, sign in, and return the displayed code. Do not sign in on their behalf.',
           'After the user returns the code, run mint claim --code <code> from the same documentation directory (or repeat --directory). The CLI completes the claim using its saved credentials.',
         ]
-      : [
-          'Ask the user for the email address they want to use to claim this site. Never invent an email address.',
-          'After they provide it, run mint deploy --email <their-email> from the same documentation directory (or repeat --directory). This reuses the site and returns its claim link.',
-        ]),
+      : CLAIM_INSTRUCTIONS),
   ].join('\n');
 }

package/src/deploy.ts

@@ -105,15 +105,19 @@ export async function prepareAgentDeployment(
   throw new Error('The new anonymous site is already expired. Please retry later.');
 }
 
-export function formatDeployment(result: DeployResult, apiUrl: string): string {
-  if (result.status === 'claimed')
-    return 'This site has been claimed. Manage it in the Mintlify dashboard. Use mint deploy --new --subdomain <name> to create another site.';
-  const { site, write } = result;
+export function agentSiteUrl(apiUrl: string, subdomain: string): string {
   const domain =
     new URL(apiUrl).hostname === 'leaves-dev.mintlify.com'
       ? 'mint-dev.mintlify.me'
       : 'mintlify.site';
-  const siteUrl = new URL(`https://${site.subdomain}.${domain}`).toString();
+  return new URL(`https://${subdomain}.${domain}`).toString();
+}
+
+export function formatDeployment(result: DeployResult, apiUrl: string): string {
+  if (result.status === 'claimed')
+    return 'This site has been claimed. Manage it in the Mintlify dashboard. Use mint deploy --new --subdomain <name> to create another site.';
+  const { site, write } = result;
+  const siteUrl = agentSiteUrl(apiUrl, site.subdomain);
   return [
     result.created
       ? 'Repository provisioned; push required to build the site.'