PR Check / Security scan (Snyk) (pull_request) Skipped
PR Check / Lint + typecheck (pull_request) Successful in 1m10s
PR Check / Secret scan (gitleaks) (pull_request) Successful in 6s
PR Check / Dependency audit (pull_request) Successful in 9s
PR Check / Dockerfile lint (droast) (pull_request) Successful in 5s
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.
214 lines
10 KiB
Markdown
214 lines
10 KiB
Markdown
---
|
|
type: Decision
|
|
title: Publishing images to the own registry
|
|
description: A release tag builds the production image and pushes it to git.noelsabia.dev, because that is the only way Kubernetes can pull it.
|
|
tags: [decision, ci, docker, registry, gitea-actions]
|
|
status: draft
|
|
generated: { by: opencode-go/deepseek-v4.1-flash, at: 2026-10-24T00:00:00Z }
|
|
verified: { by: human:noel, at: not yet }
|
|
sources:
|
|
- id: workflow
|
|
resource: .gitea/workflows/publish-image.yml
|
|
title: Publish image workflow
|
|
- id: dockerfile
|
|
resource: Dockerfile
|
|
title: Production Dockerfile
|
|
- id: k8s
|
|
resource: ../OKF_CV_Website/architecture/delivery.md
|
|
title: 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](https://docs.gitea.com/usage/packages/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](release-engineering.md)); 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:
|
|
|
|
```yaml
|
|
# 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:
|
|
|
|
```yaml
|
|
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](production-image.md)).
|
|
* 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).
|