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