From 459ce939263007ea7cd9cb57f6bccf542653d1a7 Mon Sep 17 00:00:00 2001 From: Brad Edwards Date: Wed, 11 Nov 2026 04:19:27 +0100 Subject: [PATCH] ci: run the required dev checks on merge groups The dev merge queue merges a pull request only when each required check reports on the merge group commit. CodeQL, Lint PR title, and PR Gate now run on the merge_group event and do their pull request validation there. Closes #117 --- .github/workflows/ci.yml | 95 ++++++++++++++++++++++++--- .github/workflows/codeql-analysis.yml | 3 + .github/workflows/pr-title-lint.yml | 41 +++++++++++- docs/maintainers/ci.md | 30 ++++++++- docs/maintainers/project-services.md | 2 + tools/check_project_services.py | 18 +++-- tools/tests/test_project_services.py | 15 +++++ 7 files changed, 185 insertions(+), 19 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 57f1a00..f8259de 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -6,6 +6,10 @@ on: tags: ["v*"] pull_request: branches: [main, dev] + # The `dev` merge queue runs the required `PR Gate` again on the merge group + # commit. Branch and path filters do not apply to this event. + merge_group: + types: [checks_requested] schedule: - cron: "23 4 * * 1" workflow_dispatch: @@ -37,6 +41,47 @@ permissions: # command it runs; see docs/maintainers/ci.md for the fast lane, the full gate, # job ownership, and local reproduction. jobs: + # A merge group ref names the queued pull request but not its head branch. + # The Policy job reads the requirement UID from that branch, and the SonarCloud + # job analyzes that pull request. This job reads both from the API. When it + # fails, Policy and SonarCloud do not run, so `PR Gate` fails closed. + queued-pull-request: + name: Queued pull request + if: github.event_name == 'merge_group' + runs-on: ubuntu-latest + timeout-minutes: 5 + permissions: + contents: read + pull-requests: read + outputs: + number: ${{ steps.resolve.outputs.number }} + head-ref: ${{ steps.resolve.outputs.head-ref }} + steps: + - name: Resolve the queued pull request + id: resolve + env: + GH_TOKEN: ${{ github.token }} + QUEUE_REF: ${{ github.event.merge_group.head_ref }} + run: | + set -euo pipefail + pattern='^refs/heads/gh-readonly-queue/dev/pr-([0-9]+)-[0-9a-f]{40}$' + if [[ ! "${QUEUE_REF}" =~ ${pattern} ]]; then + echo "Unexpected merge group ref '${QUEUE_REF}'" >&2 + exit 1 + fi + number="${BASH_REMATCH[1]}" + head_ref="$(gh api "repos/${GITHUB_REPOSITORY}/pulls/${number}" --jq 'select(.base.ref == "dev") | .head.ref')" + if [ -z "${head_ref}" ]; then + echo "Pull request ${number} does not target dev" >&2 + exit 1 + fi + if ! printf '%s\n' "${head_ref}" | grep -Eq '^[A-Za-z0-9._/-]+$'; then + echo "Queued pull request branch '${head_ref}' is not a plain ref name" >&2 + exit 1 + fi + echo "number=${number}" >> "${GITHUB_OUTPUT}" + echo "head-ref=${head_ref}" >> "${GITHUB_OUTPUT}" + fast-checks: name: Fast checks (hygiene + lint) runs-on: ubuntu-latest @@ -59,6 +104,8 @@ jobs: policy: name: Policy + needs: [queued-pull-request] + if: ${{ !cancelled() && (github.event_name != 'merge_group' || needs.queued-pull-request.result == 'success') }} runs-on: ubuntu-latest steps: - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6 @@ -72,7 +119,7 @@ jobs: - name: Resolve requirement UID from branch id: requirement env: - BRANCH: ${{ github.head_ref || github.ref_name }} + BRANCH: ${{ needs.queued-pull-request.outputs.head-ref || github.head_ref || github.ref_name }} run: | REQ_UID="$(printf '%s\n' "$BRANCH" | grep -oE '[A-Z]{3}-[0-9]{3}' | head -n1 || true)" echo "Resolved branch='$BRANCH' uid='$REQ_UID'" @@ -186,9 +233,13 @@ jobs: name: SonarCloud runs-on: ubuntu-latest # Static analysis needs only source + coverage, so it waits on `tests` - # alone rather than the whole verification graph. - needs: [tests] - if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository + # alone rather than the whole verification graph. On a merge group it also + # needs the queued pull request. + needs: [tests, queued-pull-request] + if: >- + ${{ !cancelled() && needs.tests.result == 'success' + && (github.event_name != 'merge_group' || needs.queued-pull-request.result == 'success') + && (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository) }} steps: - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6 with: @@ -197,8 +248,35 @@ jobs: uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4 with: name: coverage + # SonarCloud has no merge queue support. A merge group runs the pull + # request analysis and quality gate for the queued pull request against + # `dev`, on the merge group commit. + - name: Resolve the analysis target + id: target + env: + EVENT_NAME: ${{ github.event_name }} + PULL_REQUEST: ${{ needs.queued-pull-request.outputs.number }} + PULL_REQUEST_BRANCH: ${{ needs.queued-pull-request.outputs.head-ref }} + run: | + set -euo pipefail + if [ "${EVENT_NAME}" != "merge_group" ]; then + echo "args=" >> "${GITHUB_OUTPUT}" + exit 0 + fi + if ! printf '%s\n' "${PULL_REQUEST}" | grep -Eq '^[0-9]+$' || [ -z "${PULL_REQUEST_BRANCH}" ]; then + echo "A merge group analysis requires the queued pull request number and branch" >&2 + exit 1 + fi + if ! printf '%s\n' "${PULL_REQUEST_BRANCH}" | grep -Eq '^[A-Za-z0-9._/-]+$'; then + echo "Queued pull request branch '${PULL_REQUEST_BRANCH}' is not a plain ref name" >&2 + exit 1 + fi + printf 'args=-Dsonar.pullrequest.key=%s -Dsonar.pullrequest.branch=%s -Dsonar.pullrequest.base=dev\n' \ + "${PULL_REQUEST}" "${PULL_REQUEST_BRANCH}" >> "${GITHUB_OUTPUT}" - name: SonarCloud Scan uses: SonarSource/sonarqube-scan-action@299e4b793aaa83bf2aba7c9c14bedbb485688ec4 # v7 + with: + args: ${{ steps.target.outputs.args }} env: SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }} @@ -209,13 +287,14 @@ jobs: # `needs` below — the assertion enforces exactly this list, so an unlisted # job is an unenforced job. Add a job here whenever you add a job above. needs: [fast-checks, policy, tool-tests, typecheck, tests, distributions, docs, sonar] - if: ${{ always() && github.event_name == 'pull_request' }} + if: ${{ always() && (github.event_name == 'pull_request' || github.event_name == 'merge_group') }} runs-on: ubuntu-latest steps: - name: Assert required jobs passed env: NEEDS_JSON: ${{ toJSON(needs) }} - SAME_REPOSITORY: ${{ github.event.pull_request.head.repo.full_name == github.repository }} + # A merge group always comes from this repository. + SAME_REPOSITORY: ${{ github.event_name == 'merge_group' || github.event.pull_request.head.repo.full_name == github.repository }} run: | set -euo pipefail echo "needs: $NEEDS_JSON" @@ -228,8 +307,8 @@ jobs: echo "::error::A required verification job did not succeed" exit 1 fi - # SonarCloud must pass on same-repository PRs and must be skipped on - # fork PRs (no SONAR_TOKEN is exposed to forks). + # SonarCloud must pass on same-repository PRs and merge groups, and + # must be skipped on fork PRs (no SONAR_TOKEN is exposed to forks). sonar_result="$(jq -r '.sonar.result' <<<"$NEEDS_JSON")" if [ "$SAME_REPOSITORY" = "true" ]; then if [ "$sonar_result" != "success" ]; then diff --git a/.github/workflows/codeql-analysis.yml b/.github/workflows/codeql-analysis.yml index f2a8f27..da755c1 100644 --- a/.github/workflows/codeql-analysis.yml +++ b/.github/workflows/codeql-analysis.yml @@ -5,6 +5,9 @@ on: branches: [main, dev] pull_request: branches: [main, dev] + # The `dev` merge queue requires `CodeQL` on the merge group commit. + merge_group: + types: [checks_requested] schedule: - cron: "0 6 * * 0" diff --git a/.github/workflows/pr-title-lint.yml b/.github/workflows/pr-title-lint.yml index 129c462..53cf648 100644 --- a/.github/workflows/pr-title-lint.yml +++ b/.github/workflows/pr-title-lint.yml @@ -8,32 +8,67 @@ name: PR Title Lint on: pull_request: types: [opened, edited, synchronize, reopened] + # The `dev` merge queue requires `Lint PR title` on the merge group commit. + # The check validates the current title of the queued pull request. + merge_group: + types: [checks_requested] permissions: contents: read concurrency: - group: pr-title-lint-${{ github.event.pull_request.number }} + group: pr-title-lint-${{ github.event.pull_request.number || github.ref }} cancel-in-progress: true jobs: title-guard: name: Lint PR title runs-on: ubuntu-latest + permissions: + contents: read + pull-requests: read steps: # Check out the BASE ref, not the PR head, so the policy executable is the # trusted already-merged copy: a PR that edits tools/check_pr_title.py must # not be able to weaken its own required check. - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6 with: - ref: ${{ github.event.pull_request.base.sha }} + ref: ${{ github.event.merge_group.base_sha || github.event.pull_request.base.sha }} - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6 with: python-version: "3.12" + - name: Resolve the queued pull request + # A merge group event carries no pull request. Read the queued pull + # request from the API and write it in the pull_request event shape, so + # the checker validates its current title. + if: github.event_name == 'merge_group' + env: + GH_TOKEN: ${{ github.token }} + QUEUE_REF: ${{ github.event.merge_group.head_ref }} + run: | + set -euo pipefail + pattern='^refs/heads/gh-readonly-queue/dev/pr-([0-9]+)-[0-9a-f]{40}$' + if [[ ! "${QUEUE_REF}" =~ ${pattern} ]]; then + echo "Unexpected merge group ref '${QUEUE_REF}'" >&2 + exit 1 + fi + gh api "repos/${GITHUB_REPOSITORY}/pulls/${BASH_REMATCH[1]}" \ + | jq --arg repository "${GITHUB_REPOSITORY}" \ + 'if .base.ref == "dev" and (.title | type) == "string" then {repository: {full_name: $repository}, pull_request: .} else error("not a dev pull request with a title") end' \ + > "${RUNNER_TEMP}/pull-request-event.json" - name: Validate PR title + env: + EVENT_NAME: ${{ github.event_name }} + EVENT_PATH: ${{ github.event_name == 'merge_group' && format('{0}/pull-request-event.json', runner.temp) || github.event_path }} run: | if [ ! -f tools/check_pr_title.py ]; then + if [ "${EVENT_NAME}" = "merge_group" ]; then + echo "::error::tools/check_pr_title.py is missing on the merge group base" + exit 1 + fi echo "::notice::tools/check_pr_title.py not on the base ref yet; skipping (bootstrap). Enforcement is active for every subsequent PR." exit 0 fi - python tools/check_pr_title.py + # The checker reads the pull request from $GITHUB_EVENT_PATH. On a + # merge group, that is the queued pull request from the step above. + GITHUB_EVENT_PATH="${EVENT_PATH}" python tools/check_pr_title.py diff --git a/docs/maintainers/ci.md b/docs/maintainers/ci.md index 184092b..b70c761 100644 --- a/docs/maintainers/ci.md +++ b/docs/maintainers/ci.md @@ -28,7 +28,8 @@ or docs stages, and each stage reports its own result even when another stage fails. Within **Fast checks**, lint still runs when hygiene fails (`if: !cancelled()`) so one fast-lane failure never hides the other. -`SonarCloud` depends on `tests` **only** (`needs: [tests]`) because static +`SonarCloud` depends on `tests` **only** (`needs: [tests, queued-pull-request]`; +the second job runs only on a merge group) because static analysis needs source plus `coverage.xml` and nothing else — it no longer waits for the whole graph (typecheck, build, docs) to finish before it starts. @@ -43,8 +44,8 @@ stands in for the entire verification graph. reads their results, and fails unless: - **every** verification job succeeded (all `needs` except `sonar`), and -- `SonarCloud` **succeeded** on a same-repository PR, or was **skipped** on a - fork PR (forks never receive `SONAR_TOKEN`). +- `SonarCloud` **succeeded** on a same-repository PR or a merge group, or was + **skipped** on a fork PR (forks never receive `SONAR_TOKEN`). The `needs:` list on `PR Gate` is the gate contract: a verification job that is not listed there is not enforced. **Adding a verification job means adding it to @@ -52,6 +53,29 @@ that list.** Keeping one required check (`PR Gate`) means the parallel jobs can be added, split, or renamed without reconfiguring branch protection, while the protected branches still block on the complete graph. +## The `dev` merge queue + +The `dev` branch uses a GitHub merge queue. The queue merges a pull request +only when each required check reports success on the merge group commit. Thus, +each workflow that produces a required check also runs on the `merge_group` +event: + +| Required check | Workflow | Merge group behavior | +| --- | --- | --- | +| `CodeQL` | `codeql-analysis.yml` | Analyzes the merge group commit. | +| `Lint PR title` | `pr-title-lint.yml` | Reads the queued pull request from the API and validates its current title. | +| `PR Gate` | `ci.yml` | Runs the full verification graph on the merge group commit. | + +A merge group ref names the queued pull request but not its head branch. The +`Queued pull request` job in `ci.yml` reads the head branch from the API. The +`Policy` job reads the requirement UID from that branch. The `SonarCloud` job +runs a pull request analysis of the queued pull request against `dev`, with the +quality gate. If the job cannot resolve the queued pull request, `Policy` and +`SonarCloud` do not run, and `PR Gate` fails. + +`tools/check_project_services.py` makes sure that each of the three workflows +keeps its `merge_group` trigger. + ## Job ownership and sharding Each job maps 1:1 to a `nox` session, so ownership is unambiguous: the session diff --git a/docs/maintainers/project-services.md b/docs/maintainers/project-services.md index 999bab4..e79e3cb 100644 --- a/docs/maintainers/project-services.md +++ b/docs/maintainers/project-services.md @@ -29,3 +29,5 @@ an admin merge and should not be the steady-state release process. The protected `main` and `dev` branches require `CodeQL`, `Lint PR title`, and `PR Gate`. Both branches require an up-to-date pull request, dismiss stale reviews, and prohibit force-pushes and deletion. +The `dev` branch also uses a merge queue. Each required check also runs on the +merge group commit; see [Continuous integration](ci.md#the-dev-merge-queue). diff --git a/tools/check_project_services.py b/tools/check_project_services.py index ecceddd..ccc4060 100644 --- a/tools/check_project_services.py +++ b/tools/check_project_services.py @@ -9,6 +9,9 @@ ACTION_REF_RE = re.compile(r"uses:\s*([^@\s]+)@([^\s#]+)") FULL_SHA_RE = re.compile(r"[0-9a-f]{40}") +# The `dev` merge queue merges a pull request only when each required check +# reports on the merge group commit, so each producer must run on this event. +MERGE_GROUP_TRIGGER = "merge_group:\n types: [checks_requested]" EXACT_REQUIREMENT_RE = re.compile(r"[A-Za-z0-9_.-]+==[^=\s]+") @@ -92,13 +95,16 @@ def _validate_ci(text: str, errors: list[str]) -> None: # The verification graph runs as independent parallel jobs; `PR Gate` is the # single aggregating required check that keeps every stage mandatory before a # protected-branch merge. Pin its contract so no job can silently leave the - # gate: it must depend on every verification job plus Sonar, run on every PR, - # and fail closed unless each verification job succeeded (and Sonar passed on - # same-repository PRs). Adding a verification job means extending this list. + # gate: it must depend on every verification job plus Sonar, run on every PR + # and merge group, and fail closed unless each verification job succeeded + # (and Sonar passed on same-repository PRs and merge groups). Adding a + # verification job means extending this list. for expected in ( "name: PR Gate", + MERGE_GROUP_TRIGGER, "needs: [fast-checks, policy, tool-tests, typecheck, tests, distributions, docs, sonar]", - "if: ${{ always() && github.event_name == 'pull_request' }}", + "if: ${{ always() && (github.event_name == 'pull_request'" + " || github.event_name == 'merge_group') }}", '.value.result == "success"', "A required verification job did not succeed", "SonarCloud did not succeed for a same-repository PR", @@ -205,12 +211,14 @@ def validate_repository(repo_root: Path) -> list[str]: "security-events: write", "languages: python", "queries: security-extended", + MERGE_GROUP_TRIGGER, ): _require(codeql, expected, ".github/workflows/codeql-analysis.yml", errors) _validate_codeql(codeql, errors) title_lint = _read_required(repo_root, ".github/workflows/pr-title-lint.yml", errors) - _require(title_lint, "name: Lint PR title", ".github/workflows/pr-title-lint.yml", errors) + for expected in ("name: Lint PR title", MERGE_GROUP_TRIGGER): + _require(title_lint, expected, ".github/workflows/pr-title-lint.yml", errors) ci = _read_required(repo_root, ".github/workflows/ci.yml", errors) _validate_ci(ci, errors) diff --git a/tools/tests/test_project_services.py b/tools/tests/test_project_services.py index f4defa7..930eb2a 100644 --- a/tools/tests/test_project_services.py +++ b/tools/tests/test_project_services.py @@ -127,6 +127,21 @@ def test_ci_required_job_contract_violation_is_detected(self) -> None: errors, ) + def test_ci_without_merge_group_trigger_is_detected(self) -> None: + errors: list[str] = [] + _validate_ci("name: PR Gate\n", errors) + self.assertIn( + ".github/workflows/ci.yml: missing required configuration: " + "merge_group:\n types: [checks_requested]", + errors, + ) + self.assertIn( + ".github/workflows/ci.yml: missing required configuration: " + "if: ${{ always() && (github.event_name == 'pull_request' " + "|| github.event_name == 'merge_group') }}", + errors, + ) + def test_release_workflow_pypi_credential_is_detected(self) -> None: errors: list[str] = [] _validate_release_workflow("PYPI_API_TOKEN: forbidden\n", errors)