From 4196a057fbb58d1f3812ec642b7f6ffa896bdc3c Mon Sep 17 00:00:00 2001 From: Timothy Date: Wed, 26 Aug 2026 17:38:04 +0200 Subject: [PATCH] fix(746): drop the persisted checkout credential; unmask the base-ref fetches MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `actions/checkout` leaves an `Authorization` header in `.git/config` unless `persist-credentials: false` is set — write-capable while this instance's Actions default token permission is `permissive`, where it stands after a Restricted trial was reverted on 2026-08-05 (#748). Every workflow here except `review-verdict.yml` omitted it, so a job handed that credential to every script it ran, not merely to the checkout. 15 of the repo's 16 checkouts now set it. Setting the flag first would have been unsafe, which is why #743 deferred it rather than doing it blind: five steps ran `git fetch ... origin "$base_ref" || true` and fed the result into changed-file skip logic, so a credential regression would have presented as an empty changed set on the three steps that also masked `git diff`, and a possibly-absent `origin/` handed to a fail-open Python validator on the other two — a silently self-skipping check on a green job either way. So the masking comes out first, and only then does the flag go on. `git diff`'s own `2>/dev/null || true` goes with it on the three sites that had one. `--depth` came off those five fetches in the same step, and that is the part the cold reviews converged on. All five run in jobs that check out `fetch-depth: 0`, and `git fetch --depth=N` grafts a *complete* clone shallow — measured on a 150-commit repo branched 130 back: `.git/shallow` appears and `git diff origin/main...HEAD` fails `fatal: no merge base`, while the same fetch without `--depth` returns the correct file list. Under `|| true` that was a silent skip; unmasked it would have reddened `api-docs` and `format` on any branch not rebased inside the depth window, and left `decisions lifecycle` green with its diff-dependent checks silently skipped. Loud is not the same as blocking. `api-docs`, `format` and `decisions lifecycle` gate on this diff and now redden on a failed fetch. `docs-reminder` does not — it is a non-blocking nudge whose advisory red would still join the combined status the merge gate reads, which is why its `Set up Python` and doc-narrative steps already carried `continue-on-error: true`. The parity nudge now carries it for the same reason, so all three of its non-checkout steps have it and the `::error::` reaches the log without becoming a merge block. `Checkout` stays blocking. The population is wider than #746's file list. Sweeping the shape rather than the named file found 8 checkouts in `docker-build.yml` (not the six #743 recorded), 5 in `pr-checks.yml` and 1 in `dependency-scan.yml`, and three masked fetches in `pr-checks.yml` beside the two in `docker-build.yml`. That widening is recorded on the issue so acceptance is judged against what shipped. No job that checks out pushes with git, and the repo is public with anonymous `git-upload-pack` answering, so nothing loses a capability it was using. Renovate does push branches, but `renovate.yml` has no checkout step and carries its own `RENOVATE_TOKEN`. Two further masked fetches, in `scripts/ci-detect-docs-only.sh` and `scripts/ci-detect-already-validated.sh`, keep their masking on purpose: in both, a failed fetch can only leave the base revision unresolvable, and an unresolvable base emits `false` — run the full matrix. Neither can turn a failed fetch into a skip. Their `--depth` is a different matter and is NOT cleared here: the push-path `--depth=2` grafts the `build` job's `fetch-depth: 0` checkout, which is why `:latest` images ship `InformationalVersion 0.0.0-` — measured on the live test container as `0.0.0-5a7a4ed7` and filed as #836. Four stale statements of that script's shallow-consumer set (two in docs/ci-cd.md, one in the script itself, one in `ci.docs-only-detect-shallow-safe`) said `fetch-depth: 1` and named two of the three consumers; they are corrected here, because this change states the same fact again and would otherwise leave the corpus disagreeing with itself. `ci-image.yml`'s one checkout is the exception, and not because it is safe: its unfiltered `push` trigger is head-resolved in the sense that matters. It is excluded because any commit touching that file re-points `ci-image-pin`'s `expected` at itself and reddens a blocking job, and because the same trigger would publish a toolchain image from the editing branch. It rides with #744. No machine-checked guard holds the convention yet: writing one now means a hardcoded `ci-image.yml` exemption whose only justification is a temporary condition in another issue, and that entry would outlive its reason silently. Filed as #835, blocked by #744, to be written with no exemption list at all. fixes #746 Decisions-Edit: yes --- .gitea/workflows/dependency-scan.yml | 2 + .gitea/workflows/docker-build.yml | 30 +++++- .gitea/workflows/pr-checks.yml | 36 ++++++- docs/ci-cd.md | 95 +++++++++++++++++-- docs/decisions/README.md | 2 +- .../records/ci/actions-credential-scoping.md | 46 +++++++-- .../ci/docs-only-detect-shallow-safe.md | 4 +- .../release/main-direct-push-disabled.md | 19 ++-- scripts/ci-detect-docs-only.sh | 3 +- 9 files changed, 201 insertions(+), 36 deletions(-) diff --git a/.gitea/workflows/dependency-scan.yml b/.gitea/workflows/dependency-scan.yml index a971293e5..0245c981d 100644 --- a/.gitea/workflows/dependency-scan.yml +++ b/.gitea/workflows/dependency-scan.yml @@ -40,6 +40,8 @@ jobs: steps: - name: Checkout uses: actions/checkout@v4 + with: + persist-credentials: false - name: Setup .NET uses: actions/setup-dotnet@v4 diff --git a/.gitea/workflows/docker-build.yml b/.gitea/workflows/docker-build.yml index 8ed9f37b9..b34f61097 100644 --- a/.gitea/workflows/docker-build.yml +++ b/.gitea/workflows/docker-build.yml @@ -124,6 +124,8 @@ jobs: steps: - name: Checkout uses: actions/checkout@v4 + with: + persist-credentials: false - name: Resolve the pinned toolchain tag in the registry env: ETV_REGISTRY_AUTH: ${{ secrets.REGISTRY_USER }}:${{ secrets.REGISTRY_PASSWORD }} @@ -147,6 +149,7 @@ jobs: - name: Checkout uses: actions/checkout@v4 with: + persist-credentials: false # git history/tags are needed by the `build` job's `git describe` (ersatztv#190) and, # here, by the #420 revalidate step's `HEAD^2` tree comparison on a main merge commit. fetch-depth: 2 @@ -419,6 +422,7 @@ jobs: - name: Checkout uses: actions/checkout@v4 with: + persist-credentials: false # was the default fetch-depth: 1 (ersatztv#190); bumped to 2 so the #420 revalidate # step's `HEAD^2` tree comparison can resolve on a main merge commit. fetch-depth: 2 @@ -585,6 +589,7 @@ jobs: - name: Checkout uses: actions/checkout@v4 with: + persist-credentials: false # bumped from 1 (ersatztv#190 default) so the #420 revalidate step's `HEAD^2` tree # comparison can resolve on a main merge commit. fetch-depth: 2 @@ -727,6 +732,8 @@ jobs: steps: - name: Checkout uses: actions/checkout@v4 + with: + persist-credentials: false - name: Set up Python uses: actions/setup-python@v5 with: @@ -800,6 +807,7 @@ jobs: - name: Checkout uses: actions/checkout@v4 with: + persist-credentials: false fetch-depth: 0 # ersatztv#416: a docs-only push to main has nothing to rebuild (docs are not in the image), @@ -986,14 +994,21 @@ jobs: - name: Checkout uses: actions/checkout@v4 with: + persist-credentials: false fetch-depth: 0 - name: Detect API-surface changes id: detect run: | base_ref="${{ github.base_ref }}" - git fetch --no-tags --depth=100 origin "$base_ref" || true - changed="$(git diff --name-only "origin/${base_ref}...HEAD" 2>/dev/null || true)" + if ! git fetch --no-tags origin "$base_ref"; then + echo "::error::git fetch of origin/${base_ref} failed, so this job cannot compute the changed-file set it derives its work from. That is a broken job, not an empty change set (ersatztv#746). Check the base branch still exists and that the runner can reach the repository." + exit 1 + fi + if ! changed="$(git diff --name-only "origin/${base_ref}...HEAD")"; then + echo "::error::git diff against origin/${base_ref} failed, so the changed-file set could not be computed — do not read this as 'nothing changed' (ersatztv#746). If it reports no merge base, rebase this branch onto ${base_ref}." + exit 1 + fi echo "Changed files in this PR:"; printf '%s\n' "$changed" if printf '%s\n' "$changed" | grep -Eq '^ErsatzTV/Controllers/Api/|^ErsatzTV\.Core/Api/'; then echo "api_changed=true" >> "$GITHUB_OUTPUT" @@ -1081,14 +1096,21 @@ jobs: - name: Checkout uses: actions/checkout@v4 with: + persist-credentials: false fetch-depth: 0 - name: Detect changed C# files id: detect run: | base_ref="${{ github.base_ref }}" - git fetch --no-tags --depth=100 origin "$base_ref" || true - changed="$(git diff --name-only --diff-filter=ACM "origin/${base_ref}...HEAD" -- '*.cs' 2>/dev/null || true)" + if ! git fetch --no-tags origin "$base_ref"; then + echo "::error::git fetch of origin/${base_ref} failed, so this job cannot compute the changed-file set it derives its work from. That is a broken job, not an empty change set (ersatztv#746). Check the base branch still exists and that the runner can reach the repository." + exit 1 + fi + if ! changed="$(git diff --name-only --diff-filter=ACM "origin/${base_ref}...HEAD" -- '*.cs')"; then + echo "::error::git diff against origin/${base_ref} failed, so the changed-file set could not be computed — do not read this as 'nothing changed' (ersatztv#746). If it reports no merge base, rebase this branch onto ${base_ref}." + exit 1 + fi echo "Changed .cs files in this PR:"; printf '%s\n' "$changed" if [ -n "$changed" ]; then printf '%s\n' "$changed" > /tmp/changed-cs.txt diff --git a/.gitea/workflows/pr-checks.yml b/.gitea/workflows/pr-checks.yml index a667e9b59..8f39aef05 100644 --- a/.gitea/workflows/pr-checks.yml +++ b/.gitea/workflows/pr-checks.yml @@ -62,6 +62,7 @@ jobs: - name: Checkout uses: actions/checkout@v4 with: + persist-credentials: false # need real history: `git log -- ` on a shallow clone can't find the last # commit that touched the image sources fetch-depth: 0 @@ -138,12 +139,26 @@ jobs: - name: Checkout uses: actions/checkout@v4 with: + persist-credentials: false fetch-depth: 0 + # `continue-on-error` for the same reason the two steps below carry it: this whole job + # is a non-blocking nudge, and an advisory red still joins the combined status the merge gate + # reads. Unmasking the fetch (ersatztv#746) makes a broken base LOUD in the log; it must not + # also make a warn-only job merge-blocking. The three jobs that genuinely gate on this diff — + # api-docs, format, decisions lifecycle — do redden on a failed fetch, which is where that + # belongs. - name: Warn when a screen/route change skips the parity doc + continue-on-error: true run: | base_ref="${{ github.base_ref }}" - git fetch --no-tags --depth=100 origin "$base_ref" || true - changed="$(git diff --name-only "origin/${base_ref}...HEAD" 2>/dev/null || true)" + if ! git fetch --no-tags origin "$base_ref"; then + echo "::error::git fetch of origin/${base_ref} failed, so this job cannot compute the changed-file set it derives its work from. That is a broken job, not an empty change set (ersatztv#746). Check the base branch still exists and that the runner can reach the repository." + exit 1 + fi + if ! changed="$(git diff --name-only "origin/${base_ref}...HEAD")"; then + echo "::error::git diff against origin/${base_ref} failed, so the changed-file set could not be computed — do not read this as 'nothing changed' (ersatztv#746). If it reports no merge base, rebase this branch onto ${base_ref}." + exit 1 + fi echo "Changed files in this PR:"; printf '%s\n' "$changed" screen_or_route=no if printf '%s\n' "$changed" | grep -Eq '^web/src/screens/.+\.tsx$|^ErsatzTV/LegacyUiRedirects\.cs$'; then @@ -169,7 +184,8 @@ jobs: # python-using job on it declares this. Without it a missing interpreter is exit 127 — a RED # advisory job joining the combined status, which is the one thing this step must never be. # - # Both steps carry `continue-on-error` because the SCRIPT exiting 0 is not the whole invariant: + # Both steps OF THIS CHECK (setup-python + the narrative step; the parity nudge above has its + # own) carry `continue-on-error` because the SCRIPT exiting 0 is not the whole invariant: # a setup-python download failure reddens the job just as effectively as a hit would, and an # advisory red still joins the combined status the merge gate reads (ersatztv#598). Scope, # stated rather than implied: this covers the two steps that exist to run the check. A failed @@ -186,7 +202,10 @@ jobs: continue-on-error: true run: | base_ref="${{ github.base_ref }}" - git fetch --no-tags --depth=100 origin "$base_ref" || true + if ! git fetch --no-tags origin "$base_ref"; then + echo "::error::git fetch of origin/${base_ref} failed, so this job cannot compute the changed-file set it derives its work from. That is a broken job, not an empty change set (ersatztv#746). Check the base branch still exists and that the runner can reach the repository." + exit 1 + fi python3 scripts/check-doc-narrative.py --diff "origin/${base_ref}" # BLOCKING (ersatztv#521, supersedes the ersatztv#303 H9 append-only mechanic): validates decision- @@ -204,6 +223,7 @@ jobs: - name: Checkout uses: actions/checkout@v4 with: + persist-credentials: false fetch-depth: 0 - name: Set up Python uses: actions/setup-python@v5 @@ -212,7 +232,10 @@ jobs: - name: Validate decision lifecycle run: | base_ref="${{ github.base_ref }}" - git fetch --no-tags --depth=200 origin "$base_ref" || true + if ! git fetch --no-tags origin "$base_ref"; then + echo "::error::git fetch of origin/${base_ref} failed, so this job cannot compute the changed-file set it derives its work from. That is a broken job, not an empty change set (ersatztv#746). Check the base branch still exists and that the runner can reach the repository." + exit 1 + fi PYTHONPATH=. python3 scripts/decisions_validate.py --base "origin/${base_ref}" --head HEAD - name: Active catalog in sync run: PYTHONPATH=. python3 scripts/build_decisions_catalog.py --check @@ -251,6 +274,7 @@ jobs: # clone would leave it unable to resolve `^` and it would refuse every commit. uses: actions/checkout@v4 with: + persist-credentials: false fetch-depth: 0 - name: Set up Python uses: actions/setup-python@v5 @@ -365,6 +389,8 @@ jobs: steps: - name: Checkout uses: actions/checkout@v4 + with: + persist-credentials: false - name: Set up Python uses: actions/setup-python@v5 with: diff --git a/docs/ci-cd.md b/docs/ci-cd.md index dc5ebaf99..cf1b21cc0 100644 --- a/docs/ci-cd.md +++ b/docs/ci-cd.md @@ -147,6 +147,83 @@ A backup, fetch, or migration-smoke failure aborts before the live container is **Also avoid firing several pushes back-to-back** (e.g. a `[skip ci]` commit, then `main`, then a tag, all within ~1s). Observed once on this Gitea instance: the later events were silently dropped — no `ActionRun` records created at all, even though the runner was online and the workflow `active`. Pushing again, spaced out, created the runs normally. If a push/tag doesn't produce a run, re-push (or push an empty commit) rather than assuming the runner is broken. +## Checkouts drop the persisted credential (ersatztv#746) + +Every `actions/checkout` in this repo **except `ci-image.yml`'s** (see the carve-out below) sets +`persist-credentials: false`. Without it the action leaves an `Authorization` header in +`.git/config`, and a head-resolved job then hands that credential to every script it runs, not just +to the checkout. That header is write-capable: this instance's Actions default token permission is +`permissive`, where it stands after a Restricted trial was reverted on 2026-08-05, and flipping it +back is ersatztv#748. No job that checks out +loses anything: none of them push with git, and anonymous access covers the fetches because the repo +is public — `private: false`, and `GET /info/refs?service=git-upload-pack` answers unauthenticated, +measured 2026-08-26 from the LAN. That measures the repository, not a runner's network path to it, +and the runner path is deliberately not asserted here: it does not need to be, because the fetches +in the jobs below are unmasked: an anonymous fetch that failed from a runner reddens `api-docs`, +`Formatting` and `decisions lifecycle` instead of being swallowed. (The two masked fetches further +down are covered by their own argument, not by this one.) Renovate does push branches, but +`renovate.yml` has no `actions/checkout` step at all and carries its own `RENOVATE_TOKEN`. + +The base-ref fetches that feed the changed-file skip logic — in `docs-reminder`, `decisions +lifecycle`, `api-docs` and `Formatting` — therefore run **unmasked**: a failed `git fetch` — and a failed +`git diff` at the three steps that run one inline — exit the step with an `::error::` instead of +yielding an empty changed set. That ordering is the general rule, not a fact about one +change: unmask a dependent fetch *before* you drop a persisted credential anywhere. Under `|| true` +a credential regression looked like "nothing changed" on the three steps that also masked +`git diff`, so those checks skipped themselves silently on a green job; on the other two it handed +a possibly-absent `origin/` to a Python validator. Neither shape is one you want a credential +change to land on top of. + +**What this does and does not make fail-closed.** A failed *fetch* now reddens `api-docs`, +`Formatting` and `decisions lifecycle`, which is the credential/network case this change exists for. +It does not make the two validator steps fail-closed in general: they run no inline `git diff`, and +if the base resolves badly despite a successful fetch, `scripts/decisions_validate.py` emits a +`::warning::` and skips its diff-dependent checks while `scripts/check-doc-narrative.py` prints +`SCANNED NOTHING` and exits 0. Both fail open there by their own design and are out of scope here — +do not read a green `decisions lifecycle` as proof its diff-dependent checks ran. Note which side of +that line the `Decisions-Edit: yes` trailer check falls on: `_edit_trailer_armed` is reached only +after the merge base resolves, so it goes quiet with the rest of them rather than surviving. + +**Loud is not the same as blocking, and the split is by job.** `api-docs`, `Formatting` and +`decisions lifecycle` gate on this diff, so a failed fetch reddens them. `docs-reminder` does not — +it is a non-blocking nudge, and an advisory red still joins the combined status the merge gate +reads. All three of its non-checkout steps therefore carry `continue-on-error: true` — the parity +nudge, `Set up Python` and the doc-narrative warning — so the `::error::` reaches the log without +turning a warning into a merge block. `Checkout` is deliberately still blocking; with no tree there +is nothing to warn about. + +**None of these fetches passes `--depth`.** All five run in jobs that check out `fetch-depth: 0`, +and `git fetch --depth=N` on a *complete* clone grafts it shallow: the history is still there but +cut off, so `git diff origin/...HEAD` fails with `no merge base` once the branch point is +further back than N. Measured 2026-08-26: a 150-commit repo branched 130 back, `--depth=100`, +`.git/shallow` created, three-dot diff `fatal: no merge base`; the same fetch without `--depth` +returns the correct file list. Under the old `|| true` that surfaced as a silent skip; unmasked it +would have reddened `api-docs` and `Formatting` on any branch not rebased recently, sent +`docs-reminder`'s parity nudge advisory-red, and left `decisions lifecycle` green with its +diff-dependent checks silently skipped — so the depth came off with the mask. The same graft is why `:latest` images ship `InformationalVersion 0.0.0-` (ersatztv#836). + +**Two masked fetches that stay masked, deliberately.** `scripts/ci-detect-docs-only.sh` and +`scripts/ci-detect-already-validated.sh` both swallow a failed fetch — and should. In both, a failed +fetch can only leave the base revision unresolvable, and an unresolvable base emits `false`: *run +the full matrix / full validation*. Neither can turn a failed fetch into a skip. Masking there costs +runner time and nothing else, which is the opposite direction from the workflow steps above, where +the same masking bought a silently skipped check. Judge these by which way the failure falls, not by +the `|| true`. + +That clears their **masking** and nothing else. Their `--depth` is a separate question with a +separate answer: `ci-detect-docs-only.sh`'s push-path `--depth=2` runs inside the `build` job's +`fetch-depth: 0` checkout and grafts it shallow, which is why the `git describe` in the immediately +following step returns nothing and `:latest` ships `InformationalVersion 0.0.0-` — measured on +the live test container as `0.0.0-5a7a4ed7` (ersatztv#836). That depth is correct for the script's +other three consumers — `test`, `migrations` and `functional-e2e` — whose checkouts really are +shallow (`fetch-depth: 2`). `build` is the only one that checks out complete, which is why it is the +only one that grafts. + +**`ci-image.yml` is the one exception** and is tracked in ersatztv#744, which has to change that +file alone: any commit touching `.gitea/workflows/ci-image.yml` re-points `ci-image-pin`'s +`expected` at itself and reddens that blocking job, and the file's unfiltered `push` trigger +publishes a toolchain image from whatever branch the edit lands on. + ## The workflow: `.gitea/workflows/docker-build.yml` Single workflow. Gating jobs `test` + `migrations` run in parallel and gate `build`; a @@ -427,9 +504,10 @@ the image build. job (exit 137); excluding it cuts the instrumented surface ~126× (2.5M→20k coverable lines in the whole-solution `Architecture.Tests` process) and makes the percentage reflect authored code. -- **Shallow checkout**: `fetch-depth: 1` (ersatztv#190) — this job never runs `git - describe`/`git log`, only `build` needs full history/tags for version computation, so - `test` and `migrations` both check out shallow. `build`'s checkout stays `fetch-depth: 0`. +- **Shallow checkout**: `fetch-depth: 2` — this job never runs `git describe`/`git log`, and only + `build` needs full history/tags for version computation, so `test`, `migrations` and + `functional-e2e` all check out shallow. It was 1 (ersatztv#190) until ersatztv#420's revalidate + step needed `HEAD^2` to resolve on a main merge commit. `build`'s checkout stays `fetch-depth: 0`. - **NuGet package cache**: both `test` and `migrations` cache `~/.nuget/packages` via `actions/cache@v4`, keyed on `hashFiles('Directory.Packages.props', 'global.json')` with a `restore-keys` OS-level fallback (ersatztv#190). Avoids a from-scratch `dotnet restore` @@ -548,7 +626,8 @@ files) has nothing for the heavy jobs to validate. Before this, such a change ra is gated `if: steps.detect.outputs.docs_only != 'true'`. On a docs-only change the job runs only checkout + detect and **reports `success` in seconds**. -**Shallow-checkout safe (the change-set diff).** `test`/`migrations` check out `fetch-depth: 1`, and +**Shallow-checkout safe (the change-set diff).** `test`, `migrations` and `functional-e2e` all check +out shallow (`fetch-depth: 2`), and a shallow clone has **no `origin/` tracking ref and no merge-base** — so a three-dot `origin/main...HEAD` diff *errors*, the fail-safe returns `docs_only=false`, and the skip silently never fires (the first cut shipped this bug — every docs-only PR still ran the full matrix; caught by @@ -867,9 +946,11 @@ exists for. Because this step needs an interpreter, the job DOES carry `actions/setup-python` — the one exception to the no-setup-actions note below, since `python3` is not guaranteed on the bare `small` -lane. Both it and the script step carry `continue-on-error: true`: a script that exits 0 does not by -itself keep the JOB green, and a setup-action download failure would redden an advisory check just -as effectively as a hit would. +lane. It, the script step and the parity-doc step above it all carry `continue-on-error: true`: a script +that exits 0 does not by itself keep the JOB green, a setup-action download failure would redden an +advisory check just as effectively as a hit would, and the parity step's base-ref fetch fails loudly +(ersatztv#746) — which must reach the log without reddening a warn-only job. `Checkout` is the one +step left blocking. The job deliberately has **no** `setup-dotnet`/`setup-node` (and thus no `actions/cache`), so it can't hit the cache-save hangs seen on the VM-127 runner diff --git a/docs/decisions/README.md b/docs/decisions/README.md index 928492189..597f37a10 100644 --- a/docs/decisions/README.md +++ b/docs/decisions/README.md @@ -37,7 +37,7 @@ the link for rationale. Superseded/retired history lives in `archive/`. Regenera | `blazor.rollback-tag` | The commit immediately preceding the Blazor-removal merge is tagged `blazor-final` (not a `v*` tag, so it doesn't trigger a prod release build) as the documented rollback/restore path. | 2026-07-11 | [link](records/blazor/rollback-tag.md) | | `blazor.ui-removed` | The legacy Blazor Server UI (`Pages/`, `Shared/`, `ViewModels/`, `Validators/`, MudBlazor + 8 other packages, Blazor Startup wiring) is fully deleted now that the SPA has parity; the legacy `MapWhen` branch is kept only for controllers/docs/OpenAPI/`LegacyUiRedirects`, and the catch-all fallback 302s any unmatched non-api/artwork/docs/openapi path to `/app`. | 2026-07-11 | [link](records/blazor/ui-removed.md) | | `channel.origin-marker` | A new `Channel.Origin` (`ChannelOrigin` enum — `Unknown`/`UserCreated`/`AutoTuned`) records how a channel row was created and is stamped exactly once at insert (`AutoTuned` in `CreateChannelFromLineupHandler`, `UserCreated` in `CreateChannelHandler`), and is never mutated on a later edit. It is surfaced as a raw `origin` field on `ChannelResponseModel`; the SPA badges only `AutoTuned`. Rows predating the column read `Unknown` — provenance is **not** back-filled. | 2026-07-23 | [link](records/channel/origin-marker.md) | -| `ci.actions-credential-scoping` | Any credential reachable from an Actions job is scoped to what that job needs. The container-registry secret `REGISTRY_PASSWORD` is a personal access token scoped `write:package` + `read:repository` — never an account PASSWORD. This matters because Gitea has NO `status` token scope: `POST /repos/{o}/{r}/statuses/{sha}` is gated by `reqRepoWriter(unit.TypeCode)`, so ANY credential that can write the repository can forge `review-verdict/h10`, the required context that is supposed to make merge-consent derived rather than assertable. Package-write IS a separate scope, so the registry credential can be made status-incapable at no cost: `scripts/ci-detect-already-validated.sh` only GETs. Do NOT add a `permissions:` key to constrain the injected `GITEA_TOKEN` on the assumption that it binds — below Gitea 1.26.0 it is silently a NO-OP, which is worse than absent because it reads in review as a constraint. That version precondition NO LONGER HOLDS: this instance was upgraded 1.25.4 -> 1.27.1 on 2026-08-05. What has NOT changed is that the consequence is unverified — whether `permissions:` is honored here, and what this instance's default Actions token permission is, were both left UNPROBED (there is still no API surface: `/api/v1/settings/actions` 404s at 1.27.1). Probe before relying on it; do not read the upgrade alone as the constraint now working. Scoping is necessary and not sufficient: it bounds what a job may DO, never whether attacker YAML runs at all, so a self-referencing trigger needs its own filter (`ci-image.yml`, tracked in #744 — deliberately NOT bundled here, because editing that file re-points `ci-image-pin` at the editing commit and reddens a blocking job). This record closes ONE route. It does not close the class, and four later sections say exactly what survives — read them before citing this record as a mitigation. | 2026-08-05 | [link](records/ci/actions-credential-scoping.md) | +| `ci.actions-credential-scoping` | Any credential reachable from an Actions job is scoped to what that job needs. The container-registry secret `REGISTRY_PASSWORD` is a personal access token scoped `write:package` + `read:repository` — never an account PASSWORD. This matters because Gitea has NO `status` token scope: `POST /repos/{o}/{r}/statuses/{sha}` is gated by `reqRepoWriter(unit.TypeCode)`, so ANY credential that can write the repository can forge `review-verdict/h10`, the required context that is supposed to make merge-consent derived rather than assertable. Package-write IS a separate scope, so the registry credential can be made status-incapable at no cost: `scripts/ci-detect-already-validated.sh` only GETs. Do NOT add a `permissions:` key to constrain the injected `GITEA_TOKEN` on the assumption that it binds — below Gitea 1.26.0 it is silently a NO-OP, which is worse than absent because it reads in review as a constraint. That version precondition NO LONGER HOLDS: this instance was upgraded 1.25.4 -> 1.27.1 on 2026-08-05. What has NOT changed is that the consequence is unverified — whether `permissions:` is honored here is still UNPROBED, and there is still no API surface for it (`/api/v1/settings/actions` 404s at 1.27.1). The instance default HAS since been probed and is NOT unknown: it was set to Restricted, verified, and reverted to `permissive` on 2026-08-05 (#748), which is where it stands. Probe before relying on it; do not read the upgrade alone as the constraint now working. Scoping is necessary and not sufficient: it bounds what a job may DO, never whether attacker YAML runs at all, so a self-referencing trigger needs its own filter (`ci-image.yml`, tracked in #744 — deliberately NOT bundled here, because editing that file re-points `ci-image-pin` at the editing commit and reddens a blocking job). A second, separate consequence of the same boundary: `actions/checkout` persists a write-capable credential into `.git/config` unless `persist-credentials: false` is set, and 15 of this repo's 16 checkouts now set it (#746), `ci-image.yml`'s being excluded for the reason in that section. Ordering is part of the rule: unmask the dependent fetches FIRST, because until then a credential regression presents as an empty changed-file set and a silently skipped check rather than a red job. This record closes ONE route. It does not close the class, and the later sections say exactly what survives — read them before citing this record as a mitigation. | 2026-08-05 | [link](records/ci/actions-credential-scoping.md) | | `ci.batch-pushes-no-cancel-route` | Hold review fixes, doc corrections and format fixes locally and push **once** — a superseded run cannot be cancelled from the agent side and holds a runner slot until it finishes. | 2026-07-21 | [link](records/ci/batch-pushes-no-cancel-route.md) | | `ci.build-once-rejected` | CI build-once (a shared compile artifact across jobs) was implemented, measured, and rejected for a 40-85% wall-clock regression; keep the #420 cross-run tree-identity skip instead. | 2026-07-18 | [link](records/ci/build-once-rejected.md) | | `ci.cancelled-is-not-a-verdict` | Treat a `cancelled` conclusion as "no verdict" — never as pass or fail — and report FAILED and CANCELLED counts separately in any CI monitor. THE COMBINED COMMIT-STATUS ENDPOINT CANNOT EXPRESS THIS: `GET /repos/{o}/{r}/commits/{sha}/status` has states `success`/`failure`/`pending`/`error` and NO `cancelled`, so it reports a cancelled job as `failure`. Anything polling that endpoint — which is what a CI monitor naturally polls, because it is the per-sha view the merge gate reads — must resolve the job-level `conclusion` via `actions/runs/{id}/jobs` before reporting a red. | 2026-07-21 | [link](records/ci/cancelled-is-not-a-verdict.md) | diff --git a/docs/decisions/records/ci/actions-credential-scoping.md b/docs/decisions/records/ci/actions-credential-scoping.md index d3335546c..8196605db 100644 --- a/docs/decisions/records/ci/actions-credential-scoping.md +++ b/docs/decisions/records/ci/actions-credential-scoping.md @@ -5,8 +5,8 @@ status: active since: '2026-08-05' supersedes: none superseded-by: none -rule: 'Any credential reachable from an Actions job is scoped to what that job needs. The container-registry secret `REGISTRY_PASSWORD` is a personal access token scoped `write:package` + `read:repository` — never an account PASSWORD. This matters because Gitea has NO `status` token scope: `POST /repos/{o}/{r}/statuses/{sha}` is gated by `reqRepoWriter(unit.TypeCode)`, so ANY credential that can write the repository can forge `review-verdict/h10`, the required context that is supposed to make merge-consent derived rather than assertable. Package-write IS a separate scope, so the registry credential can be made status-incapable at no cost: `scripts/ci-detect-already-validated.sh` only GETs. Do NOT add a `permissions:` key to constrain the injected `GITEA_TOKEN` on the assumption that it binds — below Gitea 1.26.0 it is silently a NO-OP, which is worse than absent because it reads in review as a constraint. That version precondition NO LONGER HOLDS: this instance was upgraded 1.25.4 -> 1.27.1 on 2026-08-05. What has NOT changed is that the consequence is unverified — whether `permissions:` is honored here, and what this instance''s default Actions token permission is, were both left UNPROBED (there is still no API surface: `/api/v1/settings/actions` 404s at 1.27.1). Probe before relying on it; do not read the upgrade alone as the constraint now working. Scoping is necessary and not sufficient: it bounds what a job may DO, never whether attacker YAML runs at all, so a self-referencing trigger needs its own filter (`ci-image.yml`, tracked in #744 — deliberately NOT bundled here, because editing that file re-points `ci-image-pin` at the editing commit and reddens a blocking job). This record closes ONE route. It does not close the class, and four later sections say exactly what survives — read them before citing this record as a mitigation.' -signals: 'admin password in CI secrets, registry credential scope, ETV_STATUS_AUTH can write statuses, forge review-verdict/h10, head-resolved workflow holds credentials, Gitea token scopes, no status scope, write:package vs write:repository, permissions key no-op, GITEA_TOKEN default read/write, Restricted default token permissions, orphan secret, deploy key in secret store, toolchain image overwrite, prod floating tag write · paths: `.gitea/workflows/docker-build.yml`, `.gitea/workflows/ci-image.yml`, `.gitea/workflows/renovate.yml`, `scripts/ci-detect-already-validated.sh` · issues: #697, #672, #698, #742, #743, #420, server-management#714' +rule: 'Any credential reachable from an Actions job is scoped to what that job needs. The container-registry secret `REGISTRY_PASSWORD` is a personal access token scoped `write:package` + `read:repository` — never an account PASSWORD. This matters because Gitea has NO `status` token scope: `POST /repos/{o}/{r}/statuses/{sha}` is gated by `reqRepoWriter(unit.TypeCode)`, so ANY credential that can write the repository can forge `review-verdict/h10`, the required context that is supposed to make merge-consent derived rather than assertable. Package-write IS a separate scope, so the registry credential can be made status-incapable at no cost: `scripts/ci-detect-already-validated.sh` only GETs. Do NOT add a `permissions:` key to constrain the injected `GITEA_TOKEN` on the assumption that it binds — below Gitea 1.26.0 it is silently a NO-OP, which is worse than absent because it reads in review as a constraint. That version precondition NO LONGER HOLDS: this instance was upgraded 1.25.4 -> 1.27.1 on 2026-08-05. What has NOT changed is that the consequence is unverified — whether `permissions:` is honored here is still UNPROBED, and there is still no API surface for it (`/api/v1/settings/actions` 404s at 1.27.1). The instance default HAS since been probed and is NOT unknown: it was set to Restricted, verified, and reverted to `permissive` on 2026-08-05 (#748), which is where it stands. Probe before relying on it; do not read the upgrade alone as the constraint now working. Scoping is necessary and not sufficient: it bounds what a job may DO, never whether attacker YAML runs at all, so a self-referencing trigger needs its own filter (`ci-image.yml`, tracked in #744 — deliberately NOT bundled here, because editing that file re-points `ci-image-pin` at the editing commit and reddens a blocking job). A second, separate consequence of the same boundary: `actions/checkout` persists a write-capable credential into `.git/config` unless `persist-credentials: false` is set, and 15 of this repo''s 16 checkouts now set it (#746), `ci-image.yml`''s being excluded for the reason in that section. Ordering is part of the rule: unmask the dependent fetches FIRST, because until then a credential regression presents as an empty changed-file set and a silently skipped check rather than a red job. This record closes ONE route. It does not close the class, and the later sections say exactly what survives — read them before citing this record as a mitigation.' +signals: 'admin password in CI secrets, registry credential scope, ETV_STATUS_AUTH can write statuses, forge review-verdict/h10, head-resolved workflow holds credentials, persist-credentials on actions/checkout, credential left in .git/config, masked git fetch yields empty changed set, Gitea token scopes, no status scope, write:package vs write:repository, permissions key no-op, GITEA_TOKEN default read/write, Restricted default token permissions, orphan secret, deploy key in secret store, toolchain image overwrite, prod floating tag write · paths: `.gitea/workflows/docker-build.yml`, `.gitea/workflows/pr-checks.yml`, `.gitea/workflows/dependency-scan.yml`, `.gitea/workflows/ci-image.yml`, `.gitea/workflows/renovate.yml`, `scripts/ci-detect-already-validated.sh` · issues: #697, #672, #698, #742, #743, #746, #748, #835, #420, server-management#714' mechanics: 'PAT `ci-registry-scoped-697`, scopes `write:package,read:repository`, stored as repo Actions secret `REGISTRY_PASSWORD`; `REGISTRY_USER` remains `timothy`. Verified 2026-08-05 on Gitea 1.25.4: registry push of a probe tag SUCCEEDED; `GET /commits/{sha}/status` 200; `POST /statuses/{sha}` REFUSED HTTP 403 `token does not have at least one of required scope(s), required=[write:repository], token scope=write:package,read:repository`. Probe artifacts deleted, confirmed 404. NOT measured with this token: the `container:` pull, the buildcache write and the base-image pull. Those rest on Gitea''s scope model (write implies read per category, read at tag `v1.25.4`) — INFERRED. Note WHICH run proves which: only the `container:` pull is exercised by a PR. `cache-to`/`cache-from` and the base-image pull are confined to the `build` job, which carries `if: github.event_name != ''pull_request''`, so they are first exercised on the post-merge push to `main` — AFTER the merge gate has passed. A wrong inference there reddens main, not the PR.' --- @@ -51,8 +51,37 @@ code can no longer escalate to instance admin — NOT that the durable forgery r bound — auditing it rather than the workflow set is what found `RENOVATE_TOKEN` and `SERVERMGMT_DEPLOY_KEY` below, since any PR-added workflow can reference any secret. But `GITEA_TOKEN` is injected and never in the store; nor is the credential -`actions/checkout` persists into `.git/config` (`docker-build.yml` omits `persist-credentials: false`); -and jobs reach the runner's docker daemon. +`actions/checkout` persists into `.git/config` (dropped on 15 of the repo's 16 checkouts in #746; +`ci-image.yml` is excluded and is head-resolved in the sense that matters — see below); and jobs +reach the runner's docker daemon. + +**The persisted checkout credential (#746).** `actions/checkout` writes an `Authorization` header +into `.git/config` unless `persist-credentials: false` is set, so a job hands that credential to +every script it runs, not only to the checkout — and it is write-capable while this instance's +Actions default token permission is `permissive` — where it stands after a Restricted trial was +reverted on 2026-08-05 (#748). 15 of the repo's 16 checkouts +now set it: `docker-build.yml` (8), `pr-checks.yml` (5), `dependency-scan.yml` (1) and +`review-verdict.yml` (1, pre-existing). No job that checks out pushes with git, so none of them +loses a capability; `renovate.yml` does push, but has no checkout step and uses `RENOVATE_TOKEN`. + +**Unmask the dependent fetches BEFORE dropping a persisted credential** — the rule, not a note about +one change. Five steps fed `git fetch ... origin "$base_ref" || true` into changed-file skip logic, +where a credential regression reddens nothing: on the three that also masked `git diff` it yields an +empty changed set the skip logic reads as "nothing changed", and on the other two it hands a +possibly-absent `origin/` to a validator. Anonymous fetch does cover this repo (public; `git-upload-pack` answers +unauthenticated, measured 2026-08-26), which is a reason to make the failure loud rather than a +reason to trust it silently. The same step is where `--depth` came off those fetches: their jobs +check out `fetch-depth: 0`, and `git fetch --depth=N` grafts a complete clone shallow, so a +three-dot diff against a branch point further back than N fails `no merge base` — invisible under +`|| true`, and without it a red `api-docs`/`Formatting` (`decisions lifecycle` would stay green with +its diff-dependent checks skipped, because its validator fails open on an unresolvable base). + +`ci-image.yml`'s single checkout is the one exception, and NOT because it is safe: its unfiltered +`push` trigger makes it head-resolved in the sense that matters. It is excluded because editing that +file re-points `ci-image-pin`'s `expected` at the editing commit and reddens a blocking job, and +because the same trigger would publish a toolchain image from the editing branch. It rides with +#744, which exists to change that file alone. #835 tracks the guard for this convention: it can only +be written without an exemption list once #744 has landed. **Measured vs inferred.** Measured here: the `v1.25.4` scope enum (`access_token_scope.go`) has no `status` entry; the `reqRepoWriter` gate (`routers/api/v1/api.go`); the probes in `mechanics`. Read from @@ -69,9 +98,12 @@ re-probing. Re-verification of the 1.25.4-pinned claims across the CI docs is tr **Surviving routes — this record is not a mitigation for any of them.** `RENOVATE_TOKEN` is a `write:repository` bot PAT in the same store, posting with a real creator, and cannot be scoped down because Renovate needs repo write (#742). The injected `GITEA_TOKEN` is write-capable in every job; -only Gitea >=1.26 with the Actions default set to **Restricted** binds it (server-management#714) — -the version half of that condition is now satisfied (1.27.1) but the *default* half is unverified, so -treat this route as still open until probed. A +only Gitea >=1.26 with the Actions default set to **Restricted** binds it (server-management#714). +Both halves of that condition have now been checked and it does not hold, because of the second one: +the version half IS satisfied (1.27.1), while the default was set to Restricted, verified, and +reverted to `permissive` on 2026-08-05 because this repo is not ready for it (#748). So the route is +open, and open for a known reason rather than an unprobed one — waiting on a further Gitea upgrade +would be waiting on the wrong thing. A collaborator's own token always can. `docker-build.yml` publishes `:prod` from a `v*` tag push and a tag may point at ANY commit — a prod image with no PR, review or status (tag protections are empty). **And none of it was necessary: direct pushes to `main` were server-side permitted, so the gate was diff --git a/docs/decisions/records/ci/docs-only-detect-shallow-safe.md b/docs/decisions/records/ci/docs-only-detect-shallow-safe.md index aaf00dbe0..9f7da5922 100644 --- a/docs/decisions/records/ci/docs-only-detect-shallow-safe.md +++ b/docs/decisions/records/ci/docs-only-detect-shallow-safe.md @@ -11,7 +11,9 @@ mechanics: '`docs/ci-cd.md` → "Docs-only skip"; verified via a real shallow `f --- The #416 docs-only skip shipped (#422) safe but **ineffective**: every docs-only PR still ran the full -matrix. Root cause — `test`/`migrations` check out `fetch-depth: 1`, and in a shallow clone +matrix. Root cause — the consumer jobs check out shallow (`fetch-depth: 1` then, 2 now, and the +consumers are `test`, `migrations` and `functional-e2e`; both depths are shallow, so the rule is +unaffected by the change), and in a shallow clone `origin/` has no remote-tracking ref and there is no merge-base, so the detect script's three-dot `git diff origin/main...HEAD` errored → `|| true` → empty diff → the fail-safe returned `docs_only=false` → full matrix. Confirmed in a real shallow `file://` clone (`origin/main` did not diff --git a/docs/decisions/records/release/main-direct-push-disabled.md b/docs/decisions/records/release/main-direct-push-disabled.md index 8ace6099e..576bed3af 100644 --- a/docs/decisions/records/release/main-direct-push-disabled.md +++ b/docs/decisions/records/release/main-direct-push-disabled.md @@ -60,16 +60,15 @@ rather than assumed: from one worktree, the branch push to `main` was refused an Do not conflate the two mechanisms — disabling branch push says nothing about tags, and a future tag-protection rule would not inherit from this one. -**The `docker-build.yml` `persist-credentials` question (#743's fourth box), decided and deferred.** -Its six `actions/checkout` steps omit `persist-credentials: false`, so a head-resolved job keeps a -write-capable credential in `.git/config`. It *should* be set — but not blind, and not in this PR, -because two steps run `git fetch --no-tags --depth=100 origin "$base_ref" || true` and feed the result -into the changed-file skip logic. That `|| true` means a credential regression does not fail the job; -it silently yields an empty changed-file set, and the skip logic then reads "nothing changed". The repo -is public, so anonymous fetch is *expected* to cover it — expected is not measured, and the failure -mode is silent, which is the shape that has burned this repo before. The correct order is: drop the -`|| true` masking so a fetch failure is loud, then set `persist-credentials: false` and confirm both -jobs still compute a non-empty changed set on a PR that genuinely changes files. +**The `docker-build.yml` `persist-credentials` question (#743's fourth box), since resolved in #746.** +Head-resolved jobs kept a write-capable credential in `.git/config` because their `actions/checkout` +steps omitted `persist-credentials: false`. Setting it was right but not safe to do blind, and the +ordering is the part worth keeping, as a rule for the next time: unmask the dependent fetches first, +then set the flag. Under `|| true` a credential regression does not fail the job — it yields an empty +changed-file set that the skip logic reads as "nothing changed". The population is also wider than the +six checkouts #743 recorded: eight in `docker-build.yml`, five in `pr-checks.yml`, one in +`dependency-scan.yml`, plus `review-verdict.yml`'s pre-existing one — 15 of the repo's 16. Details in +`ci.actions-credential-scoping`. **Why this is not redundant with the Husky pre-push hooks.** `.husky/pre-push` guards (H6 done-when, H11 rebase, H13 clean worktree) are client-side and deliberately fail-open — a git hook cannot prompt. diff --git a/scripts/ci-detect-docs-only.sh b/scripts/ci-detect-docs-only.sh index edc5a00aa..01f046b13 100755 --- a/scripts/ci-detect-docs-only.sh +++ b/scripts/ci-detect-docs-only.sh @@ -38,7 +38,8 @@ if [ "${GITHUB_REF_TYPE:-}" = "tag" ]; then fi # Resolve a concrete BASE COMMIT to diff HEAD against. SHALLOW-CHECKOUT SAFE (ersatztv#416 -# follow-up): the `test`/`migrations` jobs check out `fetch-depth: 1`, and a shallow clone has NO +# follow-up): the `test`/`migrations`/`functional-e2e` jobs check out shallow (`fetch-depth: 2`), and +# a shallow clone has NO # `origin/` remote-tracking ref and no merge-base — so the old `origin/...HEAD` # (three-dot) errored, the diff came back empty, and EVERY docs-only PR silently ran the full # matrix (safe but useless). `git fetch` ALWAYS writes FETCH_HEAD (the fetched base tip), which -- 2.47.3