Files
CV_Site_Nuxt/OKF_Nuxt/decisions/registry-publishing.md
Noel Sabia 81bfae7489 ci(publish): add a manual build-only rehearsal trigger
workflow_dispatch with version/push/latest inputs: push defaults to
false, so the runner, socket and registry login can be verified without
creating a tag or a package version. latest is never moved unless asked.
2026-10-31 20:40:10 +01:00

10 KiB

type, title, description, tags, status, generated, verified, sources
type title description tags status generated verified sources
Decision Publishing images to the own registry A release tag builds the production image and pushes it to git.noelsabia.dev, because that is the only way Kubernetes can pull it.
decision
ci
docker
registry
gitea-actions
draft
by at
opencode-go/deepseek-v4.1-flash 2026-10-24T00:00:00Z
by at
human:noel not yet
id resource title
workflow .gitea/workflows/publish-image.yml Publish image workflow
id resource title
dockerfile Dockerfile Production Dockerfile
id resource title
k8s ../OKF_CV_Website/architecture/delivery.md Sibling bundle - image tags and registry pull

Decision

The registry is Gitea's own, served on the Gitea host. Gitea ships a built-in container registry per owner/organisation (docs.gitea.com - container). The endpoint is the Gitea hostname itself - git.noelsabia.dev - and the /cv_website/ path segment is the Gitea organisation; images live under the package of the repository that pushed them:

docker login git.noelsabia.dev
git.noelsabia.dev/cv_website/nuxt:<tag>

There is nothing to stand up and nothing to reinvent: no separate Registry/Harbor deployment, no extra hostname, no extra certificate. TLS and auth are the ones Gitea already serves. The publishing workflow exists only to automate pushes to this built-in registry.

Corrected 2026-10-31: registry.noelsabia.dev was a separate hostname set up before this was known. It is not needed and is being removed on the server side; this repository now uses git.noelsabia.dev everywhere. Any leftover registry.noelsabia.dev reference is a bug.

.gitea/workflows/publish-image.yml builds Dockerfile and pushes the result to the own registry:

git.noelsabia.dev/cv_website/nuxt:v1.2.3
git.noelsabia.dev/cv_website/nuxt:sha-<12-char-sha>
git.noelsabia.dev/cv_website/nuxt:latest   # newest release only

Trigger is the release tag, not the main push. release-please creates vX.Y.Z when the release PR is merged (release engineering); that tag push is the build. A main push would otherwise publish commits that no release describes, and latest would move on work in progress.

Why not build on every main push

  • The registry is the deployment channel. Every image in it should answer "which release is this", and a tagged commit does.
  • The runner has capacity 1 and shares 2 vCPU / 4 GB with Gitea and k3s (OKF_CV_Website/architecture/server-budget.md). A Nuxt image build can take over 1 GB; running it more often than a release buys nothing.
  • The PR checks already gate the code that becomes a release. A tag build is not the first time the tree is built - a failing build here is a packaging failure, not a surprise.

Why docker-outside-of-docker

The job runs in node:22-bookworm, like every other job in this repository, and only needs the Docker client: docker build sends the build context over the socket, so the daemon never reads the container's filesystem. That requires the act_runner to mount its host socket:

# act_runner config.yaml
container:
  docker_host: automount

Without it the Check daemon access step fails first with a named cause instead of a mid-build error. The alternative - a privileged docker:dind sidecar - needs privileged mode and a second daemon per release; not worth it on this server.

Trust boundary (the cost of the socket)

A mounted Docker socket is root-equivalent on the host: any job that has it can run docker run -v /:/host and read or write anything, which on this machine means Gitea's data, k3s, and the CV itself. docker_host is a runner-wide setting, so enabling it gives the socket to every job on that runner, including PR jobs whose code comes from a branch.

Therefore the rule: the socket only ever goes on a runner label that PR-triggered jobs do not use.

The workflow follows it by scheduling onto a dedicated label:

runs-on: publish   # NOT ubuntu-latest, which pr-checker.yml uses

That label only exists once a second act_runner registration is configured with container.docker_host: automount and, for example, --labels publish:docker://node:22-bookworm. Until then the job queues without starting, and timeout-minutes does not apply to a job that never starts - register the runner before the first release tag.

Not acceptable: adding automount to the shared ubuntu-latest runner. That hands PR code a root-equivalent socket on the host that also runs Gitea and k3s. If it is ever the only option, treat it as an accepted risk and record it here rather than letting the workflow imply it.

Why --platform linux/arm64

