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.
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. |
|
draft |
|
|
|
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
- Repo secrets
REGISTRY_USERNAMEandREGISTRY_PASSWORDexist. - A runner with the
publishlabel exists and its config hascontainer.docker_host: automount. Without the label the job queues forever; without the socket it fails atCheck daemon access. pr-checker.ymlstill runs on a label whose runner has no socket.- Namespace
cvhas animagePullSecretfor the same credentials. git.noelsabia.devanswers 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 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
git.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).