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
27 changes: 27 additions & 0 deletions .github/scripts/check-required-pr-context.mjs
Original file line number Diff line number Diff line change
@@ -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.')
}
12 changes: 12 additions & 0 deletions .github/workflows/pr.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -1479,6 +1490,7 @@ jobs:
ref: ${{ github.event.pull_request.head.sha }}

verify:
name: PR checks passed
if: ${{ !cancelled() }}
needs:
- code_paths
Expand Down
8 changes: 8 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
48 changes: 32 additions & 16 deletions config/scripts/required-pr-check-name.test.mjs
Original file line number Diff line number Diff line change
@@ -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)
Comment thread
nwparker marked this conversation as resolved.
Resolved
})

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)
}
})
Loading