diff --git a/.gitea/workflows/ci.yml b/.gitea/workflows/ci.yml index afd8905..f5bf33f 100644 --- a/.gitea/workflows/ci.yml +++ b/.gitea/workflows/ci.yml @@ -49,11 +49,16 @@ jobs: needs: release-gate if: needs.release-gate.outputs.skip != 'true' runs-on: ubuntu-latest - # Bind-mount the shared pages tree so the coverage step below can write - # into it. The runner whitelists this path via `container.valid_volumes` - # (docker-space `setup/gitea.sh`); `image` is omitted on purpose so the - # runner keeps using its default job image. + # `image` extends the runner's default job image (catthehacker/act) + # with Node 26 pre-planted in the tool cache layout, so setup-node's + # version probe hits and never downloads (see docker/Dockerfile). The + # tag MUST equal the exact version pinned in `.node-version`; the bump + # ritual is documented in CONTRIBUTING.md § CI runner image. The volume + # bind-mounts the shared pages tree so the + # coverage step below can write into it; the runner whitelists this + # path via `container.valid_volumes` (docker-space `setup/gitea.sh`). container: + image: gitea.e1nsnull.de/tmu/act-ci:26.8.2 volumes: - /data/gitea-pages:/data/gitea-pages steps: @@ -108,6 +113,10 @@ jobs: if: needs.release-gate.outputs.skip != 'true' runs-on: ubuntu-latest continue-on-error: true + # Same baked image as `build` — without it this job re-downloads Node + # per run (see docker/Dockerfile). + container: + image: gitea.e1nsnull.de/tmu/act-ci:26.8.2 steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 @@ -121,6 +130,10 @@ jobs: if: startsWith(gitea.ref, 'refs/tags/') needs: build runs-on: ubuntu-latest + # Same baked image as `build` — setup-node still owns the registry-url + # `.npmrc` rewrite here; only the Node download is skipped. + container: + image: gitea.e1nsnull.de/tmu/act-ci:26.8.2 # The release page is created with the run's automatic Gitea token # (`github.token`), not `NPM_TOKEN`, so it needs `contents: write`. permissions: @@ -139,6 +152,10 @@ jobs: - uses: actions/setup-node@v4 with: node-version-file: .node-version + # Same lockfile/key as `build`, and tag runs can read caches + # saved on `main` — without this, every release pays a cold + # `npm ci` despite the warm shared npm cache. + cache: "npm" registry-url: "https://registry.npmjs.org/" - run: npm ci # Consume the dist/ that `build` produced and gated, instead of diff --git a/.node-version b/.node-version index 978b4e8..707210d 100644 --- a/.node-version +++ b/.node-version @@ -1 +1 @@ -26 \ No newline at end of file +26.8.2 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3fa590d..ee23cfd 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -90,6 +90,18 @@ This is why every test in the suite pairs an `expectTypeOf(...)` with an `assert - CI runs `npm run check` + `npm run test:ci` on every push to `main` — this is the authoritative gate. The one exception: a push headed by a release commit (`:rocket: Release x.y.z`) skips the full `build`/`maintain` jobs, because `create:release` pushes the tag for that exact commit right after and the tag run is the authoritative one (see `release-gate` in [.gitea/workflows/ci.yml](./.gitea/workflows/ci.yml)). - **Releases are NOT triggered by pushes.** Only the maintainer triggers a release (see [Publishing workflow](#publishing-workflow)). +## CI runner image + +The `build` / `maintain` / `publish` jobs run in `gitea.e1nsnull.de/tmu/act-ci:` ([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, so no job pays the ~50 MB fetch. The image tag MUST equal the exact version pinned in `.node-version`; `release-gate` uses no Node and stays on the default image. The script is deliberately NOT an `npm run` script: building requires a docker daemon and registry credentials, so it belongs to no feedback tier — per [Script prefix convention](#script-prefix-convention), no existing prefix fits and that is the signal. + +Bumping Node is one coordinated change, committed as a unit: + +1. Edit `.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` 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 `:`. +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. + ## Publishing workflow Publishing is CI-only by policy. Local `npm publish` is not supported. The maintainer triggers releases from `main`: diff --git a/backlog.tasks b/backlog.tasks index 0a55d8b..920006d 100644 --- a/backlog.tasks +++ b/backlog.tasks @@ -45,3 +45,7 @@ Maintenance: ☐ Add a minimal dir-listing webserver to the gitea docker setup for serving landing page (reuse existing reverse proxy) ☐ CI writes landing page to a shared volume keyed by project + tag (e.g. `/landing/tiny-pattern-ts//`) ☐ Browse to `…/tiny-pattern-ts/index.html` in the browser +☐ Stop Gitea CI re-downloading Node on every job (branch chore/fix-ci) + ✔ Share the warm npm cache with the publish job @done + ✔ Bake Node into the CI job image (docker/Dockerfile, container.image in ci.yml) @done + ☐ Build/push gitea.e1nsnull.de/tmu/act-ci:26.8.2 and confirm setup-node skips the download (first run on the branch = acceptance test) @high diff --git a/cspell.json b/cspell.json index 58d50e3..bebc052 100644 --- a/cspell.json +++ b/cspell.json @@ -27,6 +27,14 @@ "knope", "runwisp", "glab", + "hostedtoolcache", + "nodebase", + "frontends", + "catthehacker", + "nsnull", + "dedup", + "dedupe", + "repoint", "postversion", "prebuild", "Zilla", diff --git a/docker/Dockerfile b/docker/Dockerfile new file mode 100644 index 0000000..babcb5a --- /dev/null +++ b/docker/Dockerfile @@ -0,0 +1,44 @@ +# CI job image for the Gitea act_runner: the runner's default job image with +# Node pre-planted where actions/setup-node looks first. +# +# Why this layout: setup-node ignores `node` on PATH; its only fast path is a +# probe of /opt/hostedtoolcache/node//. Without an entry there +# it downloads the ~50 MB distribution on EVERY job (the runner's job +# containers are ephemeral, so its tool cache never survives a job). The +# official node images keep exactly the layout setup-node expects under +# /usr/local, so this layer is a pure file overlay — no scripts, no env. +# +# Why not a host bind of /opt/hostedtoolcache: binds never self-prune. Docker +# images are content-addressed: the base layers dedupe against the act image +# the host already has, and `docker image prune` / re-pulls are the cleanup +# story. +# +# NODE_VERSION must match `.node-version` exactly. setup-node resolves a float +# like `26` to the latest known patch at runtime, so a bump silently busts the +# baked entry; `.node-version` is pinned to x.y.z and scripts/runner-image.sh +# guards the coupling. Rebuild + repoint `container.image` in +# .gitea/workflows/ci.yml on every bump. +# +# The extra `nodebase` stage is load-bearing: `COPY --from=` resolves its value +# as a *stage name* at parse time, before build args exist, so +# `COPY --from=node:${NODE_VERSION}` collapses to the invalid `node:` on +# frontends that do not expand args there. ARGs declared before the first FROM +# *are* expanded in FROM, so routing through a named stage works everywhere. + +# Global scope: only visible to FROM lines, but that is exactly where we need it. +ARG NODE_VERSION=26.8.2 +FROM node:${NODE_VERSION} AS nodebase + +FROM catthehacker/ubuntu:act-latest + +# ARGs do not cross stage boundaries; redeclare (with the same default, so a +# bare `docker build -f docker/Dockerfile .` still works) for the paths below. +# Keep this default in sync with the global one above. +ARG NODE_VERSION=26.8.2 + +# node image: bin/ + lib/ under /usr/local → tool cache: bin/ + lib/ under /x64. +COPY --from=nodebase /usr/local /opt/hostedtoolcache/node/${NODE_VERSION}/x64 + +# Fail the build (not CI) if the overlay or the version arg were wrong. +# Shell form on purpose: exec form (`RUN [...]`) does not expand ARG values. +RUN "/opt/hostedtoolcache/node/${NODE_VERSION}/x64/bin/node" --version diff --git a/scripts/runner-image.sh b/scripts/runner-image.sh new file mode 100755 index 0000000..6205cbd --- /dev/null +++ b/scripts/runner-image.sh @@ -0,0 +1,33 @@ +#!/usr/bin/env bash +set -euo pipefail + +# Build (and optionally push) the CI job image from docker/Dockerfile. +# Run wherever docker + registry credentials live (the runner host, or any +# machine that can reach the registry). The registry/repo below MUST match +# the `container.image` references in .gitea/workflows/ci.yml — the runner +# pulls the image by name. +# +# Usage: scripts/runner-image.sh [--push] + +IMAGE_REPO="gitea.e1nsnull.de/tmu/act-ci" + +NODE_VERSION="$(tr -d '[:space:]' < .node-version)" +if [[ ! "${NODE_VERSION}" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then + echo "error: .node-version must be pinned to an exact x.y.z, got '${NODE_VERSION}'." >&2 + echo " setup-node resolves floats like '26' to the latest patch at runtime," >&2 + echo " which silently busts the tool-cache entry baked into the image." >&2 + exit 1 +fi + +IMAGE="${IMAGE_REPO}:${NODE_VERSION}" + +# --pull: refresh the act base layer so the derivative does not float on an +# aging default image forever (layer dedup keeps this cheap). +docker build --pull --build-arg "NODE_VERSION=${NODE_VERSION}" -t "${IMAGE}" -f docker/Dockerfile . + +if [[ "${1:-}" == "--push" ]]; then + docker push "${IMAGE}" +fi + +echo "built ${IMAGE}" +echo "reminder: bump container.image in .gitea/workflows/ci.yml to this tag"