Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
95 changes: 87 additions & 8 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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'"
Expand Down Expand Up @@ -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:
Expand All @@ -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 }}

Expand All @@ -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"
Expand All @@ -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
Expand Down
3 changes: 3 additions & 0 deletions .github/workflows/codeql-analysis.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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"

Expand Down
41 changes: 38 additions & 3 deletions .github/workflows/pr-title-lint.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
30 changes: 27 additions & 3 deletions docs/maintainers/ci.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -43,15 +44,38 @@ 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
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
Expand Down
2 changes: 2 additions & 0 deletions docs/maintainers/project-services.md
Original file line number Diff line number Diff line change
Expand Up @@ -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).
18 changes: 13 additions & 5 deletions tools/check_project_services.py
Original file line number Diff line number Diff line change
Expand Up @@ -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]+")


Expand Down Expand Up @@ -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",
Expand Down Expand Up @@ -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)
Expand Down
15 changes: 15 additions & 0 deletions tools/tests/test_project_services.py
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
Loading