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 2b6b637..d58808a 100644 --- a/.github/workflows/actions.lock +++ b/.github/workflows/actions.lock @@ -7,6 +7,10 @@ workflows: - 'actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1' '.github/workflows/build-notification.yml': - 'actions/checkout@v7.0.1' + '.github/workflows/ci-gate-tamper-guard-caller.yml': + - 'hyperpolymath/proven-cicd-and-workflows@4e9e680b0dfd842a457cf23271f9e005a88f766c' + '.github/workflows/ci-gate.yml': + - 'hyperpolymath/proven-cicd-and-workflows@4e9e680b0dfd842a457cf23271f9e005a88f766c' '.github/workflows/codeql.yml': - 'actions/checkout@v7.0.1' - 'github/codeql-action@6f2ac81f5cd81fe351a197ba0b00d91d03cd2aee' @@ -175,6 +179,11 @@ dependencies: commit: 'sha1-0f8e8c99d88aeb3fbfd523f1ef2c6f762d10d64d' owner_id: 75048950 repo_id: 623796603 + 'hyperpolymath/proven-cicd-and-workflows@4e9e680b0dfd842a457cf23271f9e005a88f766c': + ref: 'main' + commit: 'sha1-4e9e680b0dfd842a457cf23271f9e005a88f766c' + 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..2b46979 --- /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@4e9e680b0dfd842a457cf23271f9e005a88f766c # cicd-suite tamper guard diff --git a/.github/workflows/ci-gate.yml b/.github/workflows/ci-gate.yml new file mode 100644 index 0000000..7abe988 --- /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@4e9e680b0dfd842a457cf23271f9e005a88f766c # 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@4e9e680b0dfd842a457cf23271f9e005a88f766c # cicd-suite ci-gate + with: + context: "CI/gate" diff --git a/.github/workflows/proven-tests.yml b/.github/workflows/proven-tests.yml index 08031c5..fd10939 100644 --- a/.github/workflows/proven-tests.yml +++ b/.github/workflows/proven-tests.yml @@ -149,14 +149,15 @@ jobs: STANDARDS_DIR="$RUNNER_TEMP/standards" bash scripts/run-proven-suite.sh --require-zig --bench # ========================================================================== - # Required status check "CI/gate" (Branch-Floor ruleset). - # The check context is this job's name. It waits for every other job in this - # workflow and runs even when one fails, is cancelled or is skipped; it exits + # In-workflow verdict job "Proven suite verdict" (NOT the required context). + # The context `CI/gate` is NOT this job: it is a commit status published by + # ci-gate.yml (the suite reusable), the only producer of it. This job waits for every + # other job in this workflow and runs even when one fails, is cancelled or is skipped; it exits # 0 only when every required job succeeded (or was skipped by design behind a # detector job that itself succeeded). Pattern: hyperpolymath/hypatia ci.yml. # ========================================================================== ci-gate: - name: CI/gate + name: Proven suite verdict runs-on: ubuntu-24.04 timeout-minutes: 5 permissions: {} @@ -183,7 +184,7 @@ jobs: } row() { printf '| %s | %s | %s | %s |\n' "$@" | tee -a "$summary"; } { - echo "### CI/gate" + echo "### Proven suite verdict" echo echo "| job | result | role | verdict |" echo "|---|---|---|---|" @@ -222,7 +223,7 @@ jobs: msg="required jobs: $total; satisfied: $passed; advisory: $(wc -w <<< "$ADVISORY_JOBS")" echo "$msg" | tee -a "$summary" if [ "$fail" -ne 0 ]; then - echo "::error::CI/gate failed ($msg)" + echo "::error::Proven suite verdict failed ($msg)" exit 1 fi - echo "CI/gate passed ($msg)" + echo "Proven suite verdict passed ($msg)" diff --git a/.machine_readable/required-contexts-allow.txt b/.machine_readable/required-contexts-allow.txt index a87b767..a77d775 100644 --- a/.machine_readable/required-contexts-allow.txt +++ b/.machine_readable/required-contexts-allow.txt @@ -4,9 +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 => .github/workflows/proven-tests.yml +CI/gate => status:.github/workflows/ci-gate.yml diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc index 7f8fad8..0c90473 100644 --- a/CHANGELOG.adoc +++ b/CHANGELOG.adoc @@ -114,6 +114,28 @@ https://semver.org/spec/v2.0.0.html[Semantic Versioning]. ==== Changed +* `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 `4e9e680b0dfd842a457cf23271f9e005a88f766c`, + the squash commit of hyperpolymath/proven-cicd-and-workflows#139 on its `main`; + `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. +* The in-workflow aggregate job in `proven-tests.yml` is renamed from `CI/gate` to + `Proven suite verdict` (job id, `needs:` and verdict logic unchanged). The + context `CI/gate` is now a commit status published by `ci-gate.yml`, a thin + caller of the reusable in proven-cicd-and-workflows, which is its only + producer. `ci-gate.yml` is keyed in `actions.lock` as the lock-sync gate + requires. * KYAML, step 5 of standards YAML-POLICY §5 (standards#1024): the three estate-owned YAML files that no third-party bot rewrites are now KYAML content: `build/container/compose.yaml`, `compose.example.yaml` and diff --git a/scripts/check-required-contexts.sh b/scripts/check-required-contexts.sh old mode 100755 new mode 100644 index 235f28b..61df8fb --- a/scripts/check-required-contexts.sh +++ b/scripts/check-required-contexts.sh @@ -12,6 +12,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 @@ -43,7 +53,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"); @@ -57,8 +67,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(); @@ -68,7 +82,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"); @@ -92,12 +121,125 @@ 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`; + // The caller passes with.context, and GitHub refuses an input the called workflow does not + // declare, so the target must declare on.workflow_call.inputs.context as a string input. + const call = onBlock && typeof onBlock === "object" && !Array.isArray(onBlock) ? onBlock.workflow_call : undefined; + const ctxInput = call && typeof call === "object" ? call.inputs?.context : undefined; + if (!ctxInput || typeof ctxInput !== "object" || ctxInput.type !== "string") + return `'${uses}' does not declare on.workflow_call.inputs.context with type: string, so GitHub refuses the caller's with.context`; + 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")); @@ -139,5 +281,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/tests/workflows/squabble_gate_test.sh b/tests/workflows/squabble_gate_test.sh old mode 100755 new mode 100644 index ec8625b..6563ee8 --- a/tests/workflows/squabble_gate_test.sh +++ b/tests/workflows/squabble_gate_test.sh @@ -301,6 +301,271 @@ 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='4e9e680b0dfd842a457cf23271f9e005a88f766c' +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' +GOOD_CALL=$'on:\n workflow_call:\n inputs:\n context: {type: string}' +fresh_local "$LOCAL_TARGET" "$GOOD_CALL" +assert_rc 0 'status mapping: a separate caller whose local target declares workflow_call with a string context input passes' check_status +fresh_local "$LOCAL_TARGET" $'on:\n workflow_call:\n inputs:\n context: {type: string, required: true}\n workflow_dispatch:' +assert_rc 0 'status mapping: a required string context input beside another trigger passes' check_status +# The caller passes with.context; GitHub refuses an input the called workflow does not declare. +fresh_local "$LOCAL_TARGET" $'on:\n workflow_call:' +assert_rc 1 'status mapping: a local target whose workflow_call declares no inputs fails' check_status +fresh_local "$LOCAL_TARGET" $'on:\n workflow_call:' +check_status >"$WORK/status-msg" 2>&1 || true +assert_rc 0 'status mapping message: names the missing context input' grep -qF 'inputs.context with type: string' "$WORK/status-msg" +fresh_local "$LOCAL_TARGET" 'on: [workflow_call]' +assert_rc 1 'status mapping: a workflow_call list (which cannot declare inputs) fails' check_status +fresh_local "$LOCAL_TARGET" 'on: workflow_call' +assert_rc 1 'status mapping: a bare workflow_call string (which cannot declare inputs) fails' check_status +fresh_local "$LOCAL_TARGET" $'on:\n workflow_call:\n inputs:\n other: {type: string}' +assert_rc 1 'status mapping: inputs without context fails' check_status +fresh_local "$LOCAL_TARGET" $'on:\n workflow_call:\n inputs:\n context: {type: number}' +assert_rc 1 'status mapping: a non-string context input fails' check_status +fresh_local "$LOCAL_TARGET" $'on:\n workflow_call:\n inputs:\n context:' +assert_rc 1 'status mapping: a context input with no type fails' 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' "$GOOD_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' "$GOOD_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' "$GOOD_CALL" +assert_rc 1 'status mapping: an absolute local target fails' check_status +fresh_local "$LOCAL_TARGET" "$GOOD_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