Merge OpenAPI PRs via the merge API instead of pushing to main

jencarlucci · Copilot · jencarlucci · commit a8fef0bf9359 · 2026-07-10T13:23:02.000-06:00
Replace the local git merge + direct push to the protected default branch
with `gh pr merge` on each of the two latest PRs. Merging a PR is the
compliant path through the "require a pull request" branch rule, so the job
no longer needs a protected-branch push or any ruleset/branch-protection
bypass — OPENAPI_MERGE_TOKEN only needs pull-requests:write + contents:write.

The synchronous merge call can gateway-timeout (502/504) on these ~250K-line
diffs, so merge_pr retries and polls the PR's merged state after each failure
(the merge usually completes server-side despite the timeout). Drops the
actions/checkout-with-token step. Recompiled the lock with gh aw.

Co-authored-by: Copilot &lt;223556219+Copilot@users.noreply.github.com&gt;
Copilot-Session: dcc1f083-b349-4398-ae7e-e2b90b1924b7
diff --git a/.github/workflows/openapi-pr-reviewer.lock.yml b/.github/workflows/openapi-pr-reviewer.lock.yml
@@ -1,5 +1,5 @@
-# gh-aw-metadata: {"schema_version":"v4","frontmatter_hash":"b6c2caf626a31ee17846d663483346b74ff421e65c20f3d4713e57fa3a5c5938","body_hash":"754e3baebfa788bc34791e9abcecf9ff11c1fbd66001673477acce8bb80db1a7","compiler_version":"v0.79.6","strict":true,"agent_id":"copilot","engine_versions":{"copilot":"1.0.60"}}
-# gh-aw-manifest: {"version":1,"secrets":["CHATTERBOX_TOKEN","CHATTERBOX_URL","COPILOT_GITHUB_TOKEN","GH_AW_GITHUB_MCP_SERVER_TOKEN","GH_AW_GITHUB_TOKEN","GITHUB_TOKEN","OPENAPI_MERGE_TOKEN"],"actions":[{"repo":"actions/checkout","sha":"93cb6efe18208431cddfb8368fd83d5badbf9bfd","version":"v5"},{"repo":"actions/checkout","sha":"df4cb1c069e1874edd31b4311f1884172cec0e10","version":"v6.0.3"},{"repo":"actions/download-artifact","sha":"3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c","version":"v8.0.1"},{"repo":"actions/github-script","sha":"3a2844b7e9c422d3c10d287c895573f7108da1b3","version":"v9.0.0"},{"repo":"actions/setup-node","sha":"48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e","version":"v6.4.0"},{"repo":"actions/upload-artifact","sha":"043fb46d1a93c77aae656e7c1c64a875d1fc6a0a","version":"v7.0.1"},{"repo":"github/gh-aw-actions/setup","sha":"5c2fe865bb4dc46e1450f6ee0d0541d759aea73a","version":"v0.79.6"}],"containers":[{"image":"ghcr.io/github/gh-aw-firewall/agent:0.27.2","digest":"sha256:f88e5b17b6b7a600117bc121114d6ce2155c88c983c0c939c5df884f730fa1d6","pinned_image":"ghcr.io/github/gh-aw-firewall/agent:0.27.2@sha256:f88e5b17b6b7a600117bc121114d6ce2155c88c983c0c939c5df884f730fa1d6"},{"image":"ghcr.io/github/gh-aw-firewall/api-proxy:0.27.2","digest":"sha256:ee39841d980878ebbb87592903b06d31a1af500c71525c9616f7e8e2a27041a4","pinned_image":"ghcr.io/github/gh-aw-firewall/api-proxy:0.27.2@sha256:ee39841d980878ebbb87592903b06d31a1af500c71525c9616f7e8e2a27041a4"},{"image":"ghcr.io/github/gh-aw-firewall/squid:0.27.2","digest":"sha256:2e3a717e5f19a654cd9a2263beb52012b56bcb68562ec5ae2e42f9d156b49591","pinned_image":"ghcr.io/github/gh-aw-firewall/squid:0.27.2@sha256:2e3a717e5f19a654cd9a2263beb52012b56bcb68562ec5ae2e42f9d156b49591"},{"image":"ghcr.io/github/gh-aw-mcpg:v0.3.25","digest":"sha256:c10331ad17668ef89f38f5e356678788a40b0cd5fef96e8f92e1d9c1de47cbaa","pinned_image":"ghcr.io/github/gh-aw-mcpg:v0.3.25@sha256:c10331ad17668ef89f38f5e356678788a40b0cd5fef96e8f92e1d9c1de47cbaa"},{"image":"ghcr.io/github/github-mcp-server:v1.1.2","digest":"sha256:30197479d8036c7811892bc07e06f9a05c9ef3cdd79bc59f256d50647f95788c","pinned_image":"ghcr.io/github/github-mcp-server:v1.1.2@sha256:30197479d8036c7811892bc07e06f9a05c9ef3cdd79bc59f256d50647f95788c"}]}
+# gh-aw-metadata: {"schema_version":"v4","frontmatter_hash":"9cc11dc458df1edec3a42d9cca931bb313fbd3f00f032a7022c2f746c1d12dbf","body_hash":"754e3baebfa788bc34791e9abcecf9ff11c1fbd66001673477acce8bb80db1a7","compiler_version":"v0.79.6","strict":true,"agent_id":"copilot","engine_versions":{"copilot":"1.0.60"}}
+# gh-aw-manifest: {"version":1,"secrets":["CHATTERBOX_TOKEN","CHATTERBOX_URL","COPILOT_GITHUB_TOKEN","GH_AW_GITHUB_MCP_SERVER_TOKEN","GH_AW_GITHUB_TOKEN","GITHUB_TOKEN","OPENAPI_MERGE_TOKEN"],"actions":[{"repo":"actions/checkout","sha":"df4cb1c069e1874edd31b4311f1884172cec0e10","version":"v6.0.3"},{"repo":"actions/download-artifact","sha":"3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c","version":"v8.0.1"},{"repo":"actions/github-script","sha":"3a2844b7e9c422d3c10d287c895573f7108da1b3","version":"v9.0.0"},{"repo":"actions/setup-node","sha":"48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e","version":"v6.4.0"},{"repo":"actions/upload-artifact","sha":"043fb46d1a93c77aae656e7c1c64a875d1fc6a0a","version":"v7.0.1"},{"repo":"github/gh-aw-actions/setup","sha":"5c2fe865bb4dc46e1450f6ee0d0541d759aea73a","version":"v0.79.6"}],"containers":[{"image":"ghcr.io/github/gh-aw-firewall/agent:0.27.2","digest":"sha256:f88e5b17b6b7a600117bc121114d6ce2155c88c983c0c939c5df884f730fa1d6","pinned_image":"ghcr.io/github/gh-aw-firewall/agent:0.27.2@sha256:f88e5b17b6b7a600117bc121114d6ce2155c88c983c0c939c5df884f730fa1d6"},{"image":"ghcr.io/github/gh-aw-firewall/api-proxy:0.27.2","digest":"sha256:ee39841d980878ebbb87592903b06d31a1af500c71525c9616f7e8e2a27041a4","pinned_image":"ghcr.io/github/gh-aw-firewall/api-proxy:0.27.2@sha256:ee39841d980878ebbb87592903b06d31a1af500c71525c9616f7e8e2a27041a4"},{"image":"ghcr.io/github/gh-aw-firewall/squid:0.27.2","digest":"sha256:2e3a717e5f19a654cd9a2263beb52012b56bcb68562ec5ae2e42f9d156b49591","pinned_image":"ghcr.io/github/gh-aw-firewall/squid:0.27.2@sha256:2e3a717e5f19a654cd9a2263beb52012b56bcb68562ec5ae2e42f9d156b49591"},{"image":"ghcr.io/github/gh-aw-mcpg:v0.3.25","digest":"sha256:c10331ad17668ef89f38f5e356678788a40b0cd5fef96e8f92e1d9c1de47cbaa","pinned_image":"ghcr.io/github/gh-aw-mcpg:v0.3.25@sha256:c10331ad17668ef89f38f5e356678788a40b0cd5fef96e8f92e1d9c1de47cbaa"},{"image":"ghcr.io/github/github-mcp-server:v1.1.2","digest":"sha256:30197479d8036c7811892bc07e06f9a05c9ef3cdd79bc59f256d50647f95788c","pinned_image":"ghcr.io/github/github-mcp-server:v1.1.2@sha256:30197479d8036c7811892bc07e06f9a05c9ef3cdd79bc59f256d50647f95788c"}]}
 #    ___                   _   _      
 #   / _ \                 | | (_)     
 #  | |_| | __ _  ___ _ __ | |_ _  ___ 
@@ -34,7 +34,6 @@
 #   - OPENAPI_MERGE_TOKEN
 #
 # Custom actions used:
-#   - actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
 #   - actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
 #   - actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
 #   - actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
@@ -477,9 +476,9 @@ jobs:
           mkdir -p "${RUNNER_TEMP}/gh-aw/safeoutputs"
           mkdir -p /tmp/gh-aw/safeoutputs
           mkdir -p /tmp/gh-aw/mcp-logs/safeoutputs
-          cat > "${RUNNER_TEMP}/gh-aw/safeoutputs/config.json" << 'GH_AW_SAFE_OUTPUTS_CONFIG_9f1f6edab7d72a41_EOF'
-          {"create_report_incomplete_issue":{},"merge-openapi-prs":{"description":"Merge the latest OpenAPI 3.0 and 3.1 description PRs into the default branch, close the older superseded PRs, and notify Slack. Call this ONLY when no breaking changes were found. Provide the two latest PR numbers and the list of older PR numbers.\n","inputs":{"older_prs":{"default":null,"description":"Comma-separated PR numbers of older superseded PRs to close (may be empty).","required":false,"type":"string"},"pr_30":{"default":null,"description":"PR number of the latest 'Update OpenAPI 3.0 Descriptions' PR.","required":true,"type":"number"},"pr_31":{"default":null,"description":"PR number of the latest 'Update OpenAPI 3.1 Descriptions' PR.","required":true,"type":"number"},"summary":{"default":null,"description":"One-line summary of the merged changes for the Slack notification.","required":true,"type":"string"}},"output":"OpenAPI PRs merged, older PRs closed, Slack notified."},"missing_data":{},"missing_tool":{},"noop":{"max":1,"report-as-issue":"true"},"post-to-chatterbox":{"description":"Post a message to the #api-platform Slack channel via chatterbox. Message must be 200 characters or less. Supports Slack markdown (*bold*, _italic_, `code`, \u003curl|text\u003e). Requires the CHATTERBOX_URL and CHATTERBOX_TOKEN secrets to be configured.\n","inputs":{"message":{"default":null,"description":"The message to post (max 200 characters, Slack markdown).","required":true,"type":"string"}},"output":"Message posted to chatterbox."},"report_incomplete":{}}
-          GH_AW_SAFE_OUTPUTS_CONFIG_9f1f6edab7d72a41_EOF
+          cat > "${RUNNER_TEMP}/gh-aw/safeoutputs/config.json" << 'GH_AW_SAFE_OUTPUTS_CONFIG_b02c1f8e9d0c4506_EOF'
+          {"create_report_incomplete_issue":{},"merge-openapi-prs":{"description":"Merge the latest OpenAPI 3.0 and 3.1 description PRs into the default branch, close the older superseded PRs, and notify chatterbox. Call this ONLY when no breaking changes were found. Provide the two latest PR numbers and the list of older PR numbers.\n","inputs":{"older_prs":{"default":null,"description":"Comma-separated PR numbers of older superseded PRs to close (may be empty).","required":false,"type":"string"},"pr_30":{"default":null,"description":"PR number of the latest 'Update OpenAPI 3.0 Descriptions' PR.","required":true,"type":"number"},"pr_31":{"default":null,"description":"PR number of the latest 'Update OpenAPI 3.1 Descriptions' PR.","required":true,"type":"number"},"summary":{"default":null,"description":"One-line summary of the merged changes for the chatterbox notification.","required":true,"type":"string"}},"output":"OpenAPI PRs merged, older PRs closed, chatterbox notified."},"missing_data":{},"missing_tool":{},"noop":{"max":1,"report-as-issue":"true"},"post-to-chatterbox":{"description":"Post a message to the #api-platform Slack channel via chatterbox. Message must be 200 characters or less. Supports Slack markdown (*bold*, _italic_, `code`, \u003curl|text\u003e). Requires the CHATTERBOX_URL and CHATTERBOX_TOKEN secrets to be configured.\n","inputs":{"message":{"default":null,"description":"The message to post (max 200 characters, Slack markdown).","required":true,"type":"string"}},"output":"Message posted to chatterbox."},"report_incomplete":{}}
+          GH_AW_SAFE_OUTPUTS_CONFIG_b02c1f8e9d0c4506_EOF
       - name: Generate Safe Outputs Tools
         env:
           GH_AW_TOOLS_META_JSON: |
@@ -488,7 +487,7 @@ jobs:
               "repo_params": {},
               "dynamic_tools": [
                 {
-                  "description": "Merge the latest OpenAPI 3.0 and 3.1 description PRs into the default branch, close the older superseded PRs, and notify Slack. Call this ONLY when no breaking changes were found. Provide the two latest PR numbers and the list of older PR numbers.\n",
+                  "description": "Merge the latest OpenAPI 3.0 and 3.1 description PRs into the default branch, close the older superseded PRs, and notify chatterbox. Call this ONLY when no breaking changes were found. Provide the two latest PR numbers and the list of older PR numbers.\n",
                   "inputSchema": {
                     "additionalProperties": false,
                     "properties": {
@@ -505,7 +504,7 @@ jobs:
                         "type": "number"
                       },
                       "summary": {
-                        "description": "One-line summary of the merged changes for the Slack notification.",
+                        "description": "One-line summary of the merged changes for the chatterbox notification.",
                         "type": "string"
                       }
                     },
@@ -1475,35 +1474,40 @@ jobs:
             core.setOutput('pr_31', String(item.pr_31));
             core.setOutput('older_prs', item.older_prs || '');
             core.setOutput('summary', item.summary || '');
-      - name: Checkout default branch
-        uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
-        env:
-          CHATTERBOX_TOKEN: ${{ secrets.CHATTERBOX_TOKEN }}
-          CHATTERBOX_URL: ${{ secrets.CHATTERBOX_URL }}
-          GH_AW_AGENT_OUTPUT: ${{ runner.temp }}/gh-aw/safe-jobs/agent_output.json
-          MERGE_TOKEN: ${{ secrets.OPENAPI_MERGE_TOKEN }}
-        with:
-          fetch-depth: 0
-          token: ${{ env.MERGE_TOKEN }}
-      - name: Merge PRs locally and push
+      - name: Merge the two latest PRs via the merge API
         if: ${{ env.GH_AW_SAFE_OUTPUTS_STAGED != 'true' }}
         run: |
           set -euo pipefail
-          git config user.name "github-actions[bot]"
-          git config user.email "github-actions[bot]@users.noreply.github.com"
-          DEFAULT_BRANCH="${GITHUB_REF_NAME}"
-          git checkout "$DEFAULT_BRANCH"
-          # Fetch the two PR heads (bot branches live in this repo, so pull/N/head works).
-          git fetch origin "pull/${PR_30}/head:pr-${PR_30}"
-          git fetch origin "pull/${PR_31}/head:pr-${PR_31}"
-          # Merge 3.0 first, then 3.1, to avoid conflicts (they touch disjoint paths).
-          git merge --no-ff "pr-${PR_30}" -m "Merge OpenAPI 3.0 descriptions (#${PR_30})"
-          git merge --no-ff "pr-${PR_31}" -m "Merge OpenAPI 3.1 descriptions (#${PR_31})"
-          git push origin "$DEFAULT_BRANCH"
+          # Merge each PR through the GitHub merge API (a merge commit, like the old --no-ff).
+          # These diffs are huge (~64 files / 250K lines), so the synchronous merge call can
+          # gateway-timeout (502/504) even though the merge completes server-side. Retry, and
+          # after each failure poll the PR's merged state before giving up.
+          merge_pr() {
+            local n="$1" label="$2"
+            echo "Merging #$n ($label)..."
+            for attempt in 1 2 3 4 5; do
+              if [ "$(gh pr view "$n" --repo "$GITHUB_REPOSITORY" --json merged -q .merged)" = "true" ]; then
+                echo "#$n already merged."; return 0
+              fi
+              if gh pr merge "$n" --repo "$GITHUB_REPOSITORY" --merge; then
+                echo "#$n merged."; return 0
+              fi
+              echo "Merge attempt $attempt for #$n failed (likely a gateway timeout on a large diff); waiting to see if it completed server-side..."
+              sleep 30
+              if [ "$(gh pr view "$n" --repo "$GITHUB_REPOSITORY" --json merged -q .merged)" = "true" ]; then
+                echo "#$n merged (completed server-side after timeout)."; return 0
+              fi
+            done
+            echo "ERROR: failed to merge #$n after retries." >&2; return 1
+          }
+          # Merge 3.0 first, then 3.1 (they touch disjoint paths, so no conflicts).
+          merge_pr "$PR_30" "OpenAPI 3.0"
+          merge_pr "$PR_31" "OpenAPI 3.1"
         env:
           CHATTERBOX_TOKEN: ${{ secrets.CHATTERBOX_TOKEN }}
           CHATTERBOX_URL: ${{ secrets.CHATTERBOX_URL }}
           GH_AW_AGENT_OUTPUT: ${{ runner.temp }}/gh-aw/safe-jobs/agent_output.json
+          GH_TOKEN: ${{ env.MERGE_TOKEN }}
           MERGE_TOKEN: ${{ secrets.OPENAPI_MERGE_TOKEN }}
           PR_30: ${{ steps.req.outputs.pr_30 }}
           PR_31: ${{ steps.req.outputs.pr_31 }}
diff --git a/.github/workflows/openapi-pr-reviewer.md b/.github/workflows/openapi-pr-reviewer.md
@@ -103,17 +103,18 @@ safe-outputs:
               }
 
     # ---- Merge + close + notify ------------------------------------------------------
-    # The agent calls this ONCE when there are NO breaking changes. It performs the
-    # privileged local-git merge (the merge API times out on these diffs), closes the
-    # older superseded PRs, and posts the merged-PR list to Slack — all in one gated job
-    # so the "merged" notification only fires on real success.
+    # The agent calls this ONCE when there are NO breaking changes. It merges the two latest
+    # PRs via the GitHub merge API (merging a PR satisfies the "require a pull request" branch
+    # rule, so no protected-branch push/bypass is needed), closes the older superseded PRs,
+    # and posts the merged-PR list to chatterbox — all in one gated job so the "merged"
+    # notification only fires on real success.
     merge-openapi-prs:
       description: >
         Merge the latest OpenAPI 3.0 and 3.1 description PRs into the default branch, close
-        the older superseded PRs, and notify Slack. Call this ONLY when no breaking changes
+        the older superseded PRs, and notify chatterbox. Call this ONLY when no breaking changes
         were found. Provide the two latest PR numbers and the list of older PR numbers.
       runs-on: ubuntu-latest
-      output: "OpenAPI PRs merged, older PRs closed, Slack notified."
+      output: "OpenAPI PRs merged, older PRs closed, chatterbox notified."
       permissions:
         contents: write
         pull-requests: write
@@ -131,12 +132,13 @@ safe-outputs:
           required: false
           type: string
         summary:
-          description: "One-line summary of the merged changes for the Slack notification."
+          description: "One-line summary of the merged changes for the chatterbox notification."
           required: true
           type: string
       env:
-        # Dedicated PAT (or GitHub App token) that can push to the protected default branch.
-        # The default GITHUB_TOKEN cannot bypass required status checks; see PR description.
+        # Token used to merge the PRs and close the older ones. Merging a PR is the compliant
+        # path through the "require a pull request" branch rule, so this only needs
+        # `pull-requests: write` + `contents: write` — no protected-branch push/bypass.
         MERGE_TOKEN: "${{ secrets.OPENAPI_MERGE_TOKEN }}"
         CHATTERBOX_URL: "${{ secrets.CHATTERBOX_URL }}"
         CHATTERBOX_TOKEN: "${{ secrets.CHATTERBOX_TOKEN }}"
@@ -155,29 +157,39 @@ safe-outputs:
               core.setOutput('pr_31', String(item.pr_31));
               core.setOutput('older_prs', item.older_prs || '');
               core.setOutput('summary', item.summary || '');
-        - name: Checkout default branch
-          uses: actions/checkout@v5
-          with:
-            fetch-depth: 0
-            token: ${{ env.MERGE_TOKEN }}
-        - name: Merge PRs locally and push
+        - name: Merge the two latest PRs via the merge API
           if: ${{ env.GH_AW_SAFE_OUTPUTS_STAGED != 'true' }}
           env:
+            GH_TOKEN: ${{ env.MERGE_TOKEN }}
             PR_30: ${{ steps.req.outputs.pr_30 }}
             PR_31: ${{ steps.req.outputs.pr_31 }}
           run: |
             set -euo pipefail
-            git config user.name "github-actions[bot]"
-            git config user.email "github-actions[bot]@users.noreply.github.com"
-            DEFAULT_BRANCH="${GITHUB_REF_NAME}"
-            git checkout "$DEFAULT_BRANCH"
-            # Fetch the two PR heads (bot branches live in this repo, so pull/N/head works).
-            git fetch origin "pull/${PR_30}/head:pr-${PR_30}"
-            git fetch origin "pull/${PR_31}/head:pr-${PR_31}"
-            # Merge 3.0 first, then 3.1, to avoid conflicts (they touch disjoint paths).
-            git merge --no-ff "pr-${PR_30}" -m "Merge OpenAPI 3.0 descriptions (#${PR_30})"
-            git merge --no-ff "pr-${PR_31}" -m "Merge OpenAPI 3.1 descriptions (#${PR_31})"
-            git push origin "$DEFAULT_BRANCH"
+            # Merge each PR through the GitHub merge API (a merge commit, like the old --no-ff).
+            # These diffs are huge (~64 files / 250K lines), so the synchronous merge call can
+            # gateway-timeout (502/504) even though the merge completes server-side. Retry, and
+            # after each failure poll the PR's merged state before giving up.
+            merge_pr() {
+              local n="$1" label="$2"
+              echo "Merging #$n ($label)..."
+              for attempt in 1 2 3 4 5; do
+                if [ "$(gh pr view "$n" --repo "$GITHUB_REPOSITORY" --json merged -q .merged)" = "true" ]; then
+                  echo "#$n already merged."; return 0
+                fi
+                if gh pr merge "$n" --repo "$GITHUB_REPOSITORY" --merge; then
+                  echo "#$n merged."; return 0
+                fi
+                echo "Merge attempt $attempt for #$n failed (likely a gateway timeout on a large diff); waiting to see if it completed server-side..."
+                sleep 30
+                if [ "$(gh pr view "$n" --repo "$GITHUB_REPOSITORY" --json merged -q .merged)" = "true" ]; then
+                  echo "#$n merged (completed server-side after timeout)."; return 0
+                fi
+              done
+              echo "ERROR: failed to merge #$n after retries." >&2; return 1
+            }
+            # Merge 3.0 first, then 3.1 (they touch disjoint paths, so no conflicts).
+            merge_pr "$PR_30" "OpenAPI 3.0"
+            merge_pr "$PR_31" "OpenAPI 3.1"
         - name: Preview merge (staged)
           if: ${{ env.GH_AW_SAFE_OUTPUTS_STAGED == 'true' }}
           env:
