Files
ersatztv/scripts/tests/test_workflow_persist_credentials.py
T
timothy d91091e911 fix(744,835): review round 2 — the "forced" claim was FALSE; case + dotless-host escapes
Both round-2 cold reviews returned BLOCKED. The most important finding is that a claim
this change made three times over was simply wrong.

**"Removing the self-path is FORCED" is false.** The argument was that under
`branches: [main]` a self-triggering path can only publish after the merge. It cannot
publish by PUSH — but the retained branch `workflow_dispatch` publishes it fine: dispatch
the branch at the ci-image.yml commit, then pin it, and `ci-image-pin` resolves both to
that commit and passes. So keeping the self-reference is workable, and the decision rests
entirely on price, not necessity: keeping it charges a full ~2GB publish plus a five-pin
bump for EVERY edit to that file, comments included, redone after every rebase — the cost
that reverted #697 and forced this to land alone — against the cost of dropping it, a
recipe change living only in ci-image.yml that never republishes. The second was chosen
because that file is edited far more for triggers and comments than for build recipe.
Restated as a decided tradeoff, with both prices, in the record, ci-cd.md and both
workflow comments. #744's Done-when asks for the tradeoff to be DECIDED rather than
asserted away; a false necessity claim was the opposite of that.

**The guard had two more escapes of the class round 1 closed for URLs.** A Gitea action
host is not required to contain a dot (`http://your-git-server/actions/checkout@v4` is the
documented self-hosted spelling), and the forge is case-insensitive on owner/repo
(`Actions/Checkout@v4` runs the real checkout). Both escaped the walk AND the text scan
identically, so the count cross-check agreed and the guard reported clean. Replaced the
host heuristic with last-two-path-segments and made both halves case-insensitive; all
three spellings are pinned in the negative control.

**A new stale-but-green state was reachable by following the documented remedy literally.**
The dispatch builds HEAD's copy of every file, so a `ci-image.yml` recipe change committed
AFTER the `docker/ci` commit publishes an image built by the old recipe while the pin and
`expected` both name the `docker/ci` commit — green over an image the merged recipe would
not produce. Step 1 now states the ordering.

Also: the credential-scoping record's `rule:` frontmatter still said #744 was tracked-open
and still asserted the mechanism this change removes, contradicting its own body — round 1
fixed the 15-of-16 clause inside that same string and stopped, a sweep by keyword rather
than by concept. `ci-image-pin`'s comment still said a docker/ci PR "publishes a NEW
image". Restored the #445 attribution the recovery rewrite dropped. Renamed the composite
-action test to say what it asserts (that none EXISTS), and filed #855: nothing
mechanically couples `ci-image.yml`'s `push.paths` to `ci-image-pin`'s `expected` now that
the shared self-reference is gone.

refs #744
refs #835
Decisions-Edit: yes
2026-08-27 20:58:05 +02:00

242 lines
12 KiB
Python

