update-docs.yml

name: Auto-update Documentation

on:
  pull_request:
    types: [closed]

jobs:
  update-docs:
    # Only run if PR was actually merged (not just closed)
    if: github.event.pull_request.merged == true
    runs-on: ubuntu-latest

    steps:
      - name: Get PR details
        id: pr_details
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          PR_DIFF=$(gh api \
            -H "Accept: application/vnd.github.v3.diff" \
            /repos/${{ github.repository }}/pulls/${{ github.event.pull_request.number }})

          FILES_CHANGED=$(gh api \
            /repos/${{ github.repository }}/pulls/${{ github.event.pull_request.number }}/files \
            --jq '[.[] | .filename] | join(", ")')

          echo "pr_diff<<EOF" >> $GITHUB_OUTPUT
          echo "$PR_DIFF" >> $GITHUB_OUTPUT
          echo "EOF" >> $GITHUB_OUTPUT

          echo "files_changed=$FILES_CHANGED" >> $GITHUB_OUTPUT

      - name: Call Mintlify Agent API
        uses: actions/github-script@v8
        env:
          MINTLIFY_API_KEY: ${{ secrets.MINTLIFY_API_KEY }}
          PROJECT_ID: ${{ secrets.MINTLIFY_PROJECT_ID }}
          PR_NUMBER: ${{ github.event.pull_request.number }}
          PR_TITLE: ${{ github.event.pull_request.title }}
          PR_URL: ${{ github.event.pull_request.html_url }}
          PR_BODY: ${{ github.event.pull_request.body }}
          PR_DIFF: ${{ steps.pr_details.outputs.pr_diff }}
          FILES_CHANGED: ${{ steps.pr_details.outputs.files_changed }}
        with:
          script: |
            const { owner, repo } = context.repo;
            const projectId = process.env.PROJECT_ID;
            const apiKey = process.env.MINTLIFY_API_KEY;

            if (!projectId || !apiKey) {
              core.setFailed('Missing MINTLIFY_PROJECT_ID or MINTLIFY_API_KEY secrets');
              return;
            }

            const prBody = process.env.PR_BODY || 'No description provided';
            const userMessage = [
              `You are a documentation maintainer for ${owner}/${repo}. This is a monorepo: application code and documentation live in the same repository. All documentation files are under the \`docs/\` directory (Mintlify config at \`docs/docs.json\`). Scope every edit to \`docs/\` only — do not modify application code. Open the documentation PR against this same repository (${owner}/${repo}).`,
              ``,
              `## Merged PR Details`,
              `- **PR**: #${process.env.PR_NUMBER} — ${process.env.PR_TITLE}`,
              `- **URL**: ${process.env.PR_URL}`,
              `- **Files Changed**: ${process.env.FILES_CHANGED}`,
              ``,
              `## PR Description`,
              prBody,
              ``,
              `## Code Changes (Diff)`,
              '```diff',
              process.env.PR_DIFF,
              '```',
              ``,
              `## Instructions`,
              `First, review the merged diff and the repository's \`docs/\` directory to assess whether documentation changes are actually needed. If no relevant updates are needed, make no file changes and do not open a PR.`,
              ``,
              `If updates are needed, categorize the change and update only the appropriate docs under \`docs/\`. We have two main types of docs:`,
              `1. **Feature docs** (how users use features)`,
              `2. **Contributing docs** (engineering concepts for technical contributors) live under \`docs/contributing/\` and \`docs/evals/\``,
              ``,
              `Keep edits minimal, precise, and user-focused. When adding/moving pages, update \`docs/docs.json\` to keep navigation accurate. Use concise commit messages and open a focused PR only when changes are required. Use .mmd files for diagrams and other visual content if needed.`,
            ].join('\n');

            const url = `https://api.mintlify.com/v1/agent/${projectId}/job`;
            const payload = {
              branch: `mintlify/docs-update-pr-${process.env.PR_NUMBER}-${Date.now()}`,
              messages: [
                {
                  role: 'system',
                  content: 'You are an action runner that updates documentation based on code changes. You should never ask questions. If you are not able to access the repository, report the error and exit.'
                },
                {
                  role: 'user',
                  content: userMessage
                }
              ],
              asDraft: false
            };

            try {
              const response = await fetch(url, {
                method: 'POST',
                headers: {
                  'Authorization': `Bearer ${apiKey}`,
                  'Content-Type': 'application/json'
                },
                body: JSON.stringify(payload)
              });

              if (!response.ok) {
                throw new Error(`API request failed with status ${response.status}: ${await response.text()}`);
              }

              const reader = response.body.getReader();
              const decoder = new TextDecoder();
              let buffer = '';

              while (true) {
                const { done, value } = await reader.read();
                if (done) break;
                buffer += decoder.decode(value, { stream: true });
                const lines = buffer.split('\n');
                buffer = lines.pop() || '';
                for (const line of lines) {
                  if (line.trim()) {
                    console.log(line);
                  }
                }
              }
              if (buffer.trim()) {
                console.log(buffer);
              }

              core.notice(`Documentation update job triggered for ${owner}/${repo} PR #${process.env.PR_NUMBER}`);
            } catch (error) {
              core.setFailed(`Failed to create documentation update job: ${error.message}`);
            }