From bc513add219499d42a3d43ff05d60d27d9b1ce51 Mon Sep 17 00:00:00 2001 From: Neil Date: Tue, 13 Oct 2026 23:49:51 -0700 Subject: [PATCH 1/3] Require exact-commit PR checks before agent merges --- AGENTS.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 2451994d21a0..e561899965e4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -60,6 +60,14 @@ Fill in [`.github/pull_request_template.md`](./.github/pull_request_template.md) Cover all four concisely. Don't pad or walk the diff. +## Merging Pull Requests + +Before merging, verify that the required checks and aggregate gate in the full PR workflow have passed for the exact current PR commit. For GitHub, identify the `.github/workflows/pr.yml` run and its aggregate `verify`; Mobile Checks is separate and never substitutes for it. Check workflow identity as well as the displayed job name. If the head changes, repeat the check for the new head. + +Pending, failed, cancelled, or missing required checks block agent merges even when repository settings allow them. `gh pr merge --auto` is not proof that CI passed: GitHub may merge immediately when checks are optional. Never use `--admin` or disable protection to bypass a failed check. An explicit user instruction to make an emergency exception overrides this default; otherwise fix the failure or wait. Use `--match-head-commit` to prevent merging a different commit after validation. + +CI changes must exercise the affected checks in the PR. Required check names must be unique across workflows, and workflow changes must preserve the full aggregate's failure handling and conditional job requirements. + # Considerations ## Worktree Safety From b0a7ba258a4295583025abcecea94c8939f7be01 Mon Sep 17 00:00:00 2001 From: Neil Date: Tue, 13 Oct 2026 23:58:56 -0700 Subject: [PATCH 2/3] Give full PR checks a unique required status context --- .github/workflows/pr.yml | 1 + AGENTS.md | 2 +- config/scripts/required-pr-check-name.test.mjs | 17 +++++++++++++++++ 3 files changed, 19 insertions(+), 1 deletion(-) create mode 100644 config/scripts/required-pr-check-name.test.mjs diff --git a/.github/workflows/pr.yml b/.github/workflows/pr.yml index c0c199f88e64..8f603a66f22a 100644 --- a/.github/workflows/pr.yml +++ b/.github/workflows/pr.yml @@ -1479,6 +1479,7 @@ jobs: ref: ${{ github.event.pull_request.head.sha }} verify: + name: PR checks passed if: ${{ !cancelled() }} needs: - code_paths diff --git a/AGENTS.md b/AGENTS.md index e561899965e4..72d507e69d43 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -62,7 +62,7 @@ Cover all four concisely. Don't pad or walk the diff. ## Merging Pull Requests -Before merging, verify that the required checks and aggregate gate in the full PR workflow have passed for the exact current PR commit. For GitHub, identify the `.github/workflows/pr.yml` run and its aggregate `verify`; Mobile Checks is separate and never substitutes for it. Check workflow identity as well as the displayed job name. If the head changes, repeat the check for the new head. +Before merging, verify that the required checks and aggregate gate in the full PR workflow have passed for the exact current PR commit. For GitHub, identify the `.github/workflows/pr.yml` run and its aggregate `PR checks passed` (job ID `verify`); Mobile Checks is separate and never substitutes for it. Check workflow identity as well as the displayed job name. If the head changes, repeat the check for the new head. Pending, failed, cancelled, or missing required checks block agent merges even when repository settings allow them. `gh pr merge --auto` is not proof that CI passed: GitHub may merge immediately when checks are optional. Never use `--admin` or disable protection to bypass a failed check. An explicit user instruction to make an emergency exception overrides this default; otherwise fix the failure or wait. Use `--match-head-commit` to prevent merging a different commit after validation. diff --git a/config/scripts/required-pr-check-name.test.mjs b/config/scripts/required-pr-check-name.test.mjs new file mode 100644 index 000000000000..8475adf1c570 --- /dev/null +++ b/config/scripts/required-pr-check-name.test.mjs @@ -0,0 +1,17 @@ +import { readdirSync, readFileSync } from 'node:fs' +import { join } from 'node:path' +import { expect, it } from 'vitest' +import { parse } from 'yaml' + +it('reserves the required PR checks passed context for the full PR gate', () => { + const directory = '.github/workflows' + const providers = readdirSync(directory) + .filter((file) => /\.ya?ml$/.test(file)) + .flatMap((file) => { + const workflow = parse(readFileSync(join(directory, file), 'utf8')) + return Object.entries(workflow.jobs) + .filter(([id, job]) => (job.name ?? id) === 'PR checks passed') + .map(([id]) => `${file}:${id}`) + }) + expect(providers).toEqual(['pr.yml:verify']) +}) From da45959f0e03fe5e28087e02a4df5202d7082bc7 Mon Sep 17 00:00:00 2001 From: Neil Date: Wed, 14 Oct 2026 00:14:12 -0700 Subject: [PATCH 3/3] Validate required context ownership on every pull request --- .github/scripts/check-required-pr-context.mjs | 27 +++++++++++ .github/workflows/pr.yml | 11 +++++ .../scripts/required-pr-check-name.test.mjs | 45 +++++++++++++------ 3 files changed, 70 insertions(+), 13 deletions(-) create mode 100644 .github/scripts/check-required-pr-context.mjs diff --git a/.github/scripts/check-required-pr-context.mjs b/.github/scripts/check-required-pr-context.mjs new file mode 100644 index 000000000000..f957cb329dfc --- /dev/null +++ b/.github/scripts/check-required-pr-context.mjs @@ -0,0 +1,27 @@ +import { readdirSync, readFileSync } from 'node:fs' +import { join } from 'node:path' +import { pathToFileURL } from 'node:url' + +export function verifyRequiredPrContext(parseYaml) { + const directory = '.github/workflows' + const providers = readdirSync(directory) + .filter((file) => /\.ya?ml$/.test(file)) + .flatMap((file) => { + const workflow = parseYaml(readFileSync(join(directory, file), 'utf8')) + return Object.entries(workflow.jobs) + .filter(([id, job]) => (job.name ?? id) === 'PR checks passed') + .map(([id]) => `${file}:${id}`) + }) + if (providers.length !== 1 || providers[0] !== 'pr.yml:verify') { + throw new Error(`Required PR context must belong only to pr.yml:verify; found ${providers}`) + } +} + +if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) { + const yaml = globalThis.Bun?.YAML + if (!yaml) { + throw new Error('Run workflow context validation with the pinned Bun runtime.') + } + verifyRequiredPrContext(yaml.parse) + console.log('Required PR check context verified.') +} diff --git a/.github/workflows/pr.yml b/.github/workflows/pr.yml index 8f603a66f22a..9308d68a2680 100644 --- a/.github/workflows/pr.yml +++ b/.github/workflows/pr.yml @@ -74,6 +74,9 @@ jobs: /README.md /docs/readme/ /.github/scripts/check-root-directory-entries.mjs + /.github/scripts/check-required-pr-context.mjs + /.github/workflows/ + /config/.bun-version /config/scripts/check-readme-local-links.mjs /config/scripts/pr-code-change-scope.mjs /config/scripts/pr-layout-oracle-route.mjs @@ -94,6 +97,14 @@ jobs: - name: Check README local links run: node config/scripts/check-readme-local-links.mjs + - name: Set up Bun for required workflow validation + uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0 + with: + bun-version-file: config/.bun-version + + - name: Check required PR context ownership + run: bun .github/scripts/check-required-pr-context.mjs + # Readiness changes eligibility for advisory tests, not the already-tested source. - name: Find identical successful required checks id: readiness diff --git a/config/scripts/required-pr-check-name.test.mjs b/config/scripts/required-pr-check-name.test.mjs index 8475adf1c570..79d187ac1182 100644 --- a/config/scripts/required-pr-check-name.test.mjs +++ b/config/scripts/required-pr-check-name.test.mjs @@ -1,17 +1,36 @@ -import { readdirSync, readFileSync } from 'node:fs' -import { join } from 'node:path' +import { readFileSync } from 'node:fs' import { expect, it } from 'vitest' import { parse } from 'yaml' +import { runProcessSync } from '@orca/process-host' +import { verifyRequiredPrContext } from '../../.github/scripts/check-required-pr-context.mjs' -it('reserves the required PR checks passed context for the full PR gate', () => { - const directory = '.github/workflows' - const providers = readdirSync(directory) - .filter((file) => /\.ya?ml$/.test(file)) - .flatMap((file) => { - const workflow = parse(readFileSync(join(directory, file), 'utf8')) - return Object.entries(workflow.jobs) - .filter(([id, job]) => (job.name ?? id) === 'PR checks passed') - .map(([id]) => `${file}:${id}`) - }) - expect(providers).toEqual(['pr.yml:verify']) +it('reserves the required PR context for the full aggregate with both YAML parsers', () => { + expect(() => verifyRequiredPrContext(parse)).not.toThrow() + const result = runProcessSync({ + program: 'bun', + args: ['.github/scripts/check-required-pr-context.mjs'], + env: { ...process.env, ORCA_BACKGROUND_LAUNCH: '1' }, + timeoutMs: 10_000 + }) + expect(result.code, result.stderr).toBe(0) +}) + +it('checks context names even when workflow-only changes skip root tests', () => { + const workflow = parse(readFileSync('.github/workflows/pr.yml', 'utf8')) + const job = workflow.jobs.code_paths + const step = job.steps.find( + (candidate) => candidate.run === 'bun .github/scripts/check-required-pr-context.mjs' + ) + expect(step).toBeDefined() + expect(job.if).toBeUndefined() + expect(step.if).toBeUndefined() + expect(step['continue-on-error']).toBeUndefined() + const checkout = job.steps.find((candidate) => candidate.uses?.startsWith('actions/checkout@')) + for (const path of [ + '/.github/workflows/', + '/.github/scripts/check-required-pr-context.mjs', + '/config/.bun-version' + ]) { + expect(checkout.with['sparse-checkout'].split('\n')).toContain(path) + } })