update-generated-docs.yml

# Copyright Materialize, Inc. and contributors. All rights reserved.
#
# Use of this software is governed by the Business Source License
# included in the LICENSE file at the root of this repository.
#
# As of the Change Date specified in that file, in accordance with
# the Business Source License, use of this software will be governed
# by the Apache License, Version 2.0.

name: Update Generated Docs

on:
  schedule:
    # Run daily at 06:00 UTC
    - cron: '0 6 * * *'
  workflow_dispatch: {} # Allow manual triggering

jobs:
  update-docs:
    if: github.repository == 'MaterializeInc/materialize'
    runs-on: ubuntu-latest
    timeout-minutes: 60
    permissions:
      contents: write
      pull-requests: write
      id-token: write
    env:
      BRANCH: automated/update-generated-docs
    steps:
      - name: Checkout repository
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
        with:
          fetch-depth: 0
          persist-credentials: false

      - name: Set up branch
        id: branch
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git remote set-url origin "https://x-access-token:${GH_TOKEN}@github.com/${GITHUB_REPOSITORY}.git"

          # Check if there's already an open PR from this branch
          EXISTING_PR=$(gh pr list --state open --head "$BRANCH" --json number --jq '.[0].number // empty')

          if [ -n "$EXISTING_PR" ]; then
            echo "Updating existing PR #$EXISTING_PR on branch $BRANCH"
            git fetch origin "$BRANCH"
            git checkout "$BRANCH"
            # If merge conflicts, reset to main — PR content is fully generated
            if ! git merge --no-edit origin/main; then
              echo "Merge conflict, resetting branch to main"
              git merge --abort
              git reset --hard origin/main
            fi
          else
            # Delete stale remote branch if it exists without an open PR
            if git ls-remote --exit-code origin "refs/heads/$BRANCH" >/dev/null 2>&1; then
              echo "Deleting stale remote branch $BRANCH (no open PR)"
              git push origin --delete "$BRANCH"
            fi
            git checkout -b "$BRANCH"
          fi

          echo "existing_pr=$EXISTING_PR" >> "$GITHUB_OUTPUT"

      - name: Run Claude Code to update docs
        id: claude
        uses: anthropics/claude-code-action@02438e66d09982e371c6559d3a2ccdff9032f203 # v1.0.77
        with:
          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
          prompt: |
            Run the procedure described in .claude/commands/update-docs.md

            IMPORTANT: You may ONLY create or modify files under doc/developer/generated/.
            Do NOT modify any other files.
          claude_args: '--allowedTools Edit Read Glob Grep Bash(git log:*) Bash(git diff:*) Bash(find:*) Bash(wc:*) Bash(head:*)'

      - name: Check for changes
        id: changes
        run: |
          if git diff --quiet HEAD -- doc/developer/generated/; then
            echo "has_changes=false" >> "$GITHUB_OUTPUT"
          else
            echo "has_changes=true" >> "$GITHUB_OUTPUT"
          fi

      - name: Commit and push
        if: steps.changes.outputs.has_changes == 'true'
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git remote set-url origin "https://x-access-token:${GH_TOKEN}@github.com/${GITHUB_REPOSITORY}.git"
          git add doc/developer/generated/
          git commit -m "doc: update generated developer documentation

          Automated daily refresh of doc/developer/generated/ to reflect
          source changes since each doc was last written.

          Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>"
          git push origin "$BRANCH"

      - name: Create pull request
        if: steps.changes.outputs.has_changes == 'true' && steps.branch.outputs.existing_pr == ''
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          gh pr create \
            --head "$BRANCH" \
            --title "doc: update generated developer documentation" \
            --body "$(cat <<'EOF'
          ## Summary

          Automated daily refresh of `doc/developer/generated/` to reflect source code changes.

          This PR was generated by the `update-generated-docs` workflow running `.claude/commands/update-docs.md`.

          ## Scope

          Only files under `doc/developer/generated/` are modified.

          ## Review checklist

          - [ ] No unrelated rewording or restructuring of existing text
          - [ ] No changelog language ("now", "added", "previously", etc.)
          - [ ] Changes correspond to actual source code changes

          🤖 Generated with [Claude Code](https://claude.com/claude-code)
          EOF
          )" \
            --label "A-docs" \
            --reviewer bosconi
          # Automerge is intentionally NOT enabled here.
          # A human must review and approve before merging to prevent
          # doc degeneration (see PR #35775 discussion).

      # GITHUB_TOKEN cannot trigger other workflows, so the CLA workflow
      # never fires for PRs created by this workflow. Set the status
      # directly since github-actions[bot] is in the CLA allowlist.
      - name: Set CLA status for bot author
        if: steps.changes.outputs.has_changes == 'true'
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          SHA=$(git rev-parse HEAD)
          gh api "repos/${GITHUB_REPOSITORY}/statuses/${SHA}" \
            -f state=success \
            -f context=cla-assistant \
            -f description="All contributors have signed the CLA."