Skip to content
Merged
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
4 changes: 3 additions & 1 deletion .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,8 @@ on:
push:
branches: [main]
pull_request:
merge_group:
types: [checks_requested]
workflow_dispatch:
inputs:
full_mutation:
Expand Down Expand Up @@ -48,7 +50,7 @@ env:
# Scheduled/full-manual runs use unique groups: cancel=false alone still replaces pending runs.
# Release validation is isolated; the separate publisher retains its publication lock.
concurrency:
group: ci-${{ (inputs.ref != '' || inputs.release_tag != '') && format('release-{0}-{1}', inputs.release_tag, inputs.ref) || github.event_name == 'schedule' && format('scheduled-{0}', github.run_id) || github.event_name == 'workflow_dispatch' && inputs.full_mutation == true && format('full-{0}', github.run_id) || format('validation-{0}', github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name != github.repository && format('fork-pr-{0}', github.event.pull_request.number) || github.head_ref != '' && format('refs/heads/{0}', github.head_ref) || github.ref) }}
group: ci-${{ (inputs.ref != '' || inputs.release_tag != '') && format('release-{0}-{1}', inputs.release_tag, inputs.ref) || github.event_name == 'merge_group' && format('queue-{0}', github.sha) || github.event_name == 'schedule' && format('scheduled-{0}', github.run_id) || github.event_name == 'workflow_dispatch' && inputs.full_mutation == true && format('full-{0}', github.run_id) || format('validation-{0}', github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name != github.repository && format('fork-pr-{0}', github.event.pull_request.number) || github.head_ref != '' && format('refs/heads/{0}', github.head_ref) || github.ref) }}
cancel-in-progress: ${{ inputs.ref == '' && inputs.release_tag == '' && github.event_name != 'schedule' && !(github.event_name == 'workflow_dispatch' && inputs.full_mutation == true) }}