"""Every `actions/checkout` drops the persisted credential (ersatztv#835).
WHAT THIS IS PROTECTING. `actions/checkout` writes an `Authorization` header into `.git/config`
unless `persist-credentials: false` is set, and this instance's Actions default token permission is
`permissive` — so that header is write-capable, and every later step in the job inherits it, not
just the checkout. ersatztv#746 set the flag on every checkout but one; nothing held the convention
afterwards. A job added tomorrow gets a checkout without the flag, and **nothing goes
red** — the silent-by-construction shape `docs/defect-shapes-773.md` §4 exists to catch.
WHY THERE IS NO EXEMPTION LIST. `ci-image.yml`'s checkout was the one left unset, for a mechanical
reason in another issue (#744), and this guard was deliberately held back rather than shipped with a
one-entry exemption for it: an exemption outlives its reason silently — once #744 set the flag there,
the entry would still have passed and the guard would have been permanently blind to the very file it
was written for. #744 landed with this, so the assertion is universal over the derived population.
POPULATION. The git index, via `tracked_files.tracked_paths` — not a filesystem walk and not a
hand-written list (`testing.guard-derives-population-from-source`, ersatztv#806). Both `*.yml` and
`*.yaml` are matched: Gitea accepts either spelling, so a `.yaml` workflow would otherwise be
structurally invisible to a check that reads as covering all of them.
"""
from __future__ import annotations
import re
from pathlib import Path
import yaml
from scripts.tests.tracked_files import _git_ls_files, tracked_paths
WORKFLOW_DIR = ".gitea/workflows"
WORKFLOWS = (WORKFLOW_DIR, ("*.yml", "*.yaml"))
# Compared LOWERCASE throughout: Gitea resolves an action ref through a forge that is
# case-insensitive on owner/repo, so `uses: Actions/Checkout@v4` runs the real checkout. A
# case-sensitive comparison missed it in BOTH halves identically, so the count cross-check agreed
# and the guard reported clean over a step that persists the credential.
CHECKOUT = "actions/checkout"
# Matches the `uses:` line the YAML walk is supposed to reach, in every spelling below. Used ONLY as
# an independent second opinion on how many there are — never as the population itself.
_USES_CHECKOUT = re.compile(
r"^\s*-?\s*uses:\s*['\"]?(?:[^'\"\s]*/)?actions/checkout(@|\s|['\"]|$)",
re.M | re.I,
)
def _canonical_action(uses: str) -> str:
"""The last two path segments of a `uses:` value, without its `@version`.
Gitea accepts a full action URL as well as `owner/repo`, and the host in one is NOT required to
contain a dot — `http://your-git-server/actions/checkout@v4` is documented and valid. So this
takes the last two segments rather than trying to recognise a hostname: every spelling of the
same action canonicalises to `actions/checkout`, with no host heuristic to get wrong.
It over-matches in one direction on purpose: a genuinely different action whose path happens to
END in `actions/checkout` would be treated as a checkout and required to carry the flag. That
costs a spurious requirement on an action nobody has; the opposite error costs a live credential.
"""
ref = uses.strip().strip("'\"").split("@", 1)[0].strip().lower()
ref = re.sub(r"^https?://", "", ref)
segments = [seg for seg in ref.split("/") if seg]
if ref.startswith("./") or ref.startswith("../") or len(segments) < 2:
return ref
return "/".join(segments[-2:])
def workflow_files() -> list[Path]:
return tracked_paths(*WORKFLOWS)
def _checkout_steps(doc: object) -> list[tuple[str, int, dict]]:
"""Every `actions/checkout` step in a parsed workflow, as (job id, index within job, step).
Reads `jobs.<id>.steps` only, which is the whole shape this repo uses. Two different escapes are
reported by two different tests, and they are not interchangeable:
`test_the_walk_finds_every_actions_checkout_the_TEXT_does` covers a shape INSIDE a workflow file
that the walk cannot reach, because both halves read the same files. A **composite action** is
invisible to both halves — its `action.yml` is not in the workflow population at all — so that
case is reported by `test_no_LOCAL_COMPOSITE_ACTION_exists_AT_ALL` instead.
"""
found: list[tuple[str, int, dict]] = []
if not isinstance(doc, dict):
return found
jobs = doc.get("jobs")
if not isinstance(jobs, dict):
return found
for job_id, job in jobs.items():
if not isinstance(job, dict):
continue
steps = job.get("steps")
if not isinstance(steps, list):
continue
for index, step in enumerate(steps):
if not isinstance(step, dict):
continue
uses = step.get("uses")
if isinstance(uses, str) and _canonical_action(uses) == CHECKOUT:
found.append((str(job_id), index, step))
return found
def checkout_faults(rel: str, doc: object) -> list[str]:
"""Human-readable faults for one workflow — accumulated, not failed fast.
A missing key and an explicit `true` are the same defect and are reported the same way: what
matters is whether the credential is left behind, not how the step spelled it.
"""
faults: list[str] = []
for job_id, index, step in _checkout_steps(doc):
with_block = step.get("with")
value = with_block.get("persist-credentials") if isinstance(with_block, dict) else None
if value is False:
continue
how = "does not set it at all" if value is None else f"sets it to {value!r}"
faults.append(
f"{rel}: job `{job_id}` step #{index} uses {CHECKOUT} and {how} — so the action "
f"persists a write-capable Authorization header into .git/config, and every later "
f"step in that job inherits it. Add `persist-credentials: false` under `with:` "
f"(ersatztv#746, guarded by ersatztv#835). There is deliberately no exemption list: "
f"if a checkout genuinely needs the credential, say so in the step and change this "
f"guard in the same PR."
)
return faults
def test_every_actions_checkout_DROPS_the_persisted_credential() -> None:
faults: list[str] = []
for path in workflow_files():
rel = path.relative_to(Path(__file__).resolve().parents[2]).as_posix()
faults.extend(checkout_faults(rel, yaml.safe_load(path.read_text())))
assert not faults, "\n".join(faults)
def test_the_walk_finds_every_actions_checkout_the_TEXT_does() -> None:
"""The YAML walk and a plain text scan must agree on the count, per file.
Without this, a step list the walk cannot reach — a composite action, a reusable workflow, a
shape act_runner grows later — makes checkouts structurally invisible while the guard above
still reports a clean run. Absence of output is not evidence; make the system report it.
"""
disagreements: list[str] = []
for path in workflow_files():
text = path.read_text()
walked = len(_checkout_steps(yaml.safe_load(text)))
scanned = len(_USES_CHECKOUT.findall(text))
if walked != scanned:
disagreements.append(
f"{path.name}: the jobs.<id>.steps walk found {walked} {CHECKOUT} step(s) but the "
f"text scan found {scanned}. The walk is what the flag assertion runs over, so the "
f"difference is checkouts this guard cannot see — widen `_checkout_steps`."
)
assert not disagreements, "\n".join(disagreements)
def test_the_population_and_the_checkout_set_are_NOT_empty() -> None:
"""Anti-vacuity, in both directions.
An empty population, or a population of workflows in which the walk finds no checkout at all,
makes the assertion above pass while measuring nothing — which is the failure this guard exists
to prevent, arriving through the guard itself.
"""
files = workflow_files()
assert files, (
"`git ls-files` reported no .gitea/workflows/*.yml — the derivation is broken, not the repo, "
"and every assertion in this file would pass vacuously."
)
total = sum(len(_checkout_steps(yaml.safe_load(p.read_text()))) for p in files)
assert total > 0, (
f"Parsed {len(files)} workflow(s) and found no {CHECKOUT} step in any of them. Either the "
"repo really has none (then delete this guard and say why) or `_checkout_steps` stopped "
"matching, in which case the flag assertion is measuring an empty set."
)
def test_the_fault_collector_reports_a_checkout_that_OMITS_the_flag() -> None:
"""Negative control on the collector itself, over both defect spellings.
The mutation proof (`mutation_manifest.py`) drives the real tree; this drives the collector
directly so a collector that silently stopped reporting is caught without waiting for the
harness, and so `true` is covered as well as an absent key.
"""
omitted = {"jobs": {"j": {"steps": [{"uses": "actions/checkout@v4"}]}}}
explicit_true = {"jobs": {"j": {"steps": [{"uses": "actions/checkout@v4", "with": {"persist-credentials": True}}]}}}
compliant = {"jobs": {"j": {"steps": [{"uses": "actions/checkout@v4", "with": {"persist-credentials": False}}]}}}
assert len(checkout_faults("synthetic.yml", omitted)) == 1
assert "does not set it at all" in checkout_faults("synthetic.yml", omitted)[0]
assert len(checkout_faults("synthetic.yml", explicit_true)) == 1
assert "sets it to True" in checkout_faults("synthetic.yml", explicit_true)[0]
assert checkout_faults("synthetic.yml", compliant) == []
# Gitea accepts a full action URL, so the same step spelled as a URL must not escape either —
# pinned rather than probed once, because a canonicalisation that quietly stopped working would
# leave the guard green over a checkout it no longer recognises as one.
for spelling in (
"https://github.com/actions/checkout@v4",
# A Gitea action host is not required to contain a dot — this is the documented
# self-hosted spelling, and a dot-requiring canonicaliser let it through silently.
"http://your-git-server/actions/checkout@v4",
"github.com/actions/checkout@v4",
# The forge is case-insensitive on owner/repo, so this runs the real checkout.
"Actions/Checkout@v4",
):
as_url = {"jobs": {"j": {"steps": [{"uses": spelling}]}}}
assert len(checkout_faults("synthetic.yml", as_url)) == 1, spelling
assert _USES_CHECKOUT.search(f" - uses: {spelling}"), spelling
assert not _USES_CHECKOUT.search(" - uses: actions/setup-node@v4")
def test_no_workflow_hides_in_a_SUBDIRECTORY() -> None:
"""The population is direct children of `.gitea/workflows`; prove nothing sits below it.
`tracked_children` is direct-children-only by design (see `tracked_files`), which is right for a
flat directory and blind the moment one stops being flat. This does not widen the population —
it makes the assumption REPORT itself, so a nested workflow reddens the guard instead of being
silently uncovered, and it covers the two sibling guards that derive the same directory the same
way (`test_ci_image_pin_population.py`, `test_pr_changed_files.py`).
"""
nested = sorted(
path for path in _git_ls_files() if path.startswith(f"{WORKFLOW_DIR}/") and "/" in path[len(WORKFLOW_DIR) + 1 :]
)
assert not nested, (
f"tracked workflow file(s) below {WORKFLOW_DIR}/: {nested}. The population here is direct "
"children only, so these are NOT checked for `persist-credentials: false` — widen the "
"derivation (and the sibling guards that share it) before adding them."
)
def test_no_LOCAL_COMPOSITE_ACTION_exists_AT_ALL() -> None:
"""A checkout inside a local composite action runs in the job but is outside the workflow set.
The repo has no `action.yml`/`action.yaml` today, so rather than write a parser for a shape that
does not exist, assert the absence: the first one added reddens this and its author widens the
guard, instead of the guard reading as complete while a whole class walked around it.
"""
actions = sorted(path for path in _git_ls_files() if path.rpartition("/")[2] in {"action.yml", "action.yaml"})
assert not actions, (
f"local composite action definition(s) found: {actions}. A composite action's steps run in "
"the job, so an `actions/checkout` in one is subject to the same rule and is NOT covered by "
"the workflow-file population above — extend `_checkout_steps` to walk them."
)