feat: add automated documentation update workflow #2
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| name: Auto Update Docs | |
| on: | |
| pull_request: | |
| types: [opened, synchronize, reopened, ready_for_review] | |
| permissions: | |
| contents: write | |
| pull-requests: write | |
| jobs: | |
| auto-docs: | |
| if: ${{ !startsWith(github.head_ref, 'docs/') }} | |
| runs-on: ubuntu-latest | |
| steps: | |
| - name: Checkout repository | |
| uses: actions/checkout@v4 | |
| with: | |
| fetch-depth: 0 | |
| - name: Install Cursor CLI | |
| run: | | |
| curl https://cursor.com/install -fsS | bash | |
| echo "$HOME/.cursor/bin" >> $GITHUB_PATH | |
| - name: Configure git | |
| run: | | |
| git config user.name "Cursor Agent" | |
| git config user.email "[email protected]" | |
| - name: Generate docs updates (no commit/push/comment) | |
| env: | |
| MODEL: gpt-5 | |
| CURSOR_API_KEY: ${{ secrets.CURSOR_API_KEY }} | |
| GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} | |
| BRANCH_PREFIX: docs | |
| run: | | |
| cursor-agent -p "You are operating in a GitHub Actions runner. | |
| The GitHub CLI is available as `gh` and authenticated via `GH_TOKEN`. Git is available. | |
| IMPORTANT: Do NOT create branches, commit, push, or post PR comments. Only modify files in the working directory as needed. A later workflow step is responsible for publishing changes and commenting on the PR. | |
| # Context: | |
| - Repo: ${{ github.repository }} | |
| - Owner: ${{ github.repository_owner }} | |
| - PR Number: ${{ github.event.pull_request.number }} | |
| - Base Ref: ${{ github.base_ref }} | |
| - Head Ref: ${{ github.head_ref }} | |
| # Goal: | |
| - Update repository documentation based on incremental changes introduced by this PR. | |
| # Requirements: | |
| 1) Determine what changed in the original PR (use `gh pr diff` and git history as needed). If an existing persistent docs branch `${{ env.BRANCH_PREFIX }}/${{ github.head_ref }}` exists, you may use it as a read-only reference point to understand prior updates. | |
| 2) Docs are located in the `docs/docs` directory in a flat, markdown files structure | |
| 3) Update only the relevant docs based on those changes. Keep edits minimal and consistent with repo style. | |
| 4) Do NOT commit, push, create branches, or post PR comments. Leave the working tree with updated files only; a later step will publish. | |
| # Inputs and conventions: | |
| - Use `gh pr diff` and git history to detect changes and focus documentation edits accordingly. | |
| - If no doc updates are necessary, make no changes and produce no output. | |
| # Deliverables when updates occur: | |
| - Modified documentation files in the working directory only (no commits/pushes/comments). | |
| " --force --model "$MODEL" --output-format=text | |
| - name: Publish docs branch | |
| id: publish_docs | |
| env: | |
| BRANCH_PREFIX: docs | |
| HEAD_REF: ${{ github.head_ref }} | |
| PR_NUMBER: ${{ github.event.pull_request.number }} | |
| run: | | |
| echo "changes_published=false" >> "$GITHUB_OUTPUT" | |
| DOCS_BRANCH="${BRANCH_PREFIX}/${HEAD_REF}" | |
| # Ensure we are on a local branch that we can push | |
| git fetch origin --prune | |
| # Create/switch to the persistent docs branch, keeping current working tree changes | |
| git checkout -B "$DOCS_BRANCH" | |
| # Stage and detect changes | |
| git add -A | |
| if git diff --staged --quiet; then | |
| echo "No docs changes to publish. Skipping commit/push." | |
| exit 0 | |
| fi | |
| COMMIT_MSG="docs: update for PR #${PR_NUMBER} (${HEAD_REF} @ $(git rev-parse --short HEAD))" | |
| git commit -m "$COMMIT_MSG" | |
| git push --set-upstream origin "$DOCS_BRANCH" | |
| echo "changes_published=true" >> "$GITHUB_OUTPUT" | |
| - name: Post or update PR comment | |
| if: steps.publish_docs.outputs.changes_published == 'true' | |
| env: | |
| GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} | |
| BRANCH_PREFIX: docs | |
| REPO: ${{ github.repository }} | |
| BASE_REF: ${{ github.base_ref }} | |
| HEAD_REF: ${{ github.head_ref }} | |
| PR_NUMBER: ${{ github.event.pull_request.number }} | |
| run: | | |
| DOCS_BRANCH="${BRANCH_PREFIX}/${HEAD_REF}" | |
| COMPARE_URL="https://github.com/${REPO}/compare/${BASE_REF}...${DOCS_BRANCH}?quick_pull=1&title=docs%3A+updates+for+PR+%23${PR_NUMBER}" | |
| COMMENT_FILE="${RUNNER_TEMP}/auto-docs-comment.md" | |
| { | |
| echo "Cursor updated docs branch: \`${DOCS_BRANCH}\`" | |
| echo "You can now [view the diff and quick-create a PR to merge these docs updates](${COMPARE_URL})." | |
| echo | |
| echo "_This comment will be updated on subsequent runs as the PR changes._" | |
| echo | |
| echo "<!-- auto-update-docs-split -->" | |
| } > "$COMMENT_FILE" | |
| # If editing the last bot comment fails (older gh), fall back to creating a new comment | |
| if gh pr comment "$PR_NUMBER" --body-file "$COMMENT_FILE" --edit-last; then | |
| echo "Updated existing PR comment." | |
| else | |
| gh pr comment "$PR_NUMBER" --body-file "$COMMENT_FILE" | |
| echo "Posted new PR comment." | |
| fi |