CI: generate error code docs from trusted commits only (#20789)

Signed-off-by: Arthur Schreiber <arthur@planetscale.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: arthurschreiber

…hub/workflows/error_code_docs_update.yml .github/workflows/error_code_docs.yml.github/workflows/error_code_docs_update.yml renamed to .github/workflows/error_code_docs.yml .github/workflows/error_code_docs_update.yml renamed to .github/workflows/error_code_docs.yml

@@ -1,92 +1,96 @@
-# Updates the website repository with generated error code documentation.
-name: Update error code docs
+# Regenerates the error code documentation on the website whenever
+# go/vt/vterrors/code.go changes on main or a release branch.
+name: Error code docs
 
 on:
-  workflow_run:
-    workflows: ["Generate error code docs"]
-    types: [completed]
+  push:
+    branches:
+      - "main"
+      - "release-[0-9]+.[0-9]"
+    paths:
+      - "go/vt/vterrors/code.go"
+
+# Runs for one branch share a website branch and force-push to it, so let the
+# newest run win rather than racing an older one.
+concurrency:
+  group: format('{0}-{1}', ${{ github.ref }}, 'Error code docs')
+  cancel-in-progress: true
 
 permissions:
   contents: read
-  actions: read
 
 jobs:
-  update_error_code_docs:
+  error_code_docs:
     name: Update error code docs
     runs-on: ubuntu-latest
-    if: github.event.workflow_run.conclusion == 'success'
 
     steps:
       - name: Harden the runner (Audit all outbound calls)
         uses: step-security/harden-runner@bf7454d06d71f1098171f2acdf0cd4708d7b5920 # v2.20.0
         with:
           egress-policy: audit
 
-      - name: Download artifact
-        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+      - name: Checkout vitess
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
         with:
-          pattern: error-codes-*
-          path: /tmp/artifact
-          github-token: ${{ secrets.GITHUB_TOKEN }}
-          run-id: ${{ github.event.workflow_run.id }}
-          merge-multiple: true
-
-      - name: Read metadata
-        id: metadata
-        run: |
-          if [[ ! -f /tmp/artifact/metadata.json ]]; then
-            echo "No metadata found, skipping"
-            echo "skip=true" >> "$GITHUB_OUTPUT"
-            exit 0
-          fi
+          persist-credentials: 'false'
 
-          echo "pr_number=$(jq -r '.pr_number' /tmp/artifact/metadata.json)" >> "$GITHUB_OUTPUT"
-          echo "base_ref=$(jq -r '.base_ref' /tmp/artifact/metadata.json)" >> "$GITHUB_OUTPUT"
+      - name: Set up Go
+        uses: ./.github/actions/setup-go
+
+      - name: Generate error codes
+        run: |
+          go run ./go/vt/vterrors/vterrorsgen > /tmp/error_codes.txt
+          echo "Error codes generated successfully"
 
       - name: Generate GitHub App token
-        if: steps.metadata.outputs.skip != 'true'
         uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
         id: app-token
         with:
           app-id: ${{ vars.APP_ID }}
           private-key: ${{ secrets.APP_PRIVATE_KEY }}
           owner: ${{ github.repository_owner }}
-          repositories: vitess,website
+          repositories: website
           permission-contents: write
           permission-pull-requests: write
 
       - name: Determine docs version
-        if: steps.metadata.outputs.skip != 'true'
         id: docs_version
         env:
           GH_TOKEN: ${{ steps.app-token.outputs.token }}
-          BASE_REF: ${{ steps.metadata.outputs.base_ref }}
+          REF_NAME: ${{ github.ref_name }}
           REPO_OWNER: ${{ github.repository_owner }}
         run: |
-          if [[ "$BASE_REF" == "main" ]]; then
+          if [[ "$REF_NAME" == "main" ]]; then
             # Get the "next" version from website config.toml.
             VERSION=$(gh api "repos/${REPO_OWNER}/website/contents/config.toml" \
               --jq '.content' | base64 -d | grep 'next = ' | sed 's/.*"\([0-9.]*\)".*/\1/')
-            echo "version=$VERSION" >> "$GITHUB_OUTPUT"
-            echo "Docs version (from next): $VERSION"
-          elif [[ "$BASE_REF" =~ ^release-([0-9]+\.[0-9]+)$ ]]; then
+          elif [[ "$REF_NAME" =~ ^release-([0-9]+\.[0-9]+)$ ]]; then
             VERSION="${BASH_REMATCH[1]}"
-            echo "version=$VERSION" >> "$GITHUB_OUTPUT"
-            echo "Docs version (from release branch): $VERSION"
           else
-            echo "Unknown base ref: $BASE_REF, skipping"
-            echo "skip=true" >> "$GITHUB_OUTPUT"
+            echo "Unexpected ref: $REF_NAME"
+            exit 1
           fi
 
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+          echo "Docs version: $VERSION"
+
       - name: Clone website repository
-        if: steps.metadata.outputs.skip != 'true' && steps.docs_version.outputs.skip != 'true'
+        id: website
         env:
           REPO_OWNER: ${{ github.repository_owner }}
+          VERSION: ${{ steps.docs_version.outputs.version }}
         run: |
-          git clone --depth 1 "https://github.com/${REPO_OWNER}/website.git" /tmp/website
+          BRANCH_NAME="update-error-code-${VERSION}"
+
+          # The branch is always rebuilt from prod and force-pushed, so the
+          # remote copy of a previous run's branch is never needed here.
+          git clone --depth 1 --branch prod "https://github.com/${REPO_OWNER}/website.git" /tmp/website
+          git -C /tmp/website checkout -b "${BRANCH_NAME}"
+
+          echo "branch=${BRANCH_NAME}" >> "$GITHUB_OUTPUT"
 
       - name: Update error documentation
-        if: steps.metadata.outputs.skip != 'true' && steps.docs_version.outputs.skip != 'true'
         id: update_docs
         env:
           VERSION: ${{ steps.docs_version.outputs.version }}
@@ -100,7 +104,7 @@ jobs:
           fi
 
           # Read the generated error codes.
-          ERROR_CODES=$(cat /tmp/artifact/error_codes.txt)
+          ERROR_CODES=$(cat /tmp/error_codes.txt)
 
           # Update the documentation between <!-- start --> and <!-- end --> markers.
           awk -v codes="$ERROR_CODES" '
@@ -122,7 +126,7 @@ jobs:
           fi
 
       - name: Get GitHub App user ID
-        if: steps.metadata.outputs.skip != 'true' && steps.docs_version.outputs.skip != 'true' && steps.update_docs.outputs.skip != 'true'
+        if: steps.update_docs.outputs.skip != 'true'
         id: get-user-id
         env:
           GH_TOKEN: ${{ steps.app-token.outputs.token }}
@@ -131,7 +135,7 @@ jobs:
           echo "user-id=$(gh api "/users/${APP_SLUG}[bot]" --jq .id)" >> "$GITHUB_OUTPUT"
 
       - name: Configure Git
-        if: steps.metadata.outputs.skip != 'true' && steps.docs_version.outputs.skip != 'true' && steps.update_docs.outputs.skip != 'true'
+        if: steps.update_docs.outputs.skip != 'true'
         env:
           APP_SLUG: ${{ steps.app-token.outputs.app-slug }}
           USER_ID: ${{ steps.get-user-id.outputs.user-id }}
@@ -140,49 +144,42 @@ jobs:
           git config --global user.email "${USER_ID}+${APP_SLUG}[bot]@users.noreply.github.com"
 
       - name: Create or update PR on website
-        if: steps.metadata.outputs.skip != 'true' && steps.docs_version.outputs.skip != 'true' && steps.update_docs.outputs.skip != 'true'
+        if: steps.update_docs.outputs.skip != 'true'
         env:
           GH_TOKEN: ${{ steps.app-token.outputs.token }}
-          PR_NUMBER: ${{ steps.metadata.outputs.pr_number }}
+          VERSION: ${{ steps.docs_version.outputs.version }}
+          BRANCH_NAME: ${{ steps.website.outputs.branch }}
           DOC_PATH: ${{ steps.update_docs.outputs.doc_path }}
           REPO_OWNER: ${{ github.repository_owner }}
           REPOSITORY: ${{ github.repository }}
+          COMMIT_SHA: ${{ github.sha }}
         run: |
-          BRANCH_NAME="update-error-code-${PR_NUMBER}"
-
           cd /tmp/website
 
-          # Check if branch already exists.
-          if gh api "repos/${REPO_OWNER}/website/branches/${BRANCH_NAME}" --silent 2>/dev/null; then
-            echo "Branch ${BRANCH_NAME} already exists, updating..."
-            git fetch origin "${BRANCH_NAME}"
-            git checkout "${BRANCH_NAME}"
-            git reset --hard origin/prod
-          else
-            echo "Creating new branch ${BRANCH_NAME}..."
-            git checkout -b "${BRANCH_NAME}"
-          fi
-
           # Stage and commit changes.
           git add "$DOC_PATH"
           git commit -m "Updated the query-serving error code"
 
           # Push changes.
           git push -f "https://x-access-token:${GH_TOKEN}@github.com/${REPO_OWNER}/website.git" "${BRANCH_NAME}"
 
+          PR_BODY="## Description
+          This Pull Request updates the error code documentation based on https://github.com/${REPOSITORY}/commit/${COMMIT_SHA}"
+
           # Check if PR already exists.
           EXISTING_PR=$(gh pr list --repo "${REPO_OWNER}/website" --head "${BRANCH_NAME}" --json number --jq '.[0].number' 2>/dev/null || echo "")
 
           if [[ -n "$EXISTING_PR" ]]; then
-            echo "PR #${EXISTING_PR} already exists, updated branch"
+            # Point the description at the commit the branch was just rebuilt from.
+            gh pr edit "$EXISTING_PR" --repo "${REPO_OWNER}/website" --body "$PR_BODY"
+            echo "Updated existing pull request:"
             echo "https://github.com/${REPO_OWNER}/website/pull/${EXISTING_PR}"
           else
             # Create new PR.
             gh pr create \
               --repo "${REPO_OWNER}/website" \
-              --title "Update error code documentation (#${PR_NUMBER})" \
-              --body "## Description
-          This Pull Request updates the error code documentation based on the changes made in https://github.com/${REPOSITORY}/pull/${PR_NUMBER}" \
+              --title "Update error code documentation (v${VERSION})" \
+              --body "$PR_BODY" \
               --base prod \
               --head "${BRANCH_NAME}"
           fi