From 154e3e350d2073a42cd8207b022487fc0c6a4e9d Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 17 Nov 2026 02:14:02 +0000 Subject: [PATCH 01/13] ci: add CI gate caller emitting the CI/gate commit status (interim) Thin caller of the reusable ci-gate workflow in proven-cicd-and-workflows. It runs from the default branch via workflow_run (completed and in_progress, so a rerun flips the status to pending) and posts the commit status CI/gate, which the Branch-Floor ruleset requires. The required-check list lives in the suite profile at the pinned SHA, not in this repository. The caller is onboarded in actions.lock (workflow key plus a leaf dependency record, ref main) as the lock-sync gate requires. The pin is the placeholder __CICD_SUITE_SHA__ until the suite SHA is known. Rename the in-workflow job CI/gate to "Proven suite verdict" (CI/gate now belongs to the suite publisher). Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01J4QvDg8YzLVHtwwDfcY3J9 --- .github/workflows/README.adoc | 20 +++++++++++ .github/workflows/actions.lock | 7 ++++ .github/workflows/ci-gate.yml | 57 ++++++++++++++++++++++++++++++ .github/workflows/proven-tests.yml | 15 ++++---- CHANGELOG.adoc | 6 ++++ 5 files changed, 98 insertions(+), 7 deletions(-) create mode 100644 .github/workflows/ci-gate.yml diff --git a/.github/workflows/README.adoc b/.github/workflows/README.adoc index 2a577512..72753fbf 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 2b6b637e..653e6ed2 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@7a5713bb062218540cf4474596b3fac2835352e4' '.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@7a5713bb062218540cf4474596b3fac2835352e4': + ref: 'main' + commit: 'sha1-7a5713bb062218540cf4474596b3fac2835352e4' + 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.yml b/.github/workflows/ci-gate.yml new file mode 100644 index 00000000..9746dfcf --- /dev/null +++ b/.github/workflows/ci-gate.yml @@ -0,0 +1,57 @@ +# 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. +# +# 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 `secrets:` line: the reusable consumes none. +name: CI gate + +on: + workflow_run: + workflows: ["**", "!CI gate"] + types: [completed, in_progress] + +permissions: + statuses: write + checks: read + actions: read + contents: read + +concurrency: + group: ci-gate-${{ github.event.workflow_run.head_sha }} + cancel-in-progress: false + +jobs: + gate: + if: github.event.workflow_run.name != 'CI gate' + uses: hyperpolymath/proven-cicd-and-workflows/.github/workflows/ci-gate.yml@7a5713bb062218540cf4474596b3fac2835352e4 # cicd-suite ci-gate + with: + context: "CI/gate" diff --git a/.github/workflows/proven-tests.yml b/.github/workflows/proven-tests.yml index 08031c5a..fd109391 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/CHANGELOG.adoc b/CHANGELOG.adoc index 6f952bc5..f998b44a 100644 --- a/CHANGELOG.adoc +++ b/CHANGELOG.adoc @@ -99,6 +99,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 From c32981d299f6a14b66c78d9bdbdb9121e436c3f0 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 17 Nov 2026 02:50:54 +0000 Subject: [PATCH 02/13] ci: re-pin the CI gate caller to the suite PR head 1d657fe Supersedes 7a5713b: profile schema v2 (typed workflow and job entries) and the settled rule extended to superseded runs. Updates the ci-gate.yml pin, the actions.lock workflow key, dependency key and commit, and any test row or text naming the old SHA. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01J4QvDg8YzLVHtwwDfcY3J9 --- .github/workflows/actions.lock | 6 +++--- .github/workflows/ci-gate.yml | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/.github/workflows/actions.lock b/.github/workflows/actions.lock index 653e6ed2..f53ca61b 100644 --- a/.github/workflows/actions.lock +++ b/.github/workflows/actions.lock @@ -8,7 +8,7 @@ workflows: '.github/workflows/build-notification.yml': - 'actions/checkout@v7.0.1' '.github/workflows/ci-gate.yml': - - 'hyperpolymath/proven-cicd-and-workflows@7a5713bb062218540cf4474596b3fac2835352e4' + - 'hyperpolymath/proven-cicd-and-workflows@1d657fe32e3be011cad01dd14ce320cd15231aa1' '.github/workflows/codeql.yml': - 'actions/checkout@v7.0.1' - 'github/codeql-action@6f2ac81f5cd81fe351a197ba0b00d91d03cd2aee' @@ -177,9 +177,9 @@ dependencies: commit: 'sha1-0f8e8c99d88aeb3fbfd523f1ef2c6f762d10d64d' owner_id: 75048950 repo_id: 623796603 - 'hyperpolymath/proven-cicd-and-workflows@7a5713bb062218540cf4474596b3fac2835352e4': + 'hyperpolymath/proven-cicd-and-workflows@1d657fe32e3be011cad01dd14ce320cd15231aa1': ref: 'main' - commit: 'sha1-7a5713bb062218540cf4474596b3fac2835352e4' + commit: 'sha1-1d657fe32e3be011cad01dd14ce320cd15231aa1' owner_id: 6759885 repo_id: 1326697643 'hyperpolymath/smtp-notify-action@v0.5.1': diff --git a/.github/workflows/ci-gate.yml b/.github/workflows/ci-gate.yml index 9746dfcf..a6553965 100644 --- a/.github/workflows/ci-gate.yml +++ b/.github/workflows/ci-gate.yml @@ -52,6 +52,6 @@ concurrency: jobs: gate: if: github.event.workflow_run.name != 'CI gate' - uses: hyperpolymath/proven-cicd-and-workflows/.github/workflows/ci-gate.yml@7a5713bb062218540cf4474596b3fac2835352e4 # cicd-suite ci-gate + uses: hyperpolymath/proven-cicd-and-workflows/.github/workflows/ci-gate.yml@1d657fe32e3be011cad01dd14ce320cd15231aa1 # cicd-suite ci-gate with: context: "CI/gate" From 4ba8bd96d02da9204207d6a9e6bcb43bda2cfc4c Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 17 Nov 2026 02:53:58 +0000 Subject: [PATCH 03/13] ci: drop the concurrency block from the CI gate caller The suite reusable now re-fetches before every status write, so per-SHA serialisation only delayed the in_progress pending status. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01J4QvDg8YzLVHtwwDfcY3J9 --- .github/workflows/ci-gate.yml | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/.github/workflows/ci-gate.yml b/.github/workflows/ci-gate.yml index a6553965..c5b36636 100644 --- a/.github/workflows/ci-gate.yml +++ b/.github/workflows/ci-gate.yml @@ -31,6 +31,9 @@ # 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 @@ -45,10 +48,6 @@ permissions: actions: read contents: read -concurrency: - group: ci-gate-${{ github.event.workflow_run.head_sha }} - cancel-in-progress: false - jobs: gate: if: github.event.workflow_run.name != 'CI gate' From bab5b420bb86fbcf757bc2070b5084db40710817 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 17 Nov 2026 02:59:07 +0000 Subject: [PATCH 04/13] ci: re-pin the CI gate caller to the suite PR head c77a66d Replaces the 1d657fe pin in the ci-gate.yml caller, the actions.lock workflow key, dependency key and commit, and resource-algebra's lock case-table row. The suite profile for this repository is unchanged. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01J4QvDg8YzLVHtwwDfcY3J9 --- .github/workflows/actions.lock | 6 +++--- .github/workflows/ci-gate.yml | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/.github/workflows/actions.lock b/.github/workflows/actions.lock index f53ca61b..58a91587 100644 --- a/.github/workflows/actions.lock +++ b/.github/workflows/actions.lock @@ -8,7 +8,7 @@ workflows: '.github/workflows/build-notification.yml': - 'actions/checkout@v7.0.1' '.github/workflows/ci-gate.yml': - - 'hyperpolymath/proven-cicd-and-workflows@1d657fe32e3be011cad01dd14ce320cd15231aa1' + - 'hyperpolymath/proven-cicd-and-workflows@c77a66d3bf2b698204c1ef40776f9c1df426a7df' '.github/workflows/codeql.yml': - 'actions/checkout@v7.0.1' - 'github/codeql-action@6f2ac81f5cd81fe351a197ba0b00d91d03cd2aee' @@ -177,9 +177,9 @@ dependencies: commit: 'sha1-0f8e8c99d88aeb3fbfd523f1ef2c6f762d10d64d' owner_id: 75048950 repo_id: 623796603 - 'hyperpolymath/proven-cicd-and-workflows@1d657fe32e3be011cad01dd14ce320cd15231aa1': + 'hyperpolymath/proven-cicd-and-workflows@c77a66d3bf2b698204c1ef40776f9c1df426a7df': ref: 'main' - commit: 'sha1-1d657fe32e3be011cad01dd14ce320cd15231aa1' + commit: 'sha1-c77a66d3bf2b698204c1ef40776f9c1df426a7df' owner_id: 6759885 repo_id: 1326697643 'hyperpolymath/smtp-notify-action@v0.5.1': diff --git a/.github/workflows/ci-gate.yml b/.github/workflows/ci-gate.yml index c5b36636..16ca42a8 100644 --- a/.github/workflows/ci-gate.yml +++ b/.github/workflows/ci-gate.yml @@ -51,6 +51,6 @@ permissions: jobs: gate: if: github.event.workflow_run.name != 'CI gate' - uses: hyperpolymath/proven-cicd-and-workflows/.github/workflows/ci-gate.yml@1d657fe32e3be011cad01dd14ce320cd15231aa1 # cicd-suite ci-gate + uses: hyperpolymath/proven-cicd-and-workflows/.github/workflows/ci-gate.yml@c77a66d3bf2b698204c1ef40776f9c1df426a7df # cicd-suite ci-gate with: context: "CI/gate" From a1c0a17ccba6b1ab528b7c6915bf4b13c1f24cac Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 17 Nov 2026 03:03:49 +0000 Subject: [PATCH 05/13] ci: re-pin the CI gate caller to the suite PR head 0862fe8 Replaces the c77a66d pin in the ci-gate.yml caller, the actions.lock workflow key, dependency key and commit, and resource-algebra's lock case-table row. The suite profile for this repository is unchanged. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01J4QvDg8YzLVHtwwDfcY3J9 --- .github/workflows/actions.lock | 6 +++--- .github/workflows/ci-gate.yml | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/.github/workflows/actions.lock b/.github/workflows/actions.lock index 58a91587..f932eeee 100644 --- a/.github/workflows/actions.lock +++ b/.github/workflows/actions.lock @@ -8,7 +8,7 @@ workflows: '.github/workflows/build-notification.yml': - 'actions/checkout@v7.0.1' '.github/workflows/ci-gate.yml': - - 'hyperpolymath/proven-cicd-and-workflows@c77a66d3bf2b698204c1ef40776f9c1df426a7df' + - 'hyperpolymath/proven-cicd-and-workflows@0862fe8b4001ccc5bbfda925ef31dfd232d2c0a7' '.github/workflows/codeql.yml': - 'actions/checkout@v7.0.1' - 'github/codeql-action@6f2ac81f5cd81fe351a197ba0b00d91d03cd2aee' @@ -177,9 +177,9 @@ dependencies: commit: 'sha1-0f8e8c99d88aeb3fbfd523f1ef2c6f762d10d64d' owner_id: 75048950 repo_id: 623796603 - 'hyperpolymath/proven-cicd-and-workflows@c77a66d3bf2b698204c1ef40776f9c1df426a7df': + 'hyperpolymath/proven-cicd-and-workflows@0862fe8b4001ccc5bbfda925ef31dfd232d2c0a7': ref: 'main' - commit: 'sha1-c77a66d3bf2b698204c1ef40776f9c1df426a7df' + commit: 'sha1-0862fe8b4001ccc5bbfda925ef31dfd232d2c0a7' owner_id: 6759885 repo_id: 1326697643 'hyperpolymath/smtp-notify-action@v0.5.1': diff --git a/.github/workflows/ci-gate.yml b/.github/workflows/ci-gate.yml index 16ca42a8..dd224681 100644 --- a/.github/workflows/ci-gate.yml +++ b/.github/workflows/ci-gate.yml @@ -51,6 +51,6 @@ permissions: jobs: gate: if: github.event.workflow_run.name != 'CI gate' - uses: hyperpolymath/proven-cicd-and-workflows/.github/workflows/ci-gate.yml@c77a66d3bf2b698204c1ef40776f9c1df426a7df # cicd-suite ci-gate + uses: hyperpolymath/proven-cicd-and-workflows/.github/workflows/ci-gate.yml@0862fe8b4001ccc5bbfda925ef31dfd232d2c0a7 # cicd-suite ci-gate with: context: "CI/gate" From 851050c6bea28c85565cde323205bf945d71a573 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 17 Nov 2026 16:39:21 +0000 Subject: [PATCH 06/13] ci: scheduled CI/gate sweep and a typed status mapping in the squabble checker The CI gate caller gains a 15-minute schedule and workflow_dispatch, which bounds (does not eliminate) a stale CI/gate status. It needs pull-requests: read to list open PRs. scripts/check-required-contexts.sh learns ` => status:`: the publisher must exist, trigger on workflow_run with a completed type, call the suite ci-gate reusable at a 40-hex pin (or the local copy) and pass with.context equal to the context. A plain mapping keeps its semantics. Positive and negative tests are in tests/workflows/squabble_gate_test.sh. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01J4QvDg8YzLVHtwwDfcY3J9 --- .github/workflows/ci-gate.yml | 22 +++-- .machine_readable/required-contexts-allow.txt | 8 +- scripts/check-required-contexts.sh | 96 ++++++++++++++++++- tests/workflows/squabble_gate_test.sh | 65 +++++++++++++ 4 files changed, 175 insertions(+), 16 deletions(-) diff --git a/.github/workflows/ci-gate.yml b/.github/workflows/ci-gate.yml index dd224681..fa5bf20d 100644 --- a/.github/workflows/ci-gate.yml +++ b/.github/workflows/ci-gate.yml @@ -18,6 +18,12 @@ # 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. @@ -41,16 +47,12 @@ on: workflow_run: workflows: ["**", "!CI gate"] types: [completed, in_progress] - -permissions: - statuses: write - checks: read - actions: read - contents: read - + schedule: + - cron: "7,22,37,52 * * * *" + workflow_dispatch: {} +permissions: {statuses: write, actions: read, contents: read, pull-requests: read} jobs: gate: - if: github.event.workflow_run.name != 'CI gate' + if: github.event_name != 'workflow_run' || github.event.workflow_run.name != 'CI gate' uses: hyperpolymath/proven-cicd-and-workflows/.github/workflows/ci-gate.yml@0862fe8b4001ccc5bbfda925ef31dfd232d2c0a7 # cicd-suite ci-gate - with: - context: "CI/gate" + with: {context: "CI/gate"} diff --git a/.machine_readable/required-contexts-allow.txt b/.machine_readable/required-contexts-allow.txt index a87b767d..a77d775b 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/scripts/check-required-contexts.sh b/scripts/check-required-contexts.sh index 235f28b9..6b102d4c 100755 --- a/scripts/check-required-contexts.sh +++ b/scripts/check-required-contexts.sh @@ -12,11 +12,22 @@ # --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 with +# mikefarah yq v4. 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 # 1 = phantom/path-stranded required context or admin-bypass workflow found -# 2 = setup error (missing repo directory, workflows directory, or allowfile) +# 2 = setup error (missing repo directory, workflows directory, or allowfile; +# yq missing when a `status:` mapping needs it) set -euo pipefail REPO_ROOT="${1:-.}" @@ -44,6 +55,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 { spawnSync } from "node:child_process"; const root = resolve(process.argv[2]); const wfDir = join(root, ".github/workflows"); @@ -57,8 +69,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 +83,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 +117,73 @@ if (existsSync(rulesetsDir)) { } } +/** Parse one workflow file with mikefarah yq v4; exit 2 when yq is unusable. */ +function yqJson(file) { + const r = spawnSync("yq", ["-o=json", ".", file], { encoding: "utf8" }); + if (r.error || r.status === null) { + console.error("check-required-contexts: yq (mikefarah v4) is required for a `status:` mapping"); + process.exit(2); + } + if (r.status !== 0) return { error: (r.stderr || "").trim() }; + return { doc: JSON.parse(r.stdout) }; +} + +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 } = yqJson(fullWf); + if (error !== undefined) { + fail(`status context '${ctx}' publisher '${relWf}' is not parseable YAML: ${error}`); + return; + } + const onBlock = doc?.on; + 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 +225,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 ec8625be..086dec5b 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