Files
CV_Site_Nuxt/OKF_Nuxt/decisions/registry-publishing.md
T
Noel Sabia 435be63ae0
PR Check / Security scan (Snyk) (pull_request) Skipped
PR Check / Lint + typecheck (pull_request) Successful in 1m5s
PR Check / Secret scan (gitleaks) (pull_request) Successful in 6s
PR Check / Dependency audit (pull_request) Successful in 8s
PR Check / Dockerfile lint (droast) (pull_request) Successful in 5s
PR Check / AI code review (opencode) (pull_request) Successful in 48s
fix(ci): harden the release publish workflow after the PR review
Applied the findings that held up against the code:
- strict vMAJOR.MINOR.PATCH guard; v[0-9]* accepted v1, v1-foo and
  prereleases, all valid registry tags
- latest now follows the newest release, so replaying an older tag cannot
  drag it backwards; skipped with a warning if the tag list is unavailable
- smoke test starts the built image and requires 2xx on / before pushing
- timeout-minutes: 20 on the job, so a hung build cannot hold the
  capacity-1 runner indefinitely
- the decision doc records the socket's blast radius: root-equivalent,
  runner-wide, only on a label PR jobs cannot use

Rejected with evidence: the .dockerignore leak (.env*, *.pem, .git are
excluded) and the Docker client/daemon API mismatch (20.10.24 client
against a 29.9.2 daemon builds over the socket).
2026-10-24 19:15:55 +02:00

6.9 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 registry.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

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

registry.noelsabia.dev/cv_website/nuxt:v1.2.3
registry.noelsabia.dev/cv_website/nuxt:sha-<12-char-sha>
registry.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. Two acceptable layouts:

  • a second act_runner registration with docker_host: automount and a distinct label (e.g. publish), used only by this workflow; or
  • one runner, but this workflow moved to the dedicated label and pr-checker.yml left on a label without the socket.

Not acceptable: adding automount to the single shared runner while pr-checker.yml runs on it. If that is the only option, treat it as an accepted risk and record it here - the trade is "PR code can become root on the host" against "images can be built at all".

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 registry.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.

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
Smoke test before any push The image is started and must answer 2xx on / from inside the container. Build success only proves the bundle compiled. 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

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 registry.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).