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 c0c199f88e64..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 @@ -1479,6 +1490,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 2451994d21a0..72d507e69d43 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 `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. + +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 diff --git a/config/scripts/required-pr-check-name.test.mjs b/config/scripts/required-pr-check-name.test.mjs index 0bf763add085..79d187ac1182 100644 --- a/config/scripts/required-pr-check-name.test.mjs +++ b/config/scripts/required-pr-check-name.test.mjs @@ -1,20 +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 verify check 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')) - if (!Object.hasOwn(workflow.on ?? {}, 'pull_request')) { - return [] - } - return Object.entries(workflow.jobs) - .filter(([id, job]) => (job.name ?? id) === 'verify') - .map(() => file) - }) - expect(providers).toEqual(['pr.yml']) +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) + } })