Skip to content

chore(ci): name the security check for what it does, not for its tools - #92

Merged
DuqueOM merged 1 commit into
mainfrom
chore/rename-self-audit-job
Sep 5, 2026
Merged

chore(ci): name the security check for what it does, not for its tools#92
DuqueOM merged 1 commit into
mainfrom
chore/rename-self-audit-job

Conversation

@DuqueOM

@DuqueOM DuqueOM commented Sep 5, 2026

Copy link
Copy Markdown
Owner

Step 2 of the three-step ruleset transition ADR-046 anticipated. Self-audit (gitleaks + tfsec + checkov + trivy fs)Self-audit (secrets + IaC + supply chain).

Why this needed a transition at all

A required status check is identified by its job-name string. Rename the job and the ruleset keeps waiting for a context that will never report — so the PR containing the rename blocks itself.

That is why #90 shipped a job named after a tool it no longer runs, and said so in the workflow and in ADR-046 rather than leaving it as an unexplained inaccuracy.

The three steps

Step What State
1 Drop the context from the ruleset by direct API PUT ✅ done — 6 required checks → 5, no PRs open at the time
2 This PR: rename the job, moving all three canonical sources together gated by the remaining 5 checks
3 Re-apply the ruleset from scripts/setup_branch_protection.sh after merge, back to 6 under the new name

Step 1 is deliberately not committed. That state is transient; the applier script stays the source of truth for the final shape, so the repo never records a half-transition.

docs/governance/branch-protection.md says any change must update all three sources in the same commit, so this PR moves that document, ADR-026 and the applier payload together.

The actual fix is the naming rule, not this rename

The old name enumerated its tools, which guaranteed it would go stale on the next tool change — and made that staleness expensive to correct, because it was welded to a required-check contract.

secrets + IaC + supply chain names the classes of check. The job runs gitleaks and a hardcoded-credential sweep (secrets), Trivy config and Checkov (IaC), plus pin-drift checks, toolchain-install hygiene and a Trivy filesystem CVE scan (supply chain). A future tool swap now touches no contract at all.

What is written down

New section in docs/governance/branch-protection.md"Renaming a required check" — with the procedure and the two things that bite:

  • between steps 1 and 3 the check is not required, so keep the window short and open no other PRs in it;
  • re-adding a required check while it is red blocks every subsequent PR, so confirm the job is green on main first.

ADR-046 is amended rather than rewritten: its Consequences section recorded that the name was left alone deliberately, and now records that the transition was carried out. The [Unreleased] CHANGELOG entry from #90 is corrected in place, since it has not shipped.

Verification

$ # step 1 applied
$ gh api repos/.../rules/branches/main --jq ...required_status_checks[].context
Tests & Coverage / Python 3.11
Tests & Coverage / Python 3.12
Python Lint + Type Check
Agentic System Validation
Scaffolder End-to-End Test

$ # the other four rules survived the PUT
deletion · non_fast_forward · pull_request · required_linear_history · required_status_checks
$ # enforcement: active, admin bypass intact

$ bash scripts/setup_branch_protection.sh --dry-run | grep -c "Self-audit (secrets + IaC + supply chain)"
1

$ make verify
✓ every gate green — safe to push

Step 3 runs immediately after this merges, and I will confirm the ruleset reads back with six contexts under the new name.

🤖 Generated with Claude Code

`Self-audit (gitleaks + tfsec + checkov + trivy fs)` ->
`Self-audit (secrets + IaC + supply chain)`.

The old name enumerated its tools, so ADR-046 falsified it the moment tfsec
was swapped for Trivy. Correcting it was not a one-line edit: a required
status check is identified by its job-name string, so renaming the job leaves
the ruleset waiting for a context that will never report — the PR containing
the rename blocks itself. ADR-046 shipped with a name it knew to be wrong and
recorded why.

Step 2 of the three-step transition. Step 1 dropped the context from the
ruleset by direct API call, deliberately not committed: that state is
transient and scripts/setup_branch_protection.sh stays the source of truth
for the final shape. Step 3 re-applies the ruleset from this payload.

All three canonical sources move together, as docs/governance/branch-protection.md
requires: this document, ADR-026 and the applier script.

The procedure is now written down under §"Renaming a required check",
including the two things that bite: the check is not required between steps 1
and 3, and re-adding a required check while it is red blocks every subsequent
PR.

The new name describes the classes of check rather than the tools, so the
next tool swap touches no contract at all. That is the real fix; this rename
is just the current instance of it.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@DuqueOM
DuqueOM merged commit 62bf15d into main Sep 5, 2026
25 checks passed
@DuqueOM
DuqueOM deleted the chore/rename-self-audit-job branch September 5, 2026 18:05
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant