diff --git a/.github/workflows/README.adoc b/.github/workflows/README.adoc index 2a57751..2b65651 100644 --- a/.github/workflows/README.adoc +++ b/.github/workflows/README.adoc @@ -88,3 +88,52 @@ files the contract rejects. The hooks are now thin wrappers over the same canonical tools, run from a standards checkout (`STANDARDS_DIR`), and skip with a notice when none is present. k9iser is retired estate-wide: contracts are authored to `1-formats/k9/spec/K9-CONTRACT-SPEC.adoc`, never generated. + +== `ci-gate.yml` publishes the `CI/gate` status (interim) + +`ci-gate.yml` is a thin caller of the reusable of the same name in +hyperpolymath/proven-cicd-and-workflows. It emits the commit status `CI/gate`, +which the Branch-Floor ruleset requires. It is a commit status, not a check run, +because a reusable's check-run name is ` / ` and can never equal +`CI/gate`. + +* It starts on `pull_request` (job `gate-pr`, same-repository branches only: a + fork's or Dependabot's token cannot write statuses) so the pull request that + adds or changes the gate gets `CI/gate` itself and waits, within a bounded + budget, for the checks the profile names. `gate-pr` runs from the pull + request's own branch, so the tamper guard below is what makes an edit to the + gate visible. +* It also runs on `workflow_run` (`completed` and `in_progress`: a rerun flips the + status to pending, so a stale success never survives), on a 15-minute + `schedule` sweep and on `workflow_dispatch`. GitHub runs those from the copy on + the default branch: a pull request cannot alter that job, its pin or its list. + The job `gate` skips the `pull_request` event. There is no `concurrency:` block, + as in the suite's template: the reusable re-reads the runs before it writes. +* The required-check list is not in this repository. It lives in + `proven-cicd-and-workflows/profiles/ci-gate//.json` at the pinned + SHA. +* It is onboarded in `actions.lock` (workflow key plus a leaf record for the suite + reusable, `ref: main`), because the lock-sync gate requires it. An A3 `estate-gate` replaces it by changing the pin and the + context. + +=== `ci-gate-tamper-guard-caller.yml`: the gate tamper guard + +`ci-gate-tamper-guard-caller.yml` is a thin caller of the suite's reusable +`ci-gate-tamper-guard.yml`, pinned to the same commit as the gate. It runs on +`pull_request_target`, so GitHub uses the default-branch copy and a pull request +cannot edit the guard that judges it; it never checks out or runs pull request +code. A pull request that touches a gate file (`.github/workflows/ci-gate*.yml`, +and `scripts/check-required-contexts.sh`, among the suite's gate files) fails +`guard / check` until the owner applies the label `gate-change-approved` +after the newest commit, and only a repository admin's label counts. + +* Only the owner applies `gate-change-approved`. An agent must never apply it. + It is tamper-evident, not tamper-proof; the suite's `docs/CI-GATE.adoc`, + "Tamper guard", states the limit. +* The guard has a fixed set of protected paths in the suite's script; the caller + takes no `paths` input. In this repository + `.machine_readable/required-contexts-allow.txt` (the `CI/gate => status:` mapping) + is not in that set, so a change to it is not flagged by the guard. +* It is onboarded in `actions.lock` like `ci-gate.yml` (its own workflow key, the + same leaf record for the suite). It is not yet a required context; listing + `guard / check` in the suite's profile is a later round, once the guard is on the default branch. diff --git a/.github/workflows/actions.lock b/.github/workflows/actions.lock index 1789035..950d2eb 100644 --- a/.github/workflows/actions.lock +++ b/.github/workflows/actions.lock @@ -5,6 +5,10 @@ version: 'v0.0.3' workflows: '.github/workflows/build-notification.yml': - 'actions/checkout@v7.0.1' + '.github/workflows/ci-gate-tamper-guard-caller.yml': + - 'hyperpolymath/proven-cicd-and-workflows@d2140a5a789e4ebec52f1bab0074181012660c3b' + '.github/workflows/ci-gate.yml': + - 'hyperpolymath/proven-cicd-and-workflows@d2140a5a789e4ebec52f1bab0074181012660c3b' '.github/workflows/codeql.yml': - 'actions/checkout@v7.0.1' - 'github/codeql-action@9b3254085494b55a0f7c4c2b3d2d52cc712ce370' @@ -194,6 +198,11 @@ dependencies: commit: 'sha1-0f8e8c99d88aeb3fbfd523f1ef2c6f762d10d64d' owner_id: 75048950 repo_id: 623796603 + 'hyperpolymath/proven-cicd-and-workflows@d2140a5a789e4ebec52f1bab0074181012660c3b': + ref: 'main' + commit: 'sha1-d2140a5a789e4ebec52f1bab0074181012660c3b' + owner_id: 6759885 + repo_id: 1326697643 'hyperpolymath/smtp-notify-action@v0.5.1': ref: 'v0.5.1' commit: 'sha1-e384daf6167a7a7567642d6a62060106244d2413' diff --git a/.github/workflows/ci-gate-tamper-guard-caller.yml b/.github/workflows/ci-gate-tamper-guard-caller.yml new file mode 100644 index 0000000..6eb9b3a --- /dev/null +++ b/.github/workflows/ci-gate-tamper-guard-caller.yml @@ -0,0 +1,20 @@ +# SPDX-License-Identifier: MPL-2.0 +# Gate tamper guard - thin caller of the suite's reusable guard; installed as .github/workflows/ci-gate-tamper-guard-caller.yml. pull_request_target runs this file from the +# DEFAULT branch, so a pull request cannot edit it; the job never checks out or runs pull request code +# (it reads the changed-file list through the API). The pin is a full SHA, never @main or a tag. +# A pull request that touches gate files fails this check until the OWNER applies the label +# `gate-change-approved` after the newest commit. AGENTS MUST NEVER APPLY THAT LABEL. +# No `secrets:` line, minimal permissions. See docs/CI-GATE.adoc, "Tamper guard". +name: Gate tamper guard + +on: + pull_request_target: + types: [opened, reopened, synchronize, edited, labeled, unlabeled] + +permissions: + pull-requests: read + contents: read + +jobs: + guard: + uses: hyperpolymath/proven-cicd-and-workflows/.github/workflows/ci-gate-tamper-guard.yml@d2140a5a789e4ebec52f1bab0074181012660c3b # cicd-suite tamper guard diff --git a/.github/workflows/ci-gate.yml b/.github/workflows/ci-gate.yml new file mode 100644 index 0000000..2a71853 --- /dev/null +++ b/.github/workflows/ci-gate.yml @@ -0,0 +1,88 @@ +# SPDX-License-Identifier: MPL-2.0 +# CI gate — thin caller of the estate's interim gate, which lives in +# hyperpolymath/proven-cicd-and-workflows as a reusable workflow. Do not copy +# its jobs in here: a copy freezes at one cicd-suite commit and never receives +# a fix. +# +# It emits the commit status `CI/gate`, which the Branch-Floor ruleset +# requires. It is a COMMIT STATUS, not a check run, because a job inside a +# reusable workflow gets the check-run name ` / ` +# (see rust-ci-caller.yml: `rust-ci / Cargo test`), which always contains +# " / " and can never equal `CI/gate`. +# +# It triggers on workflow_run, schedule and workflow_dispatch, all of which GitHub runs from the +# DEFAULT branch: a pull request cannot alter this file, its pin or its list. The consequence: +# the pull request that adds this caller can never receive `CI/gate` itself, and +# would be merged past the gate once (owner action) without the gate-pr job at the end. There is no +# pull_request start here except the gate-pr job at the end (docs/CI-GATE.adoc, "The pull_request start"), +# whose shape tests/ci-gate.sh asserts. +# +# `schedule` and `workflow_dispatch` run a SWEEP: the reusable lists the open pull requests and the +# default branch head and re-evaluates each distinct head SHA with the same guarded publisher. A stale state +# then normally lasts until the next sweep. It is still last-writer-wins, a sweep is itself an evaluator, +# and GitHub may delay or skip scheduled runs (docs/CI-GATE.adoc, "Residual limit"). The cron below runs at minutes +# 7, 22, 37 and 52 of every hour; keep the minutes off :00 and :30, where scheduled load is highest. +# The sweep reads open pull requests, so the caller must grant `pull-requests: read`. +# +# It also fires when a workflow run STARTS (`in_progress`, which GitHub also sends for a rerun): +# any active run makes the verdict pending, so a rerun replaces a stale success with pending, +# approximating a native required check. `completed` then re-evaluates it (last-writer-wins; see docs/CI-GATE.adoc, "Residual limit"). +# +# The required-check list is NOT in this repository: it lives in +# proven-cicd-and-workflows/profiles/ci-gate//.json at the pinned +# SHA below, selected by github.repository. A repository with no profile there +# fails the gate closed until one is added to the suite. +# +# The job id MUST stay `gate`. The pin is a full SHA, never `@main` or a tag: +# the account enforces sha_pinning_required. An A3 `estate-gate` replaces this +# interim gate by changing ONE pin and ONE context (`with: context`) here. +# +# ONBOARDED in actions.lock (workflow key plus a leaf dependency record for the +# suite reusable) because this repository's lock-sync gate requires every +# job-level reusable ref to be keyed there; see the suite README, "Consumers +# with a lock-sync gate". The record's ref is the symbolic `main`, never the SHA. +# +# There is deliberately NO `concurrency:` block: serialising per SHA would delay the +# in_progress caller behind a running evaluation that then writes a stale success. Instead the +# reusable re-reads the runs just before it writes and re-evaluates when they moved +# (scripts/ci-gate-publish.sh; tests/ci-gate.sh asserts the template has no concurrency). +# +# No `secrets:` line: the reusable consumes none. +name: CI gate + +on: + pull_request: + workflow_run: + workflows: ["**", "!CI gate"] + types: [completed, in_progress] + schedule: + - cron: "7,22,37,52 * * * *" + workflow_dispatch: {} + +permissions: + statuses: write + actions: read + contents: read + pull-requests: read + +jobs: + gate: + if: github.event_name != 'pull_request' && (github.event_name != 'workflow_run' || github.event.workflow_run.name != 'CI gate') + uses: hyperpolymath/proven-cicd-and-workflows/.github/workflows/ci-gate.yml@d2140a5a789e4ebec52f1bab0074181012660c3b # cicd-suite ci-gate + with: + context: "CI/gate" + # timeout_minutes: 180 # how long a missing check keeps the gate pending + + # The pull_request start. workflow_run, schedule and workflow_dispatch run only from the default + # branch, so without this job the pull request that adds or changes the gate never gets the status + # and a ruleset requiring it blocks that very pull request. This job runs from the pull request's own + # branch and posts the same verdict, waiting (bounded) for the checks named in the profile to report. + # Same-repository branches only: a fork's or Dependabot's pull_request token cannot write statuses, + # and those are covered by the workflow_run job. No trust decision uses github.actor. + # Because a pull request can edit this file, the Gate tamper guard (ci-gate-tamper-guard.yml, run from + # the default branch) fails a pull request that touches gate files unless the owner has approved it. + gate-pr: + if: github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository + uses: hyperpolymath/proven-cicd-and-workflows/.github/workflows/ci-gate.yml@d2140a5a789e4ebec52f1bab0074181012660c3b # cicd-suite ci-gate + with: + context: "CI/gate" diff --git a/.github/workflows/proofs.yml b/.github/workflows/proofs.yml index 2bfccf1..476753c 100644 --- a/.github/workflows/proofs.yml +++ b/.github/workflows/proofs.yml @@ -205,8 +205,10 @@ jobs: - name: Declared exemption is still true run: bash scripts/check-coverage-exemption.sh - # The required status check `CI/gate` (live Branch-Floor ruleset 25434034). - # It aggregates every other job in this workflow with `needs:` and fails + # The in-workflow verdict `Proofs verdict` (NOT the required context: `CI/gate` + # of the live Branch-Floor ruleset 25434034 is a commit status published by + # ci-gate.yml, the only producer of it). It aggregates every other job in this workflow + # with `needs:` and fails # unless ALL of them succeeded: failure, cancellation and skipping all fail, # so it is never a rubber stamp. `if: always()` makes it run (and fail) when # a needed job fails instead of being skipped, which a required check would @@ -214,7 +216,7 @@ jobs: # job is added here without being added to `needs:`. # Read-only permissions; the one `uses:` is the checkout already pinned in actions.lock. gate: - name: CI/gate + name: Proofs verdict needs: [proofs, lean-leg, rocq-leg, coverage-exemption] if: ${{ always() }} runs-on: ubuntu-latest diff --git a/.machine_readable/coverage-exemption.toml b/.machine_readable/coverage-exemption.toml index 268f2de..a37c4a3 100644 --- a/.machine_readable/coverage-exemption.toml +++ b/.machine_readable/coverage-exemption.toml @@ -1,6 +1,6 @@ # SPDX-License-Identifier: MPL-2.0 # Declared code-coverage exemption, verified by scripts/check-coverage-exemption.sh -# (job `coverage-exemption` in .github/workflows/proofs.yml, aggregated by CI/gate). +# (job `coverage-exemption` in .github/workflows/proofs.yml, aggregated by the `Proofs verdict` job). # # This repository is prover-only: Agda, rechecked in Rocq and Lean. It has no # runtime code, so a line-coverage percentage is undefined, not 0%. The claim is diff --git a/.machine_readable/required-contexts-allow.txt b/.machine_readable/required-contexts-allow.txt index 1f429f7..a77d775 100644 --- a/.machine_readable/required-contexts-allow.txt +++ b/.machine_readable/required-contexts-allow.txt @@ -4,8 +4,15 @@ # workflow files in `.github/workflows/` that produce them on `pull_request`. # # Format: => <.github/workflows/file.yml> +# or: => status:<.github/workflows/file.yml> +# +# A `status:` mapping names a workflow_run publisher of a commit status (the +# estate's CI gate caller). The checker verifies that the file exists, triggers on +# workflow_run with a `completed` type, calls the suite's ci-gate reusable at a +# 40-hex pin (or the local copy) and passes `with.context` equal to the context. # # Verified by `scripts/check-required-contexts.sh` (3-outcome 0/1/2) so a # renamed or path-filtered workflow can never silently strand pull requests # behind an unsatisfiable ruleset check (issue #219 class). scan / gitleaks => .github/workflows/secret-scanner.yml +CI/gate => status:.github/workflows/ci-gate.yml diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc index f31767c..1070133 100644 --- a/CHANGELOG.adoc +++ b/CHANGELOG.adoc @@ -1,5 +1,43 @@ == Changelog +== 2026-11-17 — `CI/gate` starts on `pull_request`; tamper guard + +* `CI/gate` now also starts on `pull_request`, and a tamper guard is added. + `.github/workflows/ci-gate.yml` is rewritten from the suite's + `templates/ci-gate-caller.yml`: a same-repository `gate-pr` job on + `pull_request` posts `CI/gate` on the pull request that adds or changes the + gate, beside the existing `workflow_run`, `schedule` and `workflow_dispatch` + job `gate` (which skips `pull_request`). The new + `.github/workflows/ci-gate-tamper-guard-caller.yml` calls the suite's guard on + `pull_request_target`: a pull request that touches a gate file fails + `guard / check` until the owner applies the label `gate-change-approved`. The + guard is not a required context yet. Both callers pin + hyperpolymath/proven-cicd-and-workflows at `d2140a5a789e4ebec52f1bab0074181012660c3b`, + a provisional pin on a suite pull request branch (a placeholder until that pull request merges); + `actions.lock` is edited by hand to match (`gh actions-lock` v0.2.0 cannot lock + cross-repository reusable workflows) and `scripts/check-lock-sync.sh` is the + authority. `tests/workflows/squabble_gate_test.sh` section 5b asserts the new + triggers, the jobs and their pins, and the guard caller's shape. + +== 2026-11-17 — `CI/gate` comes from the suite publisher; `Proofs verdict` + +* `.github/workflows/ci-gate.yml` calls the reusable `ci-gate.yml` in + hyperpolymath/proven-cicd-and-workflows, which posts the commit status + `CI/gate` (the context the live Branch-Floor ruleset requires) from the + required-check list in that suite's `profiles/ci-gate/`. It runs on + `workflow_run` (`completed`, `in_progress`), on a 15-minute schedule and on + `workflow_dispatch`. Statuses are last-writer-wins, so a stale status can + stand until the next evaluation; the suite's `docs/CI-GATE.adoc` states the + limit. +* The `proofs.yml` job that was named `CI/gate` is renamed `Proofs verdict` + (job id, `needs:` and verdict logic unchanged). It is one of the checks the + publisher requires. +* `scripts/check-required-contexts.sh` accepts a typed mapping + ` => status:`, verifying that the publisher triggers on + `workflow_run`, calls the suite reusable at a 40-hex pin and passes the + exact context. `.machine_readable/required-contexts-allow.txt` maps + `CI/gate` that way. + == 2026-11-17 — Proof receipt and grades at 47de4a8 * `verification/receipts/resource-algebra-proofs_praxis.deed` now describes diff --git a/scripts/check-required-contexts.sh b/scripts/check-required-contexts.sh old mode 100755 new mode 100644 index e74e26c..0a52d5c --- a/scripts/check-required-contexts.sh +++ b/scripts/check-required-contexts.sh @@ -13,6 +13,16 @@ # --admin`) — enforcing cicd-squabbler's core `squabble != bypass` # invariant statically alongside the runtime binary. # +# 1b. A mapping spelled ` => status:<.github/workflows/foo.yml>` names +# a COMMIT-STATUS publisher, not a pull_request job: a workflow_run caller +# of the estate's CI gate cannot have a check run of that name (a job in a +# reusable gets ` / `). The checker then requires +# that the file exists, triggers on workflow_run with a `completed` type, +# has a job whose `uses:` is the suite's ci-gate reusable at a full +# 40-hex pin (or the local ./.github/workflows/ci-gate.yml), and passes +# `with.context` exactly equal to the mapped context. YAML is read in-process +# with Bun.YAML, as for item 1. A plain mapping keeps the semantics of item 1. +# # Exit contract (proven-tests-and-benches 3-outcome convention): # 0 = all mapped required contexts are producible on pull_request and zero # bypass commands exist in workflows @@ -44,7 +54,7 @@ command -v bun >/dev/null 2>&1 || { bun run - "$REPO_ROOT" <<'JS' import { readdirSync, readFileSync, existsSync } from "node:fs"; -import { join, resolve } from "node:path"; +import { isAbsolute, join, relative, resolve } from "node:path"; const root = resolve(process.argv[2]); const wfDir = join(root, ".github/workflows"); @@ -58,8 +68,12 @@ function fail(msg) { errors++; } -// 1. Parse mapping file: " => <.github/workflows/foo.yml>" +// 1. Parse mapping file: " => <.github/workflows/foo.yml>" or +// " => status:<.github/workflows/foo.yml>". `mapped` holds the path; +// `statusPublishers` holds the contexts whose mapping is `status:`-typed. const mapped = new Map(); +const statusPublishers = new Set(); +const mappedAtLine = new Map(); // a context may be mapped once, in any spelling const lines = readFileSync(allowPath, "utf8").split(/\r?\n/); for (let idx = 0; idx < lines.length; idx++) { const trimmed = lines[idx].trim(); @@ -69,7 +83,22 @@ for (let idx = 0; idx < lines.length; idx++) { console.error(`check-required-contexts: malformed mapping at line ${idx + 1}: ${lines[idx]}`); process.exit(2); } - mapped.set(parts[0], parts[1]); + if (mappedAtLine.has(parts[0])) { + console.error(`check-required-contexts: context '${parts[0]}' is mapped more than once (line ${mappedAtLine.get(parts[0])} and line ${idx + 1}); map each context exactly once, as either a plain or a status: mapping`); + process.exit(2); + } + mappedAtLine.set(parts[0], idx + 1); + if (parts[1].startsWith("status:")) { + const target = parts[1].slice("status:".length).trim(); + if (!target) { + console.error(`check-required-contexts: malformed status mapping at line ${idx + 1}: ${lines[idx]}`); + process.exit(2); + } + statusPublishers.add(parts[0]); + mapped.set(parts[0], target); + } else { + mapped.set(parts[0], parts[1]); + } } if (mapped.size === 0) { console.error("check-required-contexts: 0 contexts mapped in required-contexts-allow.txt"); @@ -93,12 +122,119 @@ if (existsSync(rulesetsDir)) { } } +/** Parse one workflow file in-process with Bun.YAML (as the pull_request path does). */ +function parseWorkflow(file) { + try { + return { doc: Bun.YAML.parse(readFileSync(file, "utf8")) }; + } catch (e) { + return { error: String(e?.message ?? e) }; + } +} + +const SUITE_USES = /^hyperpolymath\/proven-cicd-and-workflows\/\.github\/workflows\/ci-gate\.yml@([^\s@]+)$/; +const LOCAL_USES = "./.github/workflows/ci-gate.yml"; + +/** + * Check a local `uses: ./...ci-gate.yml` target. GitHub runs a called workflow only if its `on` + * block has `workflow_call`, and a workflow cannot call itself, so the target is resolved under + * the repository root and read. Returns an error string, or null when the target is a valid reusable. + */ +function localTargetError(uses, fullWf) { + if (isAbsolute(uses)) return `'${uses}' is an absolute path`; + if (uses.split("/").includes("..")) return `'${uses}' contains '..' path traversal`; + const target = resolve(root, uses); + const rel = relative(root, target); + if (rel === "" || rel.startsWith("..") || isAbsolute(rel)) return `'${uses}' resolves outside the repository root`; + if (rel !== LOCAL_USES.slice(2)) return `'${uses}' is not directly the file ${LOCAL_USES}`; + if (target === resolve(fullWf)) return `'${uses}' is the publisher file itself, and a workflow cannot call itself`; + if (!existsSync(target)) return `'${uses}' names a file that does not exist`; + const { doc, error } = parseWorkflow(target); + if (error !== undefined) return `'${uses}' is not parseable YAML: ${error}`; + const onBlock = doc?.on ?? doc?.true; + const callable = + typeof onBlock === "string" ? onBlock === "workflow_call" + : Array.isArray(onBlock) ? onBlock.map(String).includes("workflow_call") + : onBlock && typeof onBlock === "object" ? "workflow_call" in onBlock + : false; + if (!callable) return `'${uses}' does not declare on.workflow_call, so GitHub cannot run it as a reusable workflow`; + return null; +} + +/** + * Verify a `status:` publisher: + * workflow_run caller (type `completed`). EVERY job that calls the suite's ci-gate + * reusable must be pinned at a full 40-hex SHA (or be the local reusable, which must be a + * separate file that declares on.workflow_call) and pass + * `with.context` exactly equal to `ctx`; at least one such job must exist, and + * the pinned jobs must share one pin. + */ +function verifyStatusPublisher(ctx, relWf, fullWf) { + const { doc, error } = parseWorkflow(fullWf); + if (error !== undefined) { + fail(`status context '${ctx}' publisher '${relWf}' is not parseable YAML: ${error}`); + return; + } + const onBlock = doc?.on ?? doc?.true; + const wr = onBlock && typeof onBlock === "object" && !Array.isArray(onBlock) ? onBlock.workflow_run : undefined; + if (wr === undefined) { + fail(`status context '${ctx}' publisher '${relWf}' does not trigger on workflow_run`); + } else { + const types = wr && typeof wr === "object" ? wr.types : undefined; + if (!Array.isArray(types) || !types.includes("completed")) { + fail(`status context '${ctx}' publisher '${relWf}' workflow_run types do not include 'completed' (types: ${JSON.stringify(types ?? null)})`); + } + } + const jobs = doc?.jobs && typeof doc.jobs === "object" ? doc.jobs : {}; + const callers = []; + const rejected = []; + const badRefs = []; + for (const [id, job] of Object.entries(jobs)) { + const uses = typeof job?.uses === "string" ? job.uses : ""; + const m = uses.match(SUITE_USES); + if (uses === LOCAL_USES || ((uses.startsWith("./") || isAbsolute(uses)) && /ci-gate\.yml$/.test(uses))) { + const why = localTargetError(uses, fullWf); + if (why === null) callers.push({ id, job, pin: null }); + else { + rejected.push(`job '${id}' uses ${why}`); + badRefs.push(`job '${id}' uses ${why}`); + } + } else if (m && /^[0-9a-f]{40}$/.test(m[1])) callers.push({ id, job, pin: m[1] }); + else if (m) { + const why = `job '${id}' pins '${m[1]}', which is not a 40-hex commit SHA`; + rejected.push(why); + badRefs.push(why); + } else if (/ci-gate\.yml/.test(uses)) rejected.push(`job '${id}' uses '${uses}', which is not the suite's ci-gate reusable`); + } + if (callers.length === 0) { + const why = rejected.length > 0 ? `: ${rejected.join("; ")}` : ""; + fail(`status context '${ctx}' publisher '${relWf}' has no job whose uses: is hyperpolymath/proven-cicd-and-workflows/.github/workflows/ci-gate.yml@<40-hex> or ${LOCAL_USES}${why}`); + return; + } + // Every job that calls the suite reusable is held to the same rule, not just one of them: a + // second job (the pull_request start) on a mutable ref or another commit would otherwise pass. + for (const why of badRefs) fail(`status context '${ctx}' publisher '${relWf}': ${why}`); + for (const { id, job } of callers) { + if (job?.with?.context !== ctx) { + fail(`status context '${ctx}' publisher '${relWf}' job '${id}' passes the wrong with.context (${JSON.stringify(job?.with?.context ?? null)}); it must equal '${ctx}' exactly`); + } + } + const pins = [...new Set(callers.filter((c) => c.pin !== null).map((c) => c.pin))]; + if (pins.length > 1) { + const by = callers.filter((c) => c.pin !== null).map((c) => `${c.id}@${c.pin}`).join(", "); + fail(`status context '${ctx}' publisher '${relWf}' pins the suite reusable at more than one commit (${by}); every job must use the same pin`); + } +} + // 3. Verify each mapped producer workflow exists, triggers on pull_request, and // has no pull_request.paths / paths-ignore filter that can strand a PR. for (const [ctx, relWf] of mapped.entries()) { const fullWf = join(root, relWf); if (!existsSync(fullWf)) { - fail(`required context '${ctx}' maps to missing workflow '${relWf}'`); + fail(`required context '${ctx}' maps to missing ${statusPublishers.has(ctx) ? "status publisher" : "workflow"} '${relWf}'`); + continue; + } + if (statusPublishers.has(ctx)) { + verifyStatusPublisher(ctx, relWf, fullWf); continue; } const doc = Bun.YAML.parse(readFileSync(fullWf, "utf8")); @@ -148,5 +284,5 @@ if (errors > 0) { console.error(`check-required-contexts: ${errors} violation(s) found`); process.exit(1); } -console.log(`OK: ${mapped.size} required status context(s) verified producible on pull_request; 0 admin-bypass workflows`); +console.log(`OK: ${mapped.size - statusPublishers.size} required status context(s) verified producible on pull_request, ${statusPublishers.size} verified as commit-status publisher(s); 0 admin-bypass workflows`); JS diff --git a/scripts/ci-gate.sh b/scripts/ci-gate.sh index 2fd26cb..614cf6f 100755 --- a/scripts/ci-gate.sh +++ b/scripts/ci-gate.sh @@ -2,7 +2,8 @@ # SPDX-License-Identifier: MPL-2.0 # SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell # -# ci-gate.sh — the verdict behind the required status check `CI/gate`. +# ci-gate.sh — the verdict behind the in-workflow job `Proofs verdict` (NOT the +# required context `CI/gate`, which is a commit status published by ci-gate.yml). # # Reads the `needs` context of a GitHub Actions job (toJSON(needs)) from # $NEEDS_JSON and succeeds only if at least one job was aggregated and EVERY @@ -20,16 +21,16 @@ command -v jq >/dev/null 2>&1 || { echo "ci-gate: jq is required" >&2; exit 2; } total="$(jq -e 'length' <<<"$NEEDS_JSON")" || { echo "::error::ci-gate: NEEDS_JSON is not a JSON object"; exit 1; } if [ "$total" -eq 0 ]; then - echo "::error::CI/gate aggregates no jobs (denominator = 0); refusing to pass." + echo "::error::Proofs verdict aggregates no jobs (denominator = 0); refusing to pass." exit 1 fi -echo "CI/gate: ${total} aggregated job(s)" +echo "Proofs verdict: ${total} aggregated job(s)" jq -r 'to_entries[] | " \(.key): \(.value.result)"' <<<"$NEEDS_JSON" bad="$(jq -r 'to_entries[] | select(.value.result != "success") | "\(.key)=\(.value.result)"' <<<"$NEEDS_JSON")" if [ -n "$bad" ]; then - while IFS= read -r line; do echo "::error::CI/gate: required job did not succeed: ${line}"; done <<<"$bad" + while IFS= read -r line; do echo "::error::Proofs verdict: required job did not succeed: ${line}"; done <<<"$bad" exit 1 fi -echo "CI/gate: all ${total} required job(s) succeeded" +echo "Proofs verdict: all ${total} required job(s) succeeded" diff --git a/tests/workflows/actions_lock_sha_refs_test.sh b/tests/workflows/actions_lock_sha_refs_test.sh index 49ba215..c5a86db 100755 --- a/tests/workflows/actions_lock_sha_refs_test.sh +++ b/tests/workflows/actions_lock_sha_refs_test.sh @@ -188,6 +188,7 @@ actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9|v7.0.2|44036562 dependabot/fetch-metadata@25dd0e34f4fe68f24cc83900b1fe3fe149efef98|v3.1.0|27347476|371068214|- editorconfig-checker/action-editorconfig-checker@51f63319f592f97930c73d9c46184d20bd206393|v3.0.0|26415196|297874902|- erlef/setup-beam@54075bcc5e249e4758d363f27d099f55d843f124|v1.24.1|47606891|331103973|- +hyperpolymath/proven-cicd-and-workflows@d2140a5a789e4ebec52f1bab0074181012660c3b|main|6759885|1326697643|- github/codeql-action@9b3254085494b55a0f7c4c2b3d2d52cc712ce370|v4.39.1|9919|259445878|- ossf/scorecard-action@fa7117db83c52d787ae5a89f350999701505d78e|v2.5.0|67707773|421101922|- oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6|v2.2.0|108928776|512644635|- diff --git a/tests/workflows/ci_gate_test.sh b/tests/workflows/ci_gate_test.sh index 08188ed..cadc16b 100755 --- a/tests/workflows/ci_gate_test.sh +++ b/tests/workflows/ci_gate_test.sh @@ -1,7 +1,7 @@ #!/usr/bin/env bash # SPDX-License-Identifier: MPL-2.0 # SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell -# CI/gate must be a verdict, not a rubber stamp. Positive control: all green +# The `Proofs verdict` job must be a verdict, not a rubber stamp. Positive control: all green # passes. Negative cases: failure, cancelled, skipped, empty and malformed # input each fail. Drift: the gate's `needs:` must list every other job in # proofs.yml. Exemption: planting runtime code under src/ makes the declared @@ -24,7 +24,30 @@ wf=.github/workflows/proofs.yml jobs="$(sed -n '/^jobs:/,$ s/^ \([a-z0-9-]*\):$/\1/p' "$wf" | grep -vx 'gate' | sort | tr '\n' ' ')" needs="$(sed -n 's/^ needs: \[\(.*\)\]$/\1/p' "$wf" | tr -d ',' | tr ' ' '\n' | sort | tr '\n' ' ')" if [ "$jobs" = "$needs" ]; then echo "ok gate needs every other job ($needs)"; else echo "FAIL needs drift: jobs=[$jobs] needs=[$needs]"; fail=1; fi -grep -q '^ name: CI/gate$' "$wf" && echo "ok job name is exactly CI/gate" || { echo "FAIL job name"; fail=1; } +grep -q '^ name: Proofs verdict$' "$wf" && echo "ok job name is exactly Proofs verdict" || { echo "FAIL job name"; fail=1; } +# `CI/gate` belongs to the suite publisher (ci-gate.yml, a commit status): no workflow job may be named it. +# Job names are read as parsed YAML (yq v4), so plain, double-quoted and single-quoted spellings all count. +command -v yq >/dev/null 2>&1 || { echo "FAIL yq (mikefarah v4) is required"; exit 2; } +has_cigate_job() { # has_cigate_job DIR + local f + for f in "$1"/*.yml "$1"/*.yaml; do + [ -f "$f" ] || continue + yq '.jobs[].name | select(. == "CI/gate")' "$f" | grep -qx 'CI/gate' && return 0 + done + return 1 +} +if has_cigate_job .github/workflows; then echo "FAIL a workflow job is named CI/gate"; fail=1; else echo "ok no workflow job is named CI/gate"; fi +ctl=$(mktemp -d) +n=0 +for spelling in 'CI/gate' '"CI/gate"' "'CI/gate'"; do + n=$((n + 1)) + printf 'on: pull_request\njobs:\n x:\n name: %s\n runs-on: ubuntu-latest\n steps: []\n' "$spelling" > "$ctl/c$n.yml" + if has_cigate_job "$ctl"; then echo "ok planted job name $spelling is detected"; else echo "FAIL planted job name $spelling not detected"; fail=1; fi + rm -f "$ctl/c$n.yml" +done +printf 'on: pull_request\njobs:\n x:\n name: Other\n runs-on: ubuntu-latest\n steps: []\n' > "$ctl/ok.yml" +if has_cigate_job "$ctl"; then echo "FAIL an unrelated job name is flagged"; fail=1; else echo "ok an unrelated job name is not flagged"; fi +rm -rf "$ctl" work=$(mktemp -d); trap 'rm -rf "$work"' EXIT git ls-files -z | xargs -0 -I{} cp --parents {} "$work" 2>/dev/null diff --git a/tests/workflows/squabble_gate_test.sh b/tests/workflows/squabble_gate_test.sh old mode 100755 new mode 100644 index 203f7e9..d1757f9 --- a/tests/workflows/squabble_gate_test.sh +++ b/tests/workflows/squabble_gate_test.sh @@ -308,6 +308,256 @@ fresh_context rm -rf "$context_tree/.github/workflows" assert_rc 2 'missing workflow directory is setup failure' bash "$REPO_ROOT/scripts/check-required-contexts.sh" "$context_tree" +echo "=== 5b. Typed status mapping: a workflow_run commit-status publisher ===" +# `CI/gate => status:` is certified as a publisher, never as a job name. +SUITE_REUSABLE='hyperpolymath/proven-cicd-and-workflows/.github/workflows/ci-gate.yml' +SUITE_PIN='d2140a5a789e4ebec52f1bab0074181012660c3b' +status_tree="$WORK/status-publisher" +fresh_status() { # fresh_status [uses] [context] [on-block] + local uses="${1:-$SUITE_REUSABLE@$SUITE_PIN}" ctx="${2:-CI/gate}" + local on="${3:-}" + [ -n "$on" ] || on=$'on:\n workflow_run:\n workflows: ["**", "!CI gate"]\n types: [completed, in_progress]' + rm -rf "$status_tree" + mkdir -p "$status_tree/.github/workflows" "$status_tree/.machine_readable" + printf 'CI/gate => status:.github/workflows/ci-gate.yml\n' > "$status_tree/.machine_readable/required-contexts-allow.txt" + printf 'name: CI gate\n%s\njobs:\n gate:\n uses: %s\n with: {context: "%s"}\n' "$on" "$uses" "$ctx" > "$status_tree/.github/workflows/ci-gate.yml" +} +check_status() { bash "$REPO_ROOT/scripts/check-required-contexts.sh" "$status_tree"; } +fresh_status +assert_rc 0 'status mapping: a workflow_run suite caller at a 40-hex pin with the exact context passes' check_status +# A local reusable is a SEPARATE file that declares on.workflow_call: GitHub cannot run anything else +# as a called workflow, and a workflow cannot call itself. +fresh_status './.github/workflows/ci-gate.yml' +assert_rc 1 'status mapping: the publisher calling itself as the local reusable fails' check_status +fresh_status './.github/workflows/ci-gate.yml' +check_status >"$WORK/status-msg" 2>&1 || true +assert_rc 0 'status mapping message: a self-call says a workflow cannot call itself' grep -qF 'cannot call itself' "$WORK/status-msg" +fresh_local() { # fresh_local + local uses="$1" target="$2" + rm -rf "$status_tree" + mkdir -p "$status_tree/.github/workflows" "$status_tree/.machine_readable" + printf 'CI/gate => status:.github/workflows/gate-caller.yml\n' > "$status_tree/.machine_readable/required-contexts-allow.txt" + printf 'name: Gate caller\non:\n workflow_run:\n workflows: ["**"]\n types: [completed]\njobs:\n gate:\n uses: %s\n with: {context: "CI/gate"}\n' "$uses" > "$status_tree/.github/workflows/gate-caller.yml" + if [ "$target" != '-' ]; then + printf 'name: Local gate\n%s\njobs:\n gate:\n runs-on: ubuntu-latest\n steps: [{run: echo hi}]\n' "$target" > "$status_tree/.github/workflows/ci-gate.yml" + fi +} +LOCAL_TARGET='./.github/workflows/ci-gate.yml' +fresh_local "$LOCAL_TARGET" $'on:\n workflow_call:' +assert_rc 0 'status mapping: a separate caller whose local target declares workflow_call passes' check_status +fresh_local "$LOCAL_TARGET" $'on:\n workflow_call:\n inputs:\n context: {type: string}' +assert_rc 0 'status mapping: a local target with workflow_call inputs passes' check_status +fresh_local "$LOCAL_TARGET" 'on: [workflow_call]' +assert_rc 0 'status mapping: a local target with a workflow_call list passes' check_status +fresh_local "$LOCAL_TARGET" $'on:\n push:' +assert_rc 1 'status mapping: a local target without workflow_call fails' check_status +fresh_local "$LOCAL_TARGET" $'on:\n push:' +check_status >"$WORK/status-msg" 2>&1 || true +assert_rc 0 'status mapping message: names the missing workflow_call' grep -qF 'does not declare on.workflow_call' "$WORK/status-msg" +fresh_local "$LOCAL_TARGET" - +assert_rc 1 'status mapping: a missing local target file fails' check_status +fresh_local "$LOCAL_TARGET" - +check_status >"$WORK/status-msg" 2>&1 || true +assert_rc 0 'status mapping message: names the missing target file' grep -qF 'names a file that does not exist' "$WORK/status-msg" +fresh_local './.github/workflows/../workflows/ci-gate.yml' $'on:\n workflow_call:' +assert_rc 1 'status mapping: a local target path with .. fails even though the file exists' check_status +fresh_local './.github/workflows/../workflows/ci-gate.yml' $'on:\n workflow_call:' +check_status >"$WORK/status-msg" 2>&1 || true +assert_rc 0 'status mapping message: names the path traversal' grep -qF "contains '..' path traversal" "$WORK/status-msg" +fresh_local '/etc/ci-gate.yml' $'on:\n workflow_call:' +assert_rc 1 'status mapping: an absolute local target fails' check_status +fresh_local "$LOCAL_TARGET" $'on:\n workflow_call:' +sed -i 's|^ uses: .*| uses: ./.github/workflows/ci-gate.yml|' "$status_tree/.github/workflows/gate-caller.yml" +printf ' other:\n uses: ./../outside/ci-gate.yml\n with: {context: "CI/gate"}\n' >> "$status_tree/.github/workflows/gate-caller.yml" +assert_rc 1 'status mapping: a second, bad local job fails beside a valid local job' check_status +fresh_status +rm "$status_tree/.github/workflows/ci-gate.yml" +assert_rc 1 'status mapping: a missing publisher file fails' check_status +fresh_status "$SUITE_REUSABLE@$SUITE_PIN" 'CI/gate' $'on:\n pull_request:' +assert_rc 1 'status mapping: no workflow_run trigger fails' check_status +fresh_status "$SUITE_REUSABLE@$SUITE_PIN" 'CI/gate' $'on:\n workflow_run:\n workflows: ["**"]\n types: [in_progress]' +assert_rc 1 'status mapping: workflow_run without the completed type fails' check_status +fresh_status "$SUITE_REUSABLE@$SUITE_PIN" 'CI/other' +assert_rc 1 'status mapping: a wrong with.context fails' check_status +fresh_status "$SUITE_REUSABLE@$SUITE_PIN" 'CI/gate ' +assert_rc 1 'status mapping: a context that differs only by whitespace fails' check_status +fresh_status "hyperpolymath/other-repo/.github/workflows/ci-gate.yml@$SUITE_PIN" +assert_rc 1 'status mapping: a uses: that is not the suite ci-gate reusable fails' check_status +fresh_status "hyperpolymath/proven-cicd-and-workflows/.github/workflows/other.yml@$SUITE_PIN" +assert_rc 1 'status mapping: another workflow of the suite fails' check_status +for pin in main v1 "${SUITE_PIN:0:39}" "${SUITE_PIN}0" "${SUITE_PIN^^}"; do + fresh_status "$SUITE_REUSABLE@$pin" + assert_rc 1 "status mapping: a non-40-hex pin fails: $pin" check_status +done +fresh_status "$SUITE_REUSABLE@$SUITE_PIN" +printf 'CI/gate => status:\n' > "$status_tree/.machine_readable/required-contexts-allow.txt" +assert_rc 2 'status mapping: an empty status target is a setup failure' check_status +# Each failure names what is wrong (not merely that something failed). +status_says() { # status_says