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).
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. |
|
draft |
|
|
|
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: automountand 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.ymlleft 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 andlatesttags). Pruning is not part of this change; add adocker image prunepolicy when the disk usage actually matters. latestis 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
imagePullSecretin the namespace for the same basic-auth pair, or/etc/rancher/k3s/registries.yamlif 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:
Dockerfilehas 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.devis reachable over HTTPS from the runner. A plain-HTTP endpoint failsdocker loginwithserver gave HTTP response to HTTPS clientand needsinsecure-registrieson the daemon plusregistries.yamlon k3s. - Whether Gitea runs a
pull_requestworkflow 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 imagestep, or manifests start referencing the SHA tag. - Multi-arch becomes necessary (a laptop or a CI host of the other architecture pulls the image).