diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index eb5d3783d..7dd6d7eb4 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -4,6 +4,11 @@ on: workflow_dispatch: pull_request: types: [opened, synchronize, reopened, edited] + # The merge queue tests each pull request on top of main and of the entries + # ahead of it. Such a run is never narrowed: it gets the complete validation + # that main gets, including the database groups a pull request may defer. + merge_group: + types: [checks_requested] push: branches: [main] # Reconcile main daily, including merges made with GITHUB_TOKEN that do not @@ -856,6 +861,8 @@ jobs: path: ${{ runner.temp }}/database-shards - name: Require the complete disjoint database inventory if: needs.select.outputs.code == 'true' && needs.select.outputs.database == 'true' + env: + CI_PLAN: ${{ needs.select.outputs.plan }} run: node scripts/database-test-shards.mjs verify "${{ runner.temp }}/database-shards" - name: Collect Linux deployment-user receipts if: needs.select.outputs.code == 'true' && needs.select.outputs['test-linux-user'] == 'true' diff --git a/.github/workflows/cla.yml b/.github/workflows/cla.yml index ead4dc39c..4ff695bf2 100644 --- a/.github/workflows/cla.yml +++ b/.github/workflows/cla.yml @@ -5,6 +5,10 @@ on: types: [created] pull_request_target: # zizmor: ignore[dangerous-triggers] trusted base workflow; never checks out PR code types: [opened, closed, synchronize] + # Required check on main. Every pull request in a merge-queue entry passed + # the signature check before it was queued, so the job reports without it. + merge_group: + types: [checks_requested] # Least-privilege default: read-only at the top level. The cla job escalates to # the writes it needs. pull_request_target runs in the base repo's context, so @@ -16,6 +20,7 @@ jobs: cla: if: >- github.event_name == 'pull_request_target' || + github.event_name == 'merge_group' || (github.event.issue.pull_request && (github.event.comment.body == 'recheck' || github.event.comment.body == 'I have read the CLA Document and I hereby sign the CLA')) @@ -30,7 +35,12 @@ jobs: pull-requests: write statuses: write steps: + - name: Report for the merge queue + if: github.event_name == 'merge_group' + run: echo "Signatures were checked before this entry was queued." + - name: CLA Assistant + if: github.event_name != 'merge_group' # OpenMapX fork of the (archived) contributor-assistant/github-action, # bumped to the Node 24 runtime. See OpenMapX/cla-assistant-action. uses: OpenMapX/cla-assistant-action@3e864d0e9c7ec7a7fc4eb36e78ff857b1db7978c # v2.6.1-node24 diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml index a721354a9..d3fb77e7c 100644 --- a/.github/workflows/codeql.yml +++ b/.github/workflows/codeql.yml @@ -5,6 +5,10 @@ on: branches: [main] # Include stacked PRs so each layer is scanned before its parent is merged. pull_request: + # Required check and code-scanning rule on main: both need a result for the + # commit the merge queue is about to land. + merge_group: + types: [checks_requested] schedule: - cron: "23 6 * * 1" diff --git a/.github/workflows/dependency-review.yml b/.github/workflows/dependency-review.yml index 957cd9110..faae67b97 100644 --- a/.github/workflows/dependency-review.yml +++ b/.github/workflows/dependency-review.yml @@ -2,6 +2,9 @@ name: Dependency Review on: pull_request: + # Required check on main: review the merge queue's commit against its base. + merge_group: + types: [checks_requested] permissions: contents: read @@ -25,7 +28,11 @@ jobs: with: # Block PRs that introduce known-vulnerable dependencies. fail-on-severity: high - comment-summary-in-pr: on-failure + # A merge-queue run has no pull request to comment on and names the + # commits to compare itself. + comment-summary-in-pr: ${{ github.event_name == 'pull_request' && 'on-failure' || 'never' }} + base-ref: ${{ github.event.merge_group.base_sha || '' }} + head-ref: ${{ github.event.merge_group.head_sha || '' }} # License policy note: the product is AGPL-3.0-or-later (copyleft deps are # fine there) while the packages/* substrate is Apache-2.0. dependency-review # cannot scope a policy per package, so we surface licenses for review rather diff --git a/.github/workflows/pr-title.yml b/.github/workflows/pr-title.yml index 32b4c9278..f371b5cb9 100644 --- a/.github/workflows/pr-title.yml +++ b/.github/workflows/pr-title.yml @@ -3,6 +3,11 @@ name: PR metadata on: pull_request_target: # zizmor: ignore[dangerous-triggers] trusted metadata validation; never checks out PR code types: [opened, edited, synchronize, reopened] + # Required check on main. A merge-queue entry has no title or description of + # its own: every pull request in it passed this validation before it was + # queued, so the job reports without repeating it. + merge_group: + types: [checks_requested] # Least-privilege default; the validate job escalates to what the action needs. permissions: @@ -11,7 +16,7 @@ permissions: # Never let a cancelled/out-of-order metadata job replace the newest required # result. A later edit waits for the current validator, independently of code CI. concurrency: - group: pr-metadata-${{ github.event.pull_request.number }} + group: pr-metadata-${{ github.event.pull_request.number || github.run_id }} cancel-in-progress: false jobs: @@ -30,7 +35,12 @@ jobs: pull-requests: write statuses: write steps: + - name: Report for the merge queue + if: github.event_name == 'merge_group' + run: echo "Pull request metadata was validated before this entry was queued." + - uses: amannn/action-semantic-pull-request@2252a14e810aa9b85c2d560bd7070c802206ecf6 # v6.1.2 + if: github.event_name != 'merge_group' env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} with: @@ -60,17 +70,22 @@ jobs: # Only default-branch code/dependencies execute. Candidate commits are Git # objects read by the validator, never a checkout, lifecycle script or import. - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + if: github.event_name != 'merge_group' with: ref: ${{ github.event.repository.default_branch }} fetch-depth: 0 persist-credentials: false - uses: pnpm/action-setup@73e46992e05b19abd31f2f3c20e0e7370d762115 # v6.1.1 + if: github.event_name != 'merge_group' - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0 + if: github.event_name != 'merge_group' with: node-version-file: .nvmrc cache: pnpm - run: pnpm install --filter . --frozen-lockfile --ignore-scripts + if: github.event_name != 'merge_group' - name: Validate current release classification with trusted code + if: github.event_name != 'merge_group' env: GH_TOKEN: ${{ github.token }} PR_NUMBER: ${{ github.event.pull_request.number }} diff --git a/docs/docs/developer/ci-performance.md b/docs/docs/developer/ci-performance.md index 758dd6708..f303c9c89 100644 --- a/docs/docs/developer/ci-performance.md +++ b/docs/docs/developer/ci-performance.md @@ -335,6 +335,31 @@ The dependency review behind `client`, on revision `f86338349`: instead of on the pull request. This is the one input of a skipped job that `client` admits. +## Merge queue and deferred database groups + +CI runs for `merge_group` with the complete plan: scope `full` and every database +group, exactly as on `main`. The pull-request-only Docker build is skipped, as it +is on `main`. + +`crash-points`, `configuration-recovery` and `coordinator-recovery` are 12 of a +full run's database jobs and about 144 of its roughly 250 job-minutes (latest +runs before 16 November 2026). They start the real API, operations agent and +data-manager, so no path rule can tell when they are unaffected: replayed on the +last 80 merged pull requests, an import-graph rule would have saved about 12% of +the database job time. + +A pull request may instead leave those groups to the merge queue. The selector +drops a group from a pull request's database matrix when trusted main's +`scripts/ci-impact-rollout.json` lists it in `mergeQueueDatabaseGroups`. Only +those three groups can be listed. The plan records the result as +`deferredDatabaseGroups`; the aggregate gate checks the shard receipts against +the same plan and rejects a deferral on any event other than `pull_request`. +Merge-queue, `main`, scheduled and manual runs always run every group. + +The list is empty until the ruleset requires the merge queue. With the list set +and no queue, a recovery regression would be found on `main` after the merge +instead of before it. + ## Stopping a pull request's run after a lint failure When the `lint` job fails on a pull request, the `stop run after lint failure` diff --git a/docs/docs/developer/repository-governance.md b/docs/docs/developer/repository-governance.md index 6c8c49d17..b5ae2f444 100644 --- a/docs/docs/developer/repository-governance.md +++ b/docs/docs/developer/repository-governance.md @@ -25,8 +25,8 @@ Only squash merges are allowed. The PR title and body become the default squash commit message; review both and preserve attribution and trailers. Required checks use the loose policy: branches do not need updating after each -merge to `main`. There is no merge queue. Post-merge CI checks the combined -result and gates image publication. Repair a failing `main` before continuing +merge to `main`. A [merge queue](#merge-queue) is prepared but not yet required. +Post-merge CI checks the combined result and gates image publication. Repair a failing `main` before continuing unrelated merges. The required title check also validates current release classification using trusted @@ -78,6 +78,38 @@ Missing or unfinished required analysis must not be treated as approval: retain both the app-bound completion check and the native rule, and use only the incident-specific recovery procedure below when necessary. +## Merge queue + +The five required workflows also run for the `merge_group` event, so the ruleset +can require a merge queue without a check staying pending. A queue entry is +main plus the entries ahead of it plus one pull request. CI gives it the +complete validation that main gets; `Validate conventional commit title` and +`check / record signature` report without repeating work that needs a pull +request, because every queued pull request already passed them. + +Enable it in the `main protection` ruleset with **Require merge queue**: + +| Setting | Value | Reason | +| -------------------- | ---------- | ----------------------------------------------------------------------- | +| Merge method | Squash | The only allowed method. | +| Build concurrency | 2 | Two entries fit beside pull-request runs under the hosted-runner limit. | +| Maximum group size | 1 | Each pull request passes or fails on its own. | +| Status check timeout | 90 minutes | The longest database job timeout. | + +Then merge with **Merge when ready** or `gh pr merge`. A failing entry leaves +the queue and `main` does not move. + +Once the queue is required, pull requests may leave the recovery database groups +to it. List them in `mergeQueueDatabaseGroups` in `scripts/ci-impact-rollout.json`; +only the copy on `main` is read. See +[Measuring CI performance](ci-performance.md#merge-queue-and-deferred-database-groups). +Empty that list before removing the queue requirement, otherwise those groups +run only after a merge. + +The queue's `merge_group` runs have not been observed on this repository yet. +If a required check stays pending for an entry, remove the queue requirement +from the ruleset, merge the fix the previous way and enable it again. + ## Actions and security reporting Actions must use full commit-SHA references, including GitHub-owned and diff --git a/scripts/ci-impact-plan.mjs b/scripts/ci-impact-plan.mjs index 3de8251b1..c855ea860 100644 --- a/scripts/ci-impact-plan.mjs +++ b/scripts/ci-impact-plan.mjs @@ -38,6 +38,24 @@ export const scopeSkippedJobs = { client: ["database", "test-linux-user", "test-agent-image"], }; export const selectiveScopes = Object.keys(scopeSkippedJobs).filter((scope) => scope !== "full"); +/** Database groups a pull request may leave to the merge queue. They take over + * half of a full run's job time and still run on every merge-queue entry, on + * main and on the daily schedule, so nothing reaches a release untested. */ +export const mergeQueueDatabaseGroups = [ + "crash-points", + "configuration-recovery", + "coordinator-recovery", +]; +const deferredGroups = (value) => + Array.isArray(value) && + new Set(value).size === value.length && + value.every((group) => mergeQueueDatabaseGroups.includes(group)); +/** The database partitions this plan requires; verification uses the same list. */ +export function plannedDatabaseMatrix(plan, matrix = databaseMatrix) { + if (!deferredGroups(plan?.deferredDatabaseGroups)) + throw new Error("Missing or invalid deferred database groups"); + return matrix.filter((entry) => !plan.deferredDatabaseGroups.includes(entry.group)); +} const docsProse = (path) => /^docs\/(?:docs|blog)\/.*\.md$/.test(path); const clientSource = (path) => path.startsWith("apps/web/src/") || @@ -68,6 +86,7 @@ export function createImpactPlan({ pathsComplete = true, regularFiles = true, approvedScopes = [], + approvedMergeQueueGroups = [], closedPr = false, rolloutCommit = "", validationSource = null, @@ -117,6 +136,11 @@ export function createImpactPlan({ const proposedScope = scope; if (!Array.isArray(approvedScopes) || !approvedScopes.includes(scope)) scope = "full"; const jobs = jobsForScope(scope); + // Approved on the default branch once the merge queue is required there. + const deferredDatabaseGroups = + event === "pull_request" && jobs.database && deferredGroups(approvedMergeQueueGroups) + ? [...approvedMergeQueueGroups].sort() + : []; return { version: 1, event, @@ -141,6 +165,7 @@ export function createImpactPlan({ .update(JSON.stringify([...(paths ?? [])].sort())) .digest("hex"), jobs, + deferredDatabaseGroups, }; } @@ -190,6 +215,10 @@ export function verifyResults(plan, needs, event) { if (unknown.length) throw new Error(`Unknown aggregate dependencies: ${unknown.join(", ")}`); if (event !== "pull_request" && plan.scope !== "full") throw new Error("Trusted main requires complete validation"); + if (!deferredGroups(plan.deferredDatabaseGroups)) + throw new Error("Missing or invalid deferred database groups"); + if (plan.deferredDatabaseGroups.length && (event !== "pull_request" || !plan.jobs.database)) + throw new Error("Only a pull request may leave database groups to the merge queue"); const expected = jobsForScope(plan.scope); if (validationJobs.some((id) => plan.jobs[id] !== expected[id])) throw new Error("CI job selection does not match its declared scope"); @@ -283,6 +312,7 @@ if (import.meta.main) { } let metadataGateReady = false; let approvedScopes = []; + let approvedMergeQueueGroups = []; let rolloutCommit = ""; try { // Approval is a reviewed default-branch input, never a PR opt-in. @@ -294,6 +324,8 @@ if (import.meta.main) { rollout.approvedScopes.every((scope) => selectiveScopes.includes(scope)) ) approvedScopes = rollout.approvedScopes; + if (rollout.version === 1 && deferredGroups(rollout.mergeQueueDatabaseGroups)) + approvedMergeQueueGroups = rollout.mergeQueueDatabaseGroups; } catch { /* Missing/unknown rollout policy keeps the complete gate. */ } @@ -340,6 +372,7 @@ if (import.meta.main) { regularFiles, validationSource, approvedScopes, + approvedMergeQueueGroups, rolloutCommit, closedPr: pr?.state === "closed", baseChanged: !!event.changes?.base, @@ -367,7 +400,7 @@ if (import.meta.main) { const lines = Object.entries({ plan: JSON.stringify(plan), source: JSON.stringify(receipt), - "database-matrix": JSON.stringify({ include: databaseMatrix }), + "database-matrix": JSON.stringify({ include: plannedDatabaseMatrix(plan) }), code: plan.code, ...plan.jobs, head: plan.head, diff --git a/scripts/ci-impact-plan.test.ts b/scripts/ci-impact-plan.test.ts index d647d0a76..667c6afd5 100644 --- a/scripts/ci-impact-plan.test.ts +++ b/scripts/ci-impact-plan.test.ts @@ -2,6 +2,8 @@ import { readFileSync } from "node:fs"; import { describe, expect, it } from "vitest"; import { createImpactPlan, + mergeQueueDatabaseGroups, + plannedDatabaseMatrix, scopeSkippedJobs, selectiveScopes, validationJobs, @@ -173,6 +175,75 @@ describe("CI applicability and required result enforcement", () => { expect(rollout.version).toBe(1); expect(rollout.approvedScopes).toEqual(["docs", "web", "mobile", "client"]); for (const scope of rollout.approvedScopes) expect(selectiveScopes).toContain(scope); + for (const group of rollout.mergeQueueDatabaseGroups) + expect(mergeQueueDatabaseGroups).toContain(group); + }); + it("leaves approved database groups to the merge queue on pull requests only", () => { + const matrix = [ + { group: "api-privacy", part: 1, total: 1 }, + { group: "crash-points", part: 1, total: 2 }, + { group: "crash-points", part: 2, total: 2 }, + { group: "coordinator-recovery", part: 1, total: 1 }, + ]; + const approved = { approvedMergeQueueGroups: ["crash-points", "coordinator-recovery"] }; + const plan = pr(["packages/core/src/index.ts"], approved); + expect(plan.deferredDatabaseGroups).toEqual(["coordinator-recovery", "crash-points"]); + expect(plannedDatabaseMatrix(plan, matrix)).toEqual([matrix[0]]); + // Without approval on the default branch a pull request runs every group. + const unapproved = pr(["packages/core/src/index.ts"]); + expect(unapproved.deferredDatabaseGroups).toEqual([]); + expect(plannedDatabaseMatrix(unapproved, matrix)).toEqual(matrix); + // The merge queue, main and the schedule are never narrowed. + for (const event of ["merge_group", "push", "schedule", "workflow_dispatch"]) { + const complete = pr(["packages/core/src/index.ts"], { ...approved, event }); + expect(complete.scope, event).toBe("full"); + expect(complete.deferredDatabaseGroups, event).toEqual([]); + expect(plannedDatabaseMatrix(complete, matrix), event).toEqual(matrix); + } + // A scope that already skips the database job defers nothing. + expect(pr(["docs/docs/page.md"], approved).deferredDatabaseGroups).toEqual([]); + // Unknown or repeated groups approve nothing. + for (const approvedMergeQueueGroups of [["api-privacy"], ["crash-points", "crash-points"], {}]) + expect( + pr(["packages/core/src/index.ts"], { approvedMergeQueueGroups }).deferredDatabaseGroups, + ).toEqual([]); + }); + it("rejects a deferral outside a pull request or of a group that must always run", () => { + const results = (plan: ReturnType) => ({ + ...Object.fromEntries( + Object.entries(plan.jobs).map(([id, selected]) => [ + id, + { result: selected ? "success" : "skipped" }, + ]), + ), + "docker-changes": { result: "success", outputs: { apps: "[]" } }, + "docker-build": { result: "skipped" }, + }); + const plan = pr(["packages/core/src/index.ts"], { + approvedMergeQueueGroups: ["crash-points"], + }); + expect(() => verifyResults(plan, results(plan), "pull_request")).not.toThrow(); + for (const deferredDatabaseGroups of [["api-privacy"], ["crash-points", "crash-points"], null]) + expect(() => + verifyResults({ ...plan, deferredDatabaseGroups }, results(plan), "pull_request"), + ).toThrow(/deferred database groups/); + expect(() => + plannedDatabaseMatrix({ ...plan, deferredDatabaseGroups: ["api-privacy"] }), + ).toThrow(); + const queued = pr(["packages/core/src/index.ts"], { event: "merge_group" }); + const queuedResults = { + ...results(queued), + "docker-changes": { result: "skipped" }, + "docker-build": { result: "skipped" }, + }; + expect(() => verifyResults(queued, queuedResults, "merge_group")).not.toThrow(); + expect(() => + verifyResults( + { ...queued, deferredDatabaseGroups: ["crash-points"] }, + queuedResults, + "merge_group", + ), + ).toThrow(/merge queue/); }); it("never narrows trusted main reconciliation or incomplete diffs", () => { expect(Object.values(pr([], { event: "schedule" }).jobs).every(Boolean)).toBe(true); diff --git a/scripts/ci-impact-rollout.json b/scripts/ci-impact-rollout.json index 788f7bb3d..28a950338 100644 --- a/scripts/ci-impact-rollout.json +++ b/scripts/ci-impact-rollout.json @@ -1,4 +1,5 @@ { "version": 1, - "approvedScopes": ["docs", "web", "mobile", "client"] + "approvedScopes": ["docs", "web", "mobile", "client"], + "mergeQueueDatabaseGroups": [] } diff --git a/scripts/ci-scheduling-contract.test.ts b/scripts/ci-scheduling-contract.test.ts index 395613086..2f46f0d26 100644 --- a/scripts/ci-scheduling-contract.test.ts +++ b/scripts/ci-scheduling-contract.test.ts @@ -137,6 +137,48 @@ describe("CI scheduling and context preservation", () => { ci.jobs.types.steps.some((step: { run?: string }) => step.run?.includes("unenforced")), ).toBe(false); }); + it("reports every required check for a merge-queue entry", () => { + const load = (name: string) => + parse(readFileSync(new URL(`../.github/workflows/${name}.yml`, import.meta.url), "utf8")); + // Job names are the required status checks of the main ruleset. + const required = { + ci: ["ci", "lint / types / test"], + "pr-title": ["validate", "Validate conventional commit title"], + // biome-ignore lint/suspicious/noTemplateCurlyInString: Literal GitHub Actions expression. + codeql: ["analyze", "Analyze (${{ matrix.language }})"], + "dependency-review": ["dependency-review", "review dependencies"], + cla: ["cla", "check / record signature"], + }; + for (const [name, [id, check]] of Object.entries(required)) { + const workflow = load(name); + expect(workflow.on.merge_group, name).toEqual({ types: ["checks_requested"] }); + expect(workflow.jobs[id].name, name).toBe(check); + } + // Entries queue behind each other, so no two may share a concurrency group. + const metadata = load("pr-title").concurrency.group; + // Actions reads a missing property as empty; JavaScript needs the object. + const queued = (run_id: number) => ({ github: { run_id, event: { pull_request: {} } } }); + expect(evaluate(metadata, queued(1))).not.toBe(evaluate(metadata, queued(2))); + expect( + evaluate(metadata, { github: { run_id: 1, event: { pull_request: { number: 7 } } } }), + ).toBe(evaluate(metadata, { github: { run_id: 2, event: { pull_request: { number: 7 } } } })); + // The pull-request-only work of the two trusted workflows is not repeated. + for (const [name, id] of [ + ["pr-title", "validate"], + ["cla", "cla"], + ]) { + const steps = load(name).jobs[id].steps as { if?: string }[]; + expect(steps[0].if, name).toBe("github.event_name == 'merge_group'"); + for (const step of steps.slice(1)) + expect(step.if, name).toBe("github.event_name != 'merge_group'"); + } + // The aggregate gate checks the shard inventory against the same plan. + const inventory = ci.jobs.ci.steps.find( + (step: { name?: string }) => step.name === "Require the complete disjoint database inventory", + ); + // biome-ignore lint/suspicious/noTemplateCurlyInString: Literal GitHub Actions expression. + expect(inventory.env.CI_PLAN).toBe("${{ needs.select.outputs.plan }}"); + }); it("checks out only trusted default-branch code for required metadata validation", () => { const workflow = parse( readFileSync(new URL("../.github/workflows/pr-title.yml", import.meta.url), "utf8"), diff --git a/scripts/database-test-shards.mjs b/scripts/database-test-shards.mjs index d7781aaa8..ed84e558b 100644 --- a/scripts/database-test-shards.mjs +++ b/scripts/database-test-shards.mjs @@ -143,15 +143,21 @@ if (import.meta.main) { const receipts = readdirSync(directory) .filter((name) => name.endsWith(".json")) .map((name) => JSON.parse(readFileSync(join(directory, name), "utf8"))); + // A pull request may leave whole groups to the merge queue. The aggregate + // gate separately rejects a plan that defers anything it may not. + const deferred = JSON.parse(process.env.CI_PLAN ?? "{}").deferredDatabaseGroups ?? []; + if (!Array.isArray(deferred)) throw new Error("Invalid deferred database groups"); verifyShardReceipts( receipts, process.argv[2] === "verify-linux" ? [1, 2].map((part) => ({ group: "linux-user", part, total: 2 })) - : databaseMatrix, + : databaseMatrix.filter((entry) => !deferred.includes(entry.group)), process.env.GITHUB_SHA, ); console.log( - "Complete database scenario/file union: every shard present, no loss or duplication.", + deferred.length + ? `Complete union for every required shard; left to the merge queue: ${deferred.join(", ")}.` + : "Complete database scenario/file union: every shard present, no loss or duplication.", ); } catch (error) { console.error(error.message);