The runner and the node are the same arm64 machine, so the build is native (no QEMU, no crossed dependencies). Stating the platform makes a build on another architecture fail instead of publishing an image the node cannot run.

Secrets

Gitea secret Use
REGISTRY_USERNAME basic-auth user for docker login git.noelsabia.dev
REGISTRY_PASSWORD basic-auth password (or token) for the same login

Both are repo secrets. The login uses --password-stdin so the value never appears in the process list or the log.

Before the first release tag

  1. Repo secrets REGISTRY_USERNAME and REGISTRY_PASSWORD exist.
  2. A runner with the publish label exists and its config has container.docker_host: automount. Without the label the job queues forever; without the socket it fails at Check daemon access.
  3. pr-checker.yml still runs on a label whose runner has no socket.
  4. Namespace cv has an imagePullSecret for the same credentials.
  5. git.noelsabia.dev answers over HTTPS.

Manual rehearsal (workflow_dispatch)

The workflow can be started from the Gitea UI (Actions → Publish image → Run workflow) without creating a tag:

Input Use
version required, vMAJOR.MINOR.PATCH
push false (default) builds and smoke-tests only; true publishes
latest false unless this is a real release

A build-only run publishes nothing, so it creates no package version and the immutability guard is skipped. This is the way to prove the runner, socket and registry login before the first release - a rehearsal must never move latest, which is why that input is explicit.

Gitea only offers the Run-workflow button for workflows present on the default branch, so this trigger is available once the change is on main.

Guards in the workflow

Guard Why
Strict ^vMAJOR.MINOR.PATCH$ check A v[0-9]* prefix match accepts v1, v1-anything and v1.2.3-rc1, all of which are valid registry tags and would publish silently
latest only when the built tag is the highest vX.Y.Z in the repository Gitea can replay any run. Without the comparison, re-running v1.2.0 after v1.3.0 drags latest backwards. A re-run of the newest tag still moves it - that release had not produced an image yet. If the tag list cannot be fetched, latest is skipped with a warning rather than guessed
A published version tag is never overwritten Before building, the registry's v2 API is asked for manifests/<version>: 200 aborts the run, 404 continues. A replay of a released tag fails instead of silently replacing published content. docker manifest inspect is deliberately not used - the Debian 20.10 client fails it on OCI indexes with unsupported manifest media type and no default available, for existing and missing tags alike
Smoke test before any push The image is started and must answer 2xx with at least 10 kB of rendered HTML on / (the real page is ~97 kB), so "200 but nothing rendered" fails too. Port publishing is not usable here: the daemon binds on the host, not in the job container
timeout-minutes: 20 A hung build would hold the capacity-1 runner and every job queued behind it
.github/actionlint.yaml Declares the custom publish label, otherwise the lint hook reports it as unknown. The hook passes the file with -config-file, because actionlint only auto-loads it when it recognises a .github/workflows project

Costs and consequences

  • Registry storage grows by one image per release in three tags. The three tags share layers, so the extra cost is mostly the tag, not the bytes.
  • Images accumulate on the runner's daemon (sha-, version and latest tags). Pruning is not part of this change; add a docker image prune policy when the disk usage actually matters.
  • latest is a convenience, not a pin. Manifests should reference the version or SHA tag so a release rollback is a manifest edit.
  • k3s needs pull credentials: an imagePullSecret in the namespace for the same basic-auth pair, or /etc/rancher/k3s/registries.yaml if the registry is ever plain HTTP. Not part of this workflow.

Not verified

  • That the runner has the host socket mounted (docker_host: automount) - the workflow's first step answers this on the first release.
  • That the arm64 build succeeds: Dockerfile has been built on x86_64 only (production image).
  • That the smoke test passes on arm64. The same script was run against an x86_64 build of the merged tree and answered 2xx; the arm64 run is the first release.
  • That git.noelsabia.dev is reachable over HTTPS from the runner. A plain-HTTP endpoint fails docker login with server gave HTTP response to HTTPS client and needs insecure-registries on the daemon plus registries.yaml on k3s.
  • Whether Gitea runs a pull_request workflow from a fork without maintainer approval on this instance. That answer decides how severe the socket risk above really is.

Revisit when

  • A second image (the Go gateway or chapter service) needs publishing - then the workflow grows a matrix instead of being copied.
  • Deploys should follow automatically: the release workflow gains a kubectl set image step, or manifests start referencing the SHA tag.
  • Multi-arch becomes necessary (a laptop or a CI host of the other architecture pulls the image).