tiny-pattern-ts/development/ci.md

# CI

The pipeline definition is [.gitea/workflows/ci.yml](../.gitea/workflows/ci.yml);
that file, not this prose, is the source of truth for the job graph. This file
records why the pipeline and its runner image are shaped the way they are.

## Pipeline

- **`build`** (push to `main` / tag) — build + correctness + packaging.
- **`maintain`** (push to `main`, non-blocking) — `npm run maintain`; it reports
  and never fails the build.
- **`publish`** (tag) — packaging checks + `publish:publint` / `publish:attw`,
  then the Gitea release page and `npm publish`. See
  [publishing.md](./publishing.md).
- **`release-gate`** — recognizes a `:rocket: Release x.y.z` commit and skips the
  `build`/`maintain` jobs, because `create:release` pushes the tag for the exact
  same commit right after and the tag run is authoritative. It uses no Node and
  stays on the runner's default image.

## Runner image

#### Decision (2026-09)

The `build` / `maintain` / `publish` jobs run in
`gitea.e1nsnull.de/tmu/act-ci:<version>`
([docker/Dockerfile](../docker/Dockerfile)) — the runner's default act image
with the Node distribution overlaid at the exact `/opt/hostedtoolcache` layout
`actions/setup-node` probes before downloading.

#### Why

- No job pays the ~50 MB Node fetch, because the probe hits the baked entry.
- The image tag must equal the exact version pinned in
  [.node-version](../.node-version), and the image is rebuilt only as part of a
  Node bump — there is no other trigger.
- Building requires a docker daemon and registry credentials, so it belongs to
  no feedback tier. This is why it is deliberately **not** an `npm run` script:
  per the [script prefix convention](./workflow.md#script-prefix-convention), no
  existing prefix fits and that is the signal.

#### Rejected

- Downloading Node in every job: the ~50 MB fetch per job was the original
  problem.
- Gitea Pages / Codecov for coverage: neither was confirmed available or wanted
  (see [Coverage serving](#coverage-serving)).

## Bumping Node

Bumping Node is one coordinated change, committed as a unit:

1. Edit [.node-version](../.node-version) to the new exact `x.y.z` — floats like
   `26` resolve to the latest patch at runtime and silently bust the baked
   entry; [scripts/runner-image.sh](../scripts/runner-image.sh) refuses them.
2. `docker login gitea.e1nsnull.de` (user + package/access token), then
   `./scripts/runner-image.sh --push` — it reads the version from `.node-version`
   and builds/pushes `<IMAGE_REPO>:<version>`.
3. Repoint the three `container.image` tags in
   [.gitea/workflows/ci.yml](../.gitea/workflows/ci.yml) to the same version.

Skipping step 2 fails CI at image pull; skipping step 3 silently reverts to the
per-job download.

## Image invariants

Two invariants the image must satisfy for the `setup-node` probe to hit, both
easy to break:

### The `x64.complete` marker

#### Decision (2026-09)

Bake a `<version>/<arch>.complete` marker next to the Node directory.

#### Why

- `actions/tool-cache` accepts a cached tool only when
  `<version>/<arch>.complete` exists next to the directory (`tc.find()` checks
  it). A plausible-looking `node/<version>/x64/` alone is ignored and the
  download happens anyway. See the comment in
  [docker/Dockerfile](../docker/Dockerfile).

### Tag freshness, with force-pull deliberately off

#### Decision (2026-09)

Leave `act_runner`'s `force_pull` disabled.

#### Why

- The tag encodes only the Node version, and the image is rebuilt only when that
  version changes — so the normal flow always yields a new tag and the runner
  pulls it.
- Forcing a pull would re-pull the image on every job for no benefit.

#### Rejected

- Enabling `force_pull`: it is acceptable to miss a runner-side image change,
  and a `Dockerfile`-only change is not worth a per-job pull.

#### Known issue

- A `Dockerfile`-only change (like the marker above) re-pushed under an
  unchanged tag is invisible to the runner — it keeps the old image while the
  registry shows the new digest. If that ever matters, remove the stale tag on
  the runner host (`docker rmi gitea.e1nsnull.de/tmu/act-ci:<version>`); do not
  reach for force-pull.

## Coverage serving

#### Decision (2026-09)

Serve CI coverage from a shared directory on the runner, with no deploy step in
CI.

#### Why

- The webserver just exposes the shared directory; the Gitea docker setup reuses
  the existing reverse proxy. There is no upload artifact and no external
  service.
- Coverage is written to a shared volume keyed by project and tag (for example
  `/docs/tiny-pattern-ts/<tag>/`).

#### Rejected

- Gitea Pages and Codecov: neither was confirmed available or wanted.

#### Known issue

- Coverage is currently served for tag pushes only. Serving it for non-tag
  pushes (for example `main/coverage`) is tracked separately.

[scripts/precompress.ts](../scripts/precompress.ts) emits `.br` / `.gz` / `.zst`
sidecars next to every text asset under the served directories. The Gitea pages
service (`static-web-server` with `SERVER_COMPRESSION_STATIC=true`) serves the
sidecar matching `Accept-Encoding` and falls back to the original for the rest.

#### Decision (2026-09)

Precompress text assets into sidecars rather than compressing on each request.

#### Why

- The files are static and change only on deploy, so the work is paid once.
- Images, fonts and archives are already compressed; a sidecar would only make
  them bigger, which is why only text extensions are emitted.