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

Expand Down
9 changes: 8 additions & 1 deletion .github/workflows/dependency-review.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down
17 changes: 16 additions & 1 deletion .github/workflows/pr-title.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -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:
Expand All @@ -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:
Expand Down Expand Up @@ -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 }}
Expand Down
25 changes: 25 additions & 0 deletions docs/docs/developer/ci-performance.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`
Expand Down
36 changes: 34 additions & 2 deletions docs/docs/developer/repository-governance.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
35 changes: 34 additions & 1 deletion scripts/ci-impact-plan.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -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/") ||
Expand Down Expand Up @@ -68,6 +86,7 @@ export function createImpactPlan({
pathsComplete = true,
regularFiles = true,
approvedScopes = [],
approvedMergeQueueGroups = [],
closedPr = false,
rolloutCommit = "",
validationSource = null,
Expand Down Expand Up @@ -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,
Expand All @@ -141,6 +165,7 @@ export function createImpactPlan({
.update(JSON.stringify([...(paths ?? [])].sort()))
.digest("hex"),
jobs,
deferredDatabaseGroups,
};
}

Expand Down Expand Up @@ -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");
Expand Down Expand Up @@ -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.
Expand All @@ -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. */
}
Expand Down Expand Up @@ -340,6 +372,7 @@ if (import.meta.main) {
regularFiles,
validationSource,
approvedScopes,
approvedMergeQueueGroups,
rolloutCommit,
closedPr: pr?.state === "closed",
baseChanged: !!event.changes?.base,
Expand Down Expand Up @@ -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,
Expand Down
Loading
Loading