Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 20 additions & 0 deletions .github/workflows/README.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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 `<caller job> / <job>` 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/<owner>/<repo>.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.
7 changes: 7 additions & 0 deletions .github/workflows/actions.lock
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,8 @@ version: 'v0.0.3'
workflows:
'.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@9b3254085494b55a0f7c4c2b3d2d52cc712ce370'
Expand Down Expand Up @@ -194,6 +196,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'
Expand Down
20 changes: 20 additions & 0 deletions .github/workflows/ci-gate-tamper-guard.yml
Original file line number Diff line number Diff line change
@@ -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
71 changes: 71 additions & 0 deletions .github/workflows/ci-gate.yml
Original file line number Diff line number Diff line change
@@ -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 `<caller job> / <called job>`,
# 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/<owner>/<repo>.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"}
8 changes: 5 additions & 3 deletions .github/workflows/proofs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@
name: Core proofs and expected rejections
runs-on: ubuntu-latest
timeout-minutes: 15
container: debian:trixie-slim

Check warning on line 32 in .github/workflows/proofs.yml

View workflow job for this annotation

GitHub Actions / Hypatia neurosymbolic scan

[hypatia] workflow .github/workflows/proofs.yml:32 pins container `debian:trixie-slim` by tag — tag is mutable; pin by sha256 digest instead
steps:
- name: Install the pinned prover
run: |
Expand Down Expand Up @@ -205,16 +205,18 @@
- 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
# report as passing-by-absence. tests/workflows/ci_gate_test.sh fails if a new
# 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
Expand Down
2 changes: 1 addition & 1 deletion .machine_readable/coverage-exemption.toml
Original file line number Diff line number Diff line change
@@ -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
Expand Down
7 changes: 7 additions & 0 deletions .machine_readable/required-contexts-allow.txt
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,15 @@
# workflow files in `.github/workflows/` that produce them on `pull_request`.
#
# Format: <exact check context> => <.github/workflows/file.yml>
# or: <exact commit-status context> => 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
19 changes: 19 additions & 0 deletions CHANGELOG.adoc
Original file line number Diff line number Diff line change
@@ -1,5 +1,24 @@
== Changelog

== 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
`<context> => status:<workflow>`, 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
Expand Down
90 changes: 86 additions & 4 deletions scripts/check-required-contexts.sh
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,16 @@
# --admin`) — enforcing cicd-squabbler's core `squabble != bypass`
# invariant statically alongside the runtime binary.
#
# 1b. A mapping spelled `<context> => 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 `<caller job> / <called job>`). 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
Expand Down Expand Up @@ -58,8 +68,11 @@ function fail(msg) {
errors++;
}

// 1. Parse mapping file: "<context> => <.github/workflows/foo.yml>"
// 1. Parse mapping file: "<context> => <.github/workflows/foo.yml>" or
// "<context> => 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();
Expand All @@ -69,7 +82,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");
Expand All @@ -93,12 +116,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"));
Expand Down Expand Up @@ -148,5 +230,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
11 changes: 6 additions & 5 deletions scripts/ci-gate.sh
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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"
1 change: 1 addition & 0 deletions tests/workflows/actions_lock_sha_refs_test.sh
Original file line number Diff line number Diff line change
Expand Up @@ -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@0862fe8b4001ccc5bbfda925ef31dfd232d2c0a7|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|-
Expand Down
Loading
Loading