Guard the persist-credentials convention — after #744, with no exemption list #835

Closed
opened 2026-08-26 17:41:00 +02:00 by timothy · 2 comments
Owner

Deferred from #746, which set persist-credentials: false on all 14 actions/checkout steps in docker-build.yml, pr-checks.yml and dependency-scan.yml (review-verdict.yml already had it) and unmasked the five base-ref fetches that fed changed-file skip logic.

What is missing

Nothing mechanically holds the convention. A new job added tomorrow gets a checkout without the flag and nothing goes red — the failure is silent by construction, which is the class docs/defect-shapes-773.md §4 exists to catch.

The obvious guard is a scripts/tests/ case that derives its population from git ls-files '.gitea/workflows/*.yml', parses each file, and asserts every actions/checkout step sets persist-credentials: false (testing.guard-derives-population-from-source).

Why it was NOT written in #746

.gitea/workflows/ci-image.yml is the one checkout left unset, and it has to stay unset until #744 lands: any commit touching that file re-points ci-image-pin's expected at itself and reddens a blocking job, and its unfiltered push trigger publishes a toolchain image from whatever branch the edit lands on.

So writing the guard now means shipping it with a hardcoded ci-image.yml exemption — a one-entry exception list whose only justification is a temporary condition in another issue. That entry outlives its reason silently: once #744 sets the flag there, the exemption still passes and the guard is permanently blind to that file. That is the rot shape, not a lint nit.

Do this instead

Land it with or after #744, with no exemption list at all: #744 sets persist-credentials: false on ci-image.yml's checkout as part of the same change that fixes its trigger, and then the guard's assertion is universal over the derived population.

Done-when

  • #744 has landed (or this change rides with it), so ci-image.yml's checkout also sets persist-credentials: false
  • A scripts/tests/ case derives the workflow population from git ls-files and asserts the flag on EVERY actions/checkout, with no exemption list
  • The guard ships with a declared clause mutation that is re-run every suite (testing.guard-ships-with-mutation-proof, testing.mutation-claims-are-executed) and a row in docs/guard-inventory.md
  • Adversarial review passed
Deferred from #746, which set `persist-credentials: false` on all 14 `actions/checkout` steps in `docker-build.yml`, `pr-checks.yml` and `dependency-scan.yml` (`review-verdict.yml` already had it) and unmasked the five base-ref fetches that fed changed-file skip logic. ## What is missing Nothing mechanically holds the convention. A new job added tomorrow gets a checkout without the flag and nothing goes red — the failure is silent by construction, which is the class `docs/defect-shapes-773.md` §4 exists to catch. The obvious guard is a `scripts/tests/` case that derives its population from `git ls-files '.gitea/workflows/*.yml'`, parses each file, and asserts every `actions/checkout` step sets `persist-credentials: false` (`testing.guard-derives-population-from-source`). ## Why it was NOT written in #746 `.gitea/workflows/ci-image.yml` is the one checkout left unset, and it has to stay unset until #744 lands: any commit touching that file re-points `ci-image-pin`'s `expected` at itself and reddens a blocking job, and its unfiltered `push` trigger publishes a toolchain image from whatever branch the edit lands on. So writing the guard now means shipping it with a hardcoded `ci-image.yml` exemption — a one-entry exception list whose only justification is a *temporary* condition in another issue. That entry outlives its reason silently: once #744 sets the flag there, the exemption still passes and the guard is permanently blind to that file. That is the rot shape, not a lint nit. ## Do this instead Land it **with or after #744**, with no exemption list at all: #744 sets `persist-credentials: false` on `ci-image.yml`'s checkout as part of the same change that fixes its trigger, and then the guard's assertion is universal over the derived population. ## Done-when - [x] #744 has landed (or this change rides with it), so `ci-image.yml`'s checkout also sets `persist-credentials: false` - [x] A `scripts/tests/` case derives the workflow population from `git ls-files` and asserts the flag on EVERY `actions/checkout`, with no exemption list - [x] The guard ships with a declared clause mutation that is re-run every suite (`testing.guard-ships-with-mutation-proof`, `testing.mutation-claims-are-executed`) and a row in `docs/guard-inventory.md` - [x] Adversarial review passed
timothy added the ci-cdpriority: lowsecurity labels 2026-08-26 17:41:08 +02:00
timothy added the in-progress label 2026-08-27 19:51:59 +02:00
Author
Owner

Claiming alongside #744 in the same PR — this issue's own "Do this instead" says the guard should ride with #744 so it needs no exemption list. Same session, same branch.

Claiming alongside #744 in the same PR — this issue's own "Do this instead" says the guard should ride with #744 so it needs no exemption list. Same session, same branch.
Author
Owner

Closing record

Outcome: Shipped in PR #857, riding with #744 exactly as this issue's "Do this instead" prescribed. ci-image.yml's checkout takes persist-credentials: false (16 of 16), and scripts/tests/test_workflow_persist_credentials.py asserts the flag on every actions/checkout in every tracked workflow with no exemption list.

Root cause: N/A — a missing guard. #746 set the flag on 15 of 16 checkouts and nothing held the convention afterwards; a job added later would get a checkout without it and nothing would go red.

Decisions/conventions changed: None added. The guard row and the appendix population row are in docs/guard-inventory.md; the declared clause mutation is in scripts/tests/mutation_manifest.py.

Reusable knowledge:

  1. Waiting for #744 was the right call and the reason generalises. A one-entry exemption justified by a temporary condition in another issue keeps passing after that condition expires, leaving the guard permanently blind to the very file it was written for.
  2. actions/checkout has far more valid spellings than it looks. Three review rounds found seven that escaped successive versions of the canonicaliser: a full URL, a host with NO dot (http://your-git-server/actions/checkout@v4 is the documented self-hosted form), any letter case (the forge is case-insensitive on owner/repo), a .git suffix (how Gitea writes the clone URL), @-userinfo before the host (splitting on the FIRST @ strips the host, not the version), and a doubled slash. Canonicalise by taking the last two path segments — no host heuristic to get wrong — and compare lowercase.
  3. A count-based cross-check only reports a DISAGREEMENT. Where a shape is invisible to both the YAML walk and the text scan — a composite action, a reusable-workflow delegation, a workflow under .github/workflows or a nested subdirectory — both halves see zero and agree, so the check stays silent. Those four are covered by explicit ABSENCE tests instead, so the boundary reports itself rather than going blind.

Verification: scripts/tests full suite 1026 passed / 2 skipped. test_mutation_harness.py executes the declared clause mutation against ci-image.yml and confirms the named proof reddens with the declared diagnostic. test_guard_inventory.py and test_guard_populations_derive_from_git.py both pass, so the new file is in the derived guard population and its derivation is registered.

Deferred: None for this issue. (#855, filed from the same PR, is about a different missing coupling.)

Docs updated: docs/guard-inventory.md (main table row, appendix population row, summary counts 40/18/6/16), and the persist-credentials section of docs/ci-cd.md.

## Closing record **Outcome:** Shipped in PR #857, riding with #744 exactly as this issue's "Do this instead" prescribed. `ci-image.yml`'s checkout takes `persist-credentials: false` (16 of 16), and `scripts/tests/test_workflow_persist_credentials.py` asserts the flag on every `actions/checkout` in every tracked workflow **with no exemption list**. **Root cause:** N/A — a missing guard. #746 set the flag on 15 of 16 checkouts and nothing held the convention afterwards; a job added later would get a checkout without it and nothing would go red. **Decisions/conventions changed:** None added. The guard row and the appendix population row are in `docs/guard-inventory.md`; the declared clause mutation is in `scripts/tests/mutation_manifest.py`. **Reusable knowledge:** 1. **Waiting for #744 was the right call and the reason generalises.** A one-entry exemption justified by a temporary condition in another issue keeps passing after that condition expires, leaving the guard permanently blind to the very file it was written for. 2. **`actions/checkout` has far more valid spellings than it looks.** Three review rounds found seven that escaped successive versions of the canonicaliser: a full URL, a host with NO dot (`http://your-git-server/actions/checkout@v4` is the documented self-hosted form), any letter case (the forge is case-insensitive on owner/repo), a `.git` suffix (how Gitea writes the clone URL), `@`-userinfo before the host (splitting on the FIRST `@` strips the host, not the version), and a doubled slash. Canonicalise by taking the last two path segments — no host heuristic to get wrong — and compare lowercase. 3. **A count-based cross-check only reports a DISAGREEMENT.** Where a shape is invisible to both the YAML walk and the text scan — a composite action, a reusable-workflow delegation, a workflow under `.github/workflows` or a nested subdirectory — both halves see zero and agree, so the check stays silent. Those four are covered by explicit ABSENCE tests instead, so the boundary reports itself rather than going blind. **Verification:** `scripts/tests` full suite 1026 passed / 2 skipped. `test_mutation_harness.py` executes the declared clause mutation against `ci-image.yml` and confirms the named proof reddens with the declared diagnostic. `test_guard_inventory.py` and `test_guard_populations_derive_from_git.py` both pass, so the new file is in the derived guard population and its derivation is registered. **Deferred:** None for this issue. (#855, filed from the same PR, is about a different missing coupling.) **Docs updated:** `docs/guard-inventory.md` (main table row, appendix population row, summary counts 40/18/6/16), and the persist-credentials section of `docs/ci-cd.md`.
timothy removed the in-progress label 2026-08-27 22:45:25 +02:00
Sign in to join this conversation.
1 Participants
Notifications
Due Date
No due date set.
Reference: timothy/ersatztv#835