jobs:
Expand Down
58 changes: 57 additions & 1 deletion .github/workflows/pr-title.yml
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,8 @@ name: PR title
on:
pull_request_target:
types: [opened, edited, reopened, synchronize]
merge_group:
types: [checks_requested]
workflow_dispatch:
inputs:
pr_number:
Expand All @@ -21,7 +23,7 @@ jobs:
steps:
# Only inspect PR metadata. Never check out or execute pull-request code here.
- uses: amannn/action-semantic-pull-request@48f256284bd46cdaab1048c3721360e808335d50 # v6.1.1
if: github.event_name != 'workflow_dispatch'
if: github.event_name == 'pull_request_target'
env:
GITHUB_TOKEN: ${{ github.token }}
with:
Expand All @@ -37,6 +39,60 @@ jobs:
ci
chore
revert
- name: Validate the exact queued candidate using metadata only
if: github.event_name == 'merge_group'
env:
GH_TOKEN: ${{ github.token }}
GH_REPO: ${{ github.repository }}
run: |
node --input-type=module <<'JS'
import assert from 'node:assert/strict';
import { execFileSync } from 'node:child_process';
import { readFileSync } from 'node:fs';
const repo = process.env.GH_REPO;
assert.match(repo, /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/);
const event = JSON.parse(readFileSync(process.env.GITHUB_EVENT_PATH, 'utf8'));
assert.equal(event.action, 'checks_requested');
assert.equal(event.repository.full_name, repo);
const group = event.merge_group;
assert.equal(group.base_ref, 'refs/heads/main');
assert.equal(group.head_sha, process.env.GITHUB_SHA);
assert.match(group.head_sha, /^[0-9a-f]{40}$/);
assert.match(group.base_sha, /^[0-9a-f]{40}$/);
const [owner, name] = repo.split('/');
const query = `query($owner:String!,$name:String!,$endCursor:String) {
repository(owner:$owner,name:$name) {
pullRequests(states:OPEN,baseRefName:"main",first:100,after:$endCursor) {
pageInfo { hasNextPage endCursor }
nodes { number title state baseRefName headRefOid repository { nameWithOwner }
mergeQueueEntry { headCommit { oid } baseCommit { oid } }
}
}
}
}`;
const pages = JSON.parse(execFileSync('gh', [
'api', 'graphql', '--paginate', '--slurp', '-f', `query=${query}`,
'-f', `owner=${owner}`, '-f', `name=${name}`,
], { encoding: 'utf8' }));
assert.ok(Array.isArray(pages) && pages.length > 0, 'Queue metadata unavailable');
const prs = pages.flatMap((page) => {
assert.ok(!page.errors, 'Queue metadata query failed');
const nodes = page.data.repository.pullRequests?.nodes;
assert.ok(Array.isArray(nodes), 'Pull request metadata unavailable');
return nodes;
});
const matches = prs.filter((pr) => pr.mergeQueueEntry?.headCommit?.oid === group.head_sha);
assert.equal(matches.length, 1, 'Exactly one current queue candidate is required');
const pr = matches[0];
const entry = pr.mergeQueueEntry;
assert.equal(entry.baseCommit?.oid, group.base_sha, 'Queue candidate base changed');
assert.equal(pr.state, 'OPEN');
assert.equal(pr.baseRefName, 'main');
assert.equal(pr.repository.nameWithOwner, repo);
assert.ok(Number.isSafeInteger(pr.number) && pr.number > 0);
assert.match(pr.headRefOid, /^[0-9a-f]{40}$/);
assert.match(pr.title, /^(feat|fix|perf|docs|style|refactor|test|build|ci|chore|revert)(?:\([^\r\n()]+\))?!?: \S[^\r\n]*$/, 'Queued PR title must be a Conventional Commit');
JS
- name: Validate a dispatched release PR using metadata only
if: github.event_name == 'workflow_dispatch'
env:
Expand Down
5 changes: 3 additions & 2 deletions .github/workflows/release-please.yml
Original file line number Diff line number Diff line change
Expand Up @@ -76,9 +76,10 @@ jobs:
}
appendFileSync(process.env.GITHUB_STEP_SUMMARY, [
'## Release PR validation', '', ...rows, '',
'After the intended main-branch changes are complete, review the current release PR head.',
'A maintainer can close and reopen the PR to trigger native CI and metadata-only title validation; if it is behind main, Update branch also triggers them.',
'Review the current release PR head. A maintainer can close and reopen the PR once to trigger native CI and metadata-only title validation.',
'Review any Approve workflows to run prompt. Confirm All checks and Conventional Commit PR title pass in the PR checks before merging.',
'After the reviewed merge queue configuration is activated, add the PR to the native main merge queue. A branch behind main does not need Update branch: GitHub validates the integrated queue candidate.',
'Queueing uses the maintainer account; GITHUB_TOKEN cannot enqueue it. A real Release Please head change or a failed check needs review and requeueing.',
'workflow_dispatch checks do not satisfy PR rulesets. This summary does not approve workflows, and workflow approval does not merge or publish.',
'Final publication still requires the separate owner approval in the release environment.', '',
].join('\n'));
Expand Down
16 changes: 14 additions & 2 deletions docs/governance.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@
| Squash-only merging, read-only workflow token, SHA-pinned selected actions | Enforced |
| `main`: pull request, `All checks` and PR-title checks, up-to-date branch | Enforced by the `main` ruleset; no bypass |
| `main`: resolved conversations, linear history, no force push | Enforced by the `main` ruleset; no bypass |
| `main`: native merge queue | Proposed in Terraform; live activation and acceptance pending |
| Release tags cannot move or be deleted | Enforced by the `release-tags` ruleset and immutable releases |
| One approval from the release approver before publication | Enforced by the `release` environment; administrators cannot bypass it |
| Build provenance, release attestations, secret scanning with push protection | On |
Expand Down Expand Up @@ -170,9 +171,9 @@ Neither administrators nor automation can bypass the rulesets. If a broken requi
The `main` ruleset in [`rulesets.tf`](../governance/rulesets.tf):

- **No routine approving review.** A pull request is required but needs 0 approvals: this repository has one maintainer, who cannot approve their own pull request. Conversations must be resolved; stale approvals are dismissed.
- **Checks.** `All checks` and `Conventional Commit PR title` must pass, both from the GitHub Actions app (ID 15368), against a branch that is up to date with `main`.
- **Checks.** `All checks` and `Conventional Commit PR title` must pass, both from the GitHub Actions app (ID 15368). Strict required checks remain enabled; after queue activation GitHub validates the integrated queue candidate against `main` without requiring repeated updates to the PR branch.
- **History.** Force pushes and deletion are blocked and history must be linear. Squash is the only merge method.
- **No merge queue,** because one maintainer gains nothing from one.
- **Native merge queue, pending activation.** `SQUASH`, `ALLGREEN`, one entry building and one merging at a time, minimum one entry, no batching wait, and a 180-minute check timeout. Later PRs wait behind the candidate instead of making the maintainer repeatedly update its branch. The timeout accommodates the mutation job and its prerequisites.
- **No bypass actors.**
- GitHub's default "additional approval for unattributed Copilot pull requests" stays on; the provider cannot manage it, and it has no effect while 0 approvals are required.

Expand All @@ -183,12 +184,15 @@ The `main` ruleset in [`rulesets.tf`](../governance/rulesets.tf):
- its name is not unique across workflows, including filtered and manually dispatched workflows, or it is a matrix or reusable-workflow job rather than one direct job;
- it can be skipped, through a condition other than `always()` or through `needs` without `always()`; equivalent whitespace around the expression and its optional `${{ }}` delimiters is accepted;
- its workflow does not run on `pull_request` or `pull_request_target`;
- its workflow does not also admit `merge_group` with `checks_requested`;
- its workflow filters by paths, ignores branches, or has a branch filter other than exactly `[main]`;
- its event `types` omit `opened`, `synchronize` or `reopened`; the title check must also include `edited` so a title-only change is revalidated;
- the aggregate is not required or not unique, does not run with `always()`, or does not need every other job in its workflow.

The contract inspects the aggregate's `if` and `needs`; it is not a general Actions expression evaluator and does not prove step behavior. Its step in `ci.yml` fails on any child result other than success, including cancelled and skipped. Positive and negative fixtures exercise the supported forms and rejection rules. Renaming a check requires updating its variables and tests together or the `Governance` workflow fails on that pull request. The standalone `Governance` check is not separately required by name: governance validation is required through the fail-closed `All checks` aggregate, so its failure blocks merging.

Both required workflows handle `merge_group`. CI tests the event's queue SHA in a separate concurrency group; an ordinary PR or `main` run cannot cancel it. The title job uses live GraphQL queue metadata to require exactly one entry whose `headCommit` and `baseCommit` match the event, then validates that entry's PR title. It has no checkout. Missing or changed bindings fail closed. The post-merge audit still checks admission evidence on the original PR head; GitHub's ruleset enforces checks on the integrated queue candidate.

**Release PRs require eligible native events.** A `workflow_dispatch` run, even
green on the exact head, does **not** satisfy PR ruleset checks. Follow the
[release PR validation procedure](releasing.md#automated-path) and
Expand All @@ -197,6 +201,14 @@ events and workflow-execution approval. Those actions do not authorize publicati
GitHub documents [token-generated events](https://docs.github.com/en/actions/how-tos/write-workflows/choose-when-workflows-run/trigger-a-workflow#triggering-a-workflow-from-a-workflow)
and [required-check event eligibility](https://docs.github.com/en/pull-requests/how-tos/merge-and-close-pull-requests/troubleshooting-required-status-checks#checks-from-some-workflow-jobs-are-not-evaluated).

### Activate and verify the queue

This change does **not** apply live settings. After its PR merges, separately authorize the operator procedure: plan against the existing state, review the addition to `github_repository_ruleset.main[0]` (live ruleset **25840882**), then explicitly approve that plan before applying it. Import that existing ruleset first if it is absent from local state; do not create a second ruleset. Retain strict checks and their app bindings, zero required PR approvals, stale-review dismissal, resolved conversations, history protections, no bypass, tag protections, and the single owner environment approval. The pinned provider 6.13.0 already supports the queue; no provider or credential change is required.

After applying, queue two harmless ordinary PRs in FIFO order, with the second arriving while the first candidate validates. Confirm the first merges without a PR-branch update, both required checks identify its queue SHA, and the second follows. Confirm a failed required check prevents merging, and missing/stale queue metadata fails the title regression. Record the live settings and run evidence; do not use a release PR or publish during this acceptance check. Until activation is verified, the existing strict branch-update behavior remains in force.

This follows GitHub's [native queue model](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-a-merge-queue), also used by the pinned Release Please action's own [CI](https://github.com/googleapis/release-please-action/blob/45996ed1f6d02564a971a2fa1b5860e934307cf7/.github/workflows/ci.yaml). A separate stable release branch was considered: Release Please supports it, but it adds another protected branch and backport process and would require changing the publisher's existing `main`-ancestor contract.

## Release approval

Final publication waits for exactly one approval from the release approver, `choskeli` (user ID 98036866). The `release` environment in [`environment.tf`](../governance/environment.tf):
Expand Down
Loading
Loading