diff --git a/.github/workflows/README.adoc b/.github/workflows/README.adoc index 2a57751..72753fb 100644 --- a/.github/workflows/README.adoc +++ b/.github/workflows/README.adoc @@ -88,3 +88,23 @@ 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 runs on `workflow_run` (`completed` and `in_progress`: a rerun flips the + status to pending, so a stale success never survives), so GitHub always uses the copy on the default + branch: a pull request cannot alter the gate, its pin or its list. The pull + request that adds it can never receive `CI/gate` itself and must be merged past + the gate once. +* 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. diff --git a/.github/workflows/actions.lock b/.github/workflows/actions.lock index 2b6b637..f932eee 100644 --- a/.github/workflows/actions.lock +++ b/.github/workflows/actions.lock @@ -7,6 +7,8 @@ workflows: - 'actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1' '.github/workflows/build-notification.yml': - 'actions/checkout@v7.0.1' + '.github/workflows/ci-gate.yml': + - 'hyperpolymath/proven-cicd-and-workflows@0862fe8b4001ccc5bbfda925ef31dfd232d2c0a7' '.github/workflows/codeql.yml': - 'actions/checkout@v7.0.1' - 'github/codeql-action@6f2ac81f5cd81fe351a197ba0b00d91d03cd2aee' @@ -175,6 +177,11 @@ dependencies: commit: 'sha1-0f8e8c99d88aeb3fbfd523f1ef2c6f762d10d64d' owner_id: 75048950 repo_id: 623796603 + 'hyperpolymath/proven-cicd-and-workflows@0862fe8b4001ccc5bbfda925ef31dfd232d2c0a7': + ref: 'main' + commit: 'sha1-0862fe8b4001ccc5bbfda925ef31dfd232d2c0a7' + 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.yml b/.github/workflows/ci-gate-tamper-guard.yml new file mode 100644 index 0000000..5db0fd1 --- /dev/null +++ b/.github/workflows/ci-gate-tamper-guard.yml @@ -0,0 +1,20 @@ +# SPDX-License-Identifier: MPL-2.0 +# Gate tamper guard - thin caller of the suite's reusable guard; copy to .github/workflows/ci-gate-tamper-guard.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, labeled, unlabeled] + +permissions: + pull-requests: read + contents: read + +jobs: + guard: + uses: hyperpolymath/proven-cicd-and-workflows/.github/workflows/ci-gate-tamper-guard.yml@d49708186e7234c2e1bcce2ceda7aed44a64c08d # cicd-suite tamper guard diff --git a/.github/workflows/ci-gate.yml b/.github/workflows/ci-gate.yml new file mode 100644 index 0000000..2407113 --- /dev/null +++ b/.github/workflows/ci-gate.yml @@ -0,0 +1,71 @@ +# 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 ` / `, +# which always contains " / " and can never equal `CI/gate`. +# +# It runs from the DEFAULT branch via workflow_run, so a pull request cannot +# alter this file, its pin or its list. The consequence: the PR that adds this +# caller can never receive `CI/gate` itself, and must be merged past the gate +# once (owner action). +# +# 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. +# +# Scheduled sweep: every 15 minutes (cron 7,22,37,52, off the hour to avoid the +# top-of-hour load) the schedule re-evaluates CI/gate for the open pull request +# heads and the default branch. This BOUNDS, but does not eliminate, a stale +# status: statuses are last-writer-wins, and GitHub may delay or skip scheduled +# runs. `pull-requests: read` is needed to list the open pull requests. +# +# 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. +# +# Trigger types: `completed` re-evaluates a finished workflow; `in_progress` +# flips the status to pending when a rerun starts, so a stale success never +# survives a rerun. +# +# 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. +# +# No `concurrency:` block: the reusable re-fetches before every status write, so +# per-SHA serialisation would only delay the in_progress pending status. +# +# 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@d49708186e7234c2e1bcce2ceda7aed44a64c08d # cicd-suite ci-gate + with: {context: "CI/gate"} + # The pull_request start (permanent). 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 the ruleset blocks it. It runs from the pull request's own branch and posts the same + # verdict, waiting (bounded) for the profile's checks to report. Same-repository branches only: + # fork and Dependabot tokens cannot write statuses, those are covered by the workflow_run job. + # No trust decision uses github.actor. A pull request can edit this file, so 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@d49708186e7234c2e1bcce2ceda7aed44a64c08d # 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..eb55b5a 100644 --- a/CHANGELOG.adoc +++ b/CHANGELOG.adoc @@ -114,6 +114,12 @@ https://semver.org/spec/v2.0.0.html[Semantic Versioning]. ==== Changed +* 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 index 235f28b..5d02c93 100755 --- 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 @@ -57,8 +67,11 @@ 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 lines = readFileSync(allowPath, "utf8").split(/\r?\n/); for (let idx = 0; idx < lines.length; idx++) { const trimmed = lines[idx].trim(); @@ -68,7 +81,17 @@ 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 (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 +115,71 @@ 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"; + +/** + * Verify a `status:` publisher: a workflow_run caller (type `completed`) with a + * job that calls the suite's ci-gate reusable at a 40-hex pin, or the local + * copy, and passes `with.context` exactly equal to `ctx`. + */ +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 = []; + 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) callers.push({ id, job }); + else if (m && /^[0-9a-f]{40}$/.test(m[1])) callers.push({ id, job }); + else if (m) rejected.push(`job '${id}' pins '${m[1]}', which is not a 40-hex commit SHA`); + 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; + } + if (!callers.some(({ job }) => job?.with?.context === ctx)) { + const got = callers.map(({ id, job }) => `${id}=${JSON.stringify(job?.with?.context ?? null)}`).join(", "); + fail(`status context '${ctx}' publisher '${relWf}' passes the wrong with.context (${got}); it must equal '${ctx}' exactly`); + } +} + // 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 +221,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 index ec8625b..086dec5 100755 --- a/tests/workflows/squabble_gate_test.sh +++ b/tests/workflows/squabble_gate_test.sh @@ -301,6 +301,71 @@ 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='0862fe8b4001ccc5bbfda925ef31dfd232d2c0a7' +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 +fresh_status './.github/workflows/ci-gate.yml' +assert_rc 0 'status mapping: the local ./.github/workflows/ci-gate.yml reusable passes' 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