home-network-k3s-impl/.gitea/workflows/README.md

# CI merge gate — `.gitea/workflows/`

**Task T-0.2 · Requirements R-GITOPS-01, R-TEST-02, R-TEST-03 · Owner WS-GITOPS (CI).**

This is the **merge gate** for the home k3s + Longhorn platform. It enforces the gating rules in the
spec ([`docs/14-testing-and-conformance.md`](../../../home-network-k3s/docs/14-testing-and-conformance.md),
[ADR-0010](../../../home-network-k3s/decisions/adr-0010-conformance-testing.md),
[ADR-0011](../../../home-network-k3s/decisions/adr-0011-test-tooling-kyverno-chainsaw.md)) as a
Gitea Actions pipeline: **no change lands on `main` unless the conformance subset for the requirements
it touches is green** (R-TEST-03).

> **Done is a green, reproducible, requirement-tagged test — never "merged," never a demo.** This gate
> is the machine that enforces it.

## The pipeline

```
 decisions-log ─▶ lint ─▶ l0 (schema + Kyverno) ─▶ render-golden ─▶ l1 (rendering) ─▶ conformance (L2/L3) ─▶ merge-gate decision
 └──────────────── run in CI, NO cluster ────────────────┘        └── in-cluster Chainsaw Job ──┘
                    live now                              cluster-gated (SKIPS in Phase 0)
```

| Stage | Job | Layer | Verifies | Cluster? |
|---|---|---|---|---|
| yaml/lint | `lint` | — | YAML well-formed (`ci/yamllint.yaml`) | no — **live now** |
| schema | `l0` | L0 | ServiceDefinitions valid against `schemas/` | no — **live now** |
| Kyverno L0 | `l0` | L0 | `kyverno test platform/kyverno/`: default-deny baseline present, no plaintext secrets, required labels/egress-class, schema conformance | no — **live now** |
| L1 rendering | `l1` | L1 | ServiceDefinition → rendered resources match golden expectations (Chainsaw L1 via `conformance/`) | no — **live now** |
| conformance | `conformance` | L2+L3 | Real runtime behavior + fault-injection, as an **in-cluster Chainsaw Job** CI triggers and awaits | **yes — cluster-gated** |
| decision | `merge-gate` | — | Applies R-TEST-03 over the above; blocks merge on any failure | no |

Each stage is a thin wrapper over a `ci/*.sh` script, so **CI and a laptop run the identical gate**
(R-TEST-02). See [`../../ci/README.md`](../../ci/README.md).

### Why L2/L3 is an in-cluster Job (not run by CI directly)

Per [`docs/14` §"Where each layer runs"](../../../home-network-k3s/docs/14-testing-and-conformance.md)
and ADR-0011: **CI holds no broad kubeconfig.** L2/L3 run as an in-cluster **Chainsaw Job** whose own
**scoped test ServiceAccount** holds cluster access (R-SEC-02). CI only *triggers* the Job and
*collects* its artifacts, using a narrow trigger credential referenced **by secret name only**
(`secrets.CONFORMANCE_TRIGGER_KUBECONFIG`) — never a plaintext secret, never a cluster-admin kubeconfig.

## Honest SKIP — never fake green

**NOTE (2026-09-29):** this section is written in the past's voice — "Phase 0", "no cluster
exists". **A cluster has existed for weeks** and Flux has been reconciling against it. The
skip logic below is still correct and still honest, but read it as describing a **live
coverage gap** (L2/L3 is not wired into CI) rather than an expected phase. Its being
phrased as a phase is part of why the gap went unexamined.

Originally: The gate is deliberately built so unavailable checks **SKIP loudly,
they do not pass**:

- The `conformance` job is `if: ${{ vars.CLUSTER_AVAILABLE == 'true' }}` — with no cluster it is
  **skipped** by Gitea (shown as skipped, not green). The `merge-gate` decision then reports any
  touched requirement that needs L2/L3 as **UNVERIFIED**, not satisfied.
- Stages whose owning subtree is still a placeholder (`schemas/`, `platform/kyverno/`, `conformance/`)
  report **SKIPPED — unwired**, distinct from a pass, until those seams are delivered.

The decision matrix (`scripts/decide.sh`):

| Situation | Outcome |
|---|---|
| Any of lint/l0/l1 **fails** | **BLOCK** |
| conformance **fails/cancelled** | **BLOCK** |
| conformance **skipped** while `CLUSTER_AVAILABLE=true` | **BLOCK** (it should have run) |
| conformance **skipped**, no cluster, touched reqs need L2/L3 | **UNVERIFIED** — reported, not green; blocks only if `REQUIRE_CLUSTER_TESTS=true` |
| lint/l0/l1 green, no cluster-needing reqs touched | **PASS** |

`REQUIRE_CLUSTER_TESTS` is `false` in Phase 0 (bootstrap: seams and cluster don't exist yet) and flips
to `true` from Phase 1 once a dev/test cluster is declared — from then on, any touched requirement that
can't be verified is a hard block.

## Artifacts (R-TEST-04 traceability)

Every layer emits machine-readable output collected by the `merge-gate`:
- **JUnit XML** → `results/junit/*.xml` (uploaded as `l1-junit-coverage` / `conformance-junit-coverage`).
- **Requirement-coverage report** → `reports/coverage/**` — maps every `R-*` to its verifying test(s);
  uncovered requirements are visible gaps. Produced by the conformance runner (`conformance/`, WS-TEST).

Both dirs are git-ignored (see [`.gitignore`](../../.gitignore)).

## Triggers & branch model (CONTRIBUTING.md)

- `pull_request` → `main`: **PRs are the enforced merge gate into `main`.**
- `push` → `main` only. The per-branch prefix list was removed: `act_runner` runs at capacity 1,
  so a branch push fires a redundant run that serialises *ahead* of the PR run for the same tree.
  **No work on `main`** — and since 2026-09-29 that is enforced, not conventional: `main` is a
  protected branch and a direct push is rejected by the pre-receive hook (verified, not assumed).

## Transition: COMPLETE (2026-09-29)

This section used to describe a migration as pending. It has happened. Gitea is live at
`gitea.home.keithjackson.dev`, the runner `incluster-dind` is registered and online, and
`gate.yml` runs on every PR.

**What took a month to notice:** the migration was recorded as done on 2026-08-31 without
anyone checking the platform. In reality `main` had **no branch protection** and **zero
runners were registered** until 2026-09-29. Every "the gate enforces this" statement in
between rested on an assertion nobody verified. PR #1 — the first pull request this
repository ever had — sat `pending` for 30.6 minutes because nothing existed to run it.

So: **do not read this file, or the DECISIONS-LOG, as evidence about the live platform.**
Query the API. `infra/gitea/` holds the scripts and the measured state.

Still genuinely outstanding: `vars.CLUSTER_AVAILABLE` and
`secrets.CONFORMANCE_TRIGGER_KUBECONFIG` are unset, so L2/L3 conformance does not run in
CI. That is a real coverage gap, not a phase.

## Configuration (set in Gitea; referenced by name only)

| Kind | Name | Purpose |
|---|---|---|
| variable | `CLUSTER_AVAILABLE` | `'true'` once a dev/test cluster exists → L2/L3 run and are required; else they SKIP |
| variable | `REQUIRE_CLUSTER_TESTS` | `'true'` (Phase 1+) makes unverified cluster-needing touched reqs a hard block |
| secret | `CONFORMANCE_TRIGGER_KUBECONFIG` | narrow creds to create/await the in-cluster Chainsaw Job (not cluster-admin) |

## How images are built

This repo's three images — `toolbox` (`infra/devcontainer/`), `agent-runner` (`infra/agent/`,
built `FROM` the toolbox) and `conformance-runner` (`conformance/incluster/`) — are built,
verified and published by [`images.yaml`](images.yaml), never from a workstation
(operator rule, 2026-10-29). The logic is in [`scripts/images.sh`](scripts/images.sh).

**The builder is rootless BuildKit** ([`platform/buildkit/`](../../platform/buildkit/README.md)),
reached over mTLS with a pinned `buildx` — no job here touches a Docker daemon, privileged or
otherwise (operator decision on PR #81). The client certificate reaches jobs as the Actions
secrets `BUILDKIT_CA`, `BUILDKIT_CLIENT_CERT`, `BUILDKIT_CLIENT_KEY`.

**Verification is a build target.** Each Containerfile ends in a `verify` stage that runs every
in-image assertion at build time as the non-root uid with `RUN --network=none` (tool presence and
pinned versions, `PM_SELFTEST=1 pm-dispatch`, the pm-worker probe, the `conformance-clone`
refusals, no writable path outside the workspace). The pipeline builds `<image>-verify` before it
builds, let alone pushes, the image. Build args come from each image's own
`build-image.sh --print-build-args`, which is also the local podman path — so the recipe and the
proof exist once.

| Trigger | What happens |
|---|---|
| pull request touching an image's inputs | build + verify only. Nothing is pushed and **no registry credential is referenced** |
| push to `main` touching an image's inputs | build + verify + publish to `gitea.home.keithjackson.dev/home-network/<image>` as `sha-<commit>` (immutable) and `main` (moving); the **registry-returned** digest is in the job summary |
| `workflow_dispatch` | the same as a push when run on `main` (all images by default); verify-only elsewhere |

Only images whose inputs changed are built. The publish job **never writes to git**: Renovate
follows each image's `main` tag through a `# renovate-digest:` marker next to every digest
reference (`platform/pm-agent/`, `infra/agent/versions.env`, `conformance/versions.env`) and
opens the bump PR, which goes through the gate like anything else. A PR opened with the Actions
token would not trigger the required gate, which is why it is Renovate's job and not this one's.

Credential: the repository secret **`REGISTRY_PUSH_TOKEN`** (scope `write:package`, owned by an
account with package write on the org). The automatic Actions token cannot push in Gitea 1.24.3
— the reasoning, with source citations, is in the header of `images.yaml`. Retention:
[`infra/gitea/registry-retention.sh`](../../infra/gitea/registry-retention.sh), an operator
action, keeps every digest git pins plus the newest tags.

Cost: the job shares the single act_runner slot with the gate, but the build itself runs in the
`buildkitd` pod, not in DinD, so the runner's disk and memory are untouched. Until
`platform/buildkit` is deployed and its client certificate copied
(`infra/gitea/buildkit-client-secret.sh`), the job fails loudly at its builder preflight.

## Files

```
.gitea/workflows/
  merge-gate.yaml            the pipeline (lint → l0 → l1 → conformance → decision)
  images.yaml                build/verify/publish this repo's container images (see above)
  cve-triage.yaml            scheduled CVE triage bot (R-VULN-05/07, ADR-0027; runs before Renovate)
  scripts/
    install-tools.sh         installs the pinned tools per stage (from ci/versions.env) — used by the
                             dormant merge-gate.yaml blueprint only; gate.yml runs in the toolbox image
    decide.sh                the R-TEST-03 merge decision over job results
    images.sh                the image pipeline's driver (what to build, base, push, digest)
    cve_triage.py            the CVE triage bot: reads the scanner report, maintains the counts-only
                             CVE Dashboard issue, ticks Renovate approval rows (cve-triage.yaml)
  README.md                  this file
```

The stage logic itself lives in [`../../ci/`](../../ci/) so it is reusable locally and in CI.