ci: Preserve Gitflow merge commits with the develop queue

.github/workflows/build.yml

@@ -10,7 +10,7 @@ on:
       - release/**
   pull_request:
   merge_group:
-    types: [checks_requested]
+    branches: [develop]
   workflow_dispatch:
     inputs:
       commit:

.github/workflows/enforce-license-compliance.yml

@@ -16,6 +16,8 @@ on:
       - v10
       - v9
       - v8
+  merge_group:
+    branches: [develop]
 
 jobs:
   enforce-license-compliance:

.github/workflows/gitflow-sync-develop.yml

@@ -21,6 +21,8 @@ jobs:
     permissions:
       pull-requests: write
       contents: write
+      checks: read
+      statuses: read
     steps:
       - name: git checkout
         uses: actions/checkout@v7
@@ -44,16 +46,29 @@ jobs:
           pr_label: 'Dev: Gitflow'
           github_token: ${{ steps.app-token.outputs.token }}
 
-      - name: Enable automerge for PR
-        if: steps.open-pr.outputs.pr_number != ''
-        run: gh pr merge --merge --auto "${{ steps.open-pr.outputs.pr_number }}"
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-
       # https://github.com/marketplace/actions/auto-approve
       - name: Auto approve PR
         if: steps.open-pr.outputs.pr_number != ''
         uses: hmarr/auto-approve-action@v4
         with:
           pull-request-number: ${{ steps.open-pr.outputs.pr_number }}
           review-message: 'Auto approved automated PR'
+
+      - name: Wait for checks and merge backmerge
+        if: steps.open-pr.outputs.pr_number != ''
+        timeout-minutes: 45
+        shell: bash
+        env:
+          GH_REPO: ${{ github.repository }}
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GITFLOW_TOKEN: ${{ steps.app-token.outputs.token }}
+          PR_NUMBER: ${{ steps.open-pr.outputs.pr_number }}
+        run: |
+          backmerge_head=$(gh pr view "$PR_NUMBER" --json headRefOid --jq .headRefOid)
+
+          gh pr checks "$PR_NUMBER" --required --watch --fail-fast --interval 30
+
+          GH_TOKEN="$GITFLOW_TOKEN" gh pr merge "$PR_NUMBER" \
+            --merge \
+            --admin \
+            --match-head-commit "$backmerge_head"

docs/gitflow.md

@@ -13,6 +13,14 @@ We use [Gitflow](https://docs.github.com/en/get-started/quickstart/github-flow)
 
 ![gitflow-chart](./assets/gitflow-chart.png)
 
+PRs into `develop` normally merge through the squash merge queue.
+Release backmerges from `master` use merge commits to preserve Git history.
+The Gitflow automation waits for required checks, then merges through the
+Gitflow App's queue-only bypass. Required checks and approvals still apply.
+
+If the backmerge workflow fails or times out, resolve the blocker and rerun
+the failed job.
+
 ## Important Caveats
 
 While a release is pending, we may merge anything into develop, **except for changes to package.json files**. If we
@@ -30,4 +38,7 @@ If this happen, you can resolve this as follows:
 - Create a new branch on top of `master` (e.g. `manual-develop-sync`)
 - Merge `develop` into this branch, with a merge commit (and fix any merge conflicts that come up)
 - Now create a PR against `develop` from your branch (e.g. `manual-develop-sync`)
-- Merge this PR with a merge commit
+- Wait for required checks and approval on the replacement PR.
+- Have a release maintainer with queue-bypass permission merge the PR directly,
+  choosing **Create a merge commit**. Do not add it to the squash merge queue.
+  Bypass only the queue requirement; required checks and approvals still apply.