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 @@ -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'
Expand Down Expand Up @@ -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'
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"}
15 changes: 8 additions & 7 deletions .github/workflows/proven-tests.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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: {}
Expand All @@ -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 "|---|---|---|---|"
Expand Down Expand Up @@ -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)"
8 changes: 7 additions & 1 deletion .machine_readable/required-contexts-allow.txt
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +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 => .github/workflows/proven-tests.yml
CI/gate => status:.github/workflows/ci-gate.yml
6 changes: 6 additions & 0 deletions CHANGELOG.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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
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 @@ -12,6 +12,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 @@ -57,8 +67,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 @@ -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");
Expand All @@ -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"));
Expand Down Expand Up @@ -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
Loading
Loading