- JavaScript 100%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
| .forgejo/workflows | ||
| dist | ||
| src | ||
| test | ||
| .gitignore | ||
| action.yml | ||
| CHANGELOG.md | ||
| package-lock.json | ||
| package.json | ||
| README.md | ||
docker-buildx
Action that builds and pushes a multi-arch manifest list.
Every in-house image that runs on the cluster must be linux/amd64,linux/arm64.
ARM64 is the untainted default worker pool and amd64 is two tainted nodes
(gitops ADR 0026), so a single-arch image forces an arch: amd64 nodeSelector
plus a toleration onto that small pool. Enough of those and it fills up — which
is how a vexa meeting bot ended up unschedulable with 1000m requested against
~300m free.
actions/node-docker:24 already supplies the Docker CLI and the buildx plugin.
What it cannot supply is the per-job runtime setup: QEMU binfmt registers in the
host kernel through a privileged container, and the docker-container builder is
per-job state. That is the preamble this action removes.
jobs:
build:
runs-on: self-hosted
container:
image: git.bun.cafe/actions/node-docker:24
credentials:
username: ${{ github.actor }}
password: ${{ secrets.NPM_TOKEN }}
env:
DOCKER_HOST: tcp://172.17.0.1:2375
steps:
- uses: actions/checkout@v4
- uses: actions/docker-buildx@v1
with:
image: git.bun.cafe/cinnabrad/my-app
registry-username: ${{ github.actor }}
registry-password: ${{ secrets.NPM_TOKEN }}
Tags
Omit tags and push and the action derives them from the ref, so the case
statement lives here instead of in every repo:
| ref | tags | publishes |
|---|---|---|
refs/tags/v1.2.3 |
v1.2.3 v1.2 v1 latest |
yes |
| default branch | main-<sha> main |
yes |
| other branches | <branch>-<sha> |
no |
| pull request | pr-<n>-<sha> |
no |
Set default-branch: staging (or master) where that applies. Passing tags
explicitly still works and skips derivation; passing push always wins, so a repo
can publish from a branch if it needs to. version-tags chooses how much of a v*
release becomes a moving tag — exact for application images gitops pins
precisely, major (the default) for base images nothing pins by digest — and
extra-tags appends moving names that differ from the branch, like portal's
prod/staging.
With reuse-from-branch: staging, a pushed v* tag does not build at all: the
action retags <image>:staging-<shortsha> for the tagged commit with the release
tags via imagetools create. Releases are cut from commits the branch already
built, so this removes the double build — and the release ships the exact image
the branch validated rather than a rebuild expected to be identical.
forbid-files names globs that must not exist in the built image (checked on a
native-arch probe before anything is pushed). It is how "sourcemaps never ship"
is an enforced property of the build: app/dist/**.map — scoped, because
packages under node_modules ship maps of their own.
Release tags are what gitops should pin. They are sparse, so retention can keep
them indefinitely (Keep versions matching: ^v), whereas <branch>-<sha> builds
are disposable and the 14-day cleanup rule is free to remove them. Tagging
latest on releases helps twice over: Forgejo always keeps the latest container
version. Pinning a <branch>-<sha> that later ages out is how a deployed image
became unpullable once already.
The version output is the immutable identifier for the build — never a moving
tag — and digest is the manifest-list digest. Pin one of those, not a per-arch
sub-manifest.
push: false still builds both architectures and discards them, which is what a
PR wants — a manifest list cannot be held in the local image store, so verifying
and publishing are the same operation. Let PRs build and only publish from the
default branch.
Inputs
| input | default | notes |
|---|---|---|
image |
— | full reference without a tag |
tags |
— | space-separated |
push |
false |
requires the two registry inputs |
dockerfile |
Dockerfile |
|
context |
. |
often the repo root even when the Dockerfile is nested |
target |
— | multi-stage build target, e.g. production |
platforms |
linux/amd64,linux/arm64 |
binfmt is skipped for a single native platform |
build-args |
— | newline-separated KEY=VALUE |
build-secrets |
— | newline-separated ID=VALUE; each becomes --secret id=ID,env=ID for RUN --mount=type=secret,id=ID — use for tokens, never build-args |
labels |
— | newline-separated |
registry |
git.bun.cafe |
|
registry-username / registry-password |
— | required when pushing |
binfmt-image |
pinned tonistiigi/binfmt |
mutates the shared runner kernel, so pinned |
cache-from / cache-to |
— | newline-separated buildx cache specs |
Output digest is the manifest-list digest. Pin that in gitops, or an
immutable tag — never a per-arch sub-manifest, which would need the very
nodeSelector this exists to remove. A pod's .status.containerStatuses[].imageID
is a sub-manifest digest, so it is the wrong value to copy.
Why not compose the upstream actions
actions/docker-build-push is a mirror of docker/build-push-action, and its
README lists what it expects alongside it: setup-buildx to create a builder on
the docker-container driver, and setup-qemu for emulation. Neither is mirrored
here, so composing the upstream set would mean two more mirrors and a four-step
preamble in every repo.
Note that neither can be replaced by a prebaked image, which is the tempting
shortcut. node-docker does supply the buildx plugin — but a builder instance
is per-job state, and the default docker driver cannot build a manifest list at
all. binfmt handlers register in the host kernel, so an image cannot carry them
either; they persist until reboot, which makes the registration step usually a
no-op but never safe to drop.
This action also handles one thing setup-buildx-action does not: a persistent
self-hosted runner leaves buildx_buildkit_multiarch0 behind, so the builder can
exist on the host while this job container has no record of it. create writes
local state without touching the host, and if inspect --bootstrap then fails the
host container is stale and gets replaced.
The trade is that the build step here is a narrow slice of build-push-action's 33
inputs. cache-from/cache-to are wired because the emulated arm64 leg is the
expensive half of a multi-arch build; secrets, SBOM and attestations are not. If
one is needed, add the input rather than reaching around the action.
Requirements
Job container with the buildx plugin (actions/node-docker), DOCKER_HOST
pointing at the host's real dockerd, and a dockerd that permits privileged
containers — binfmt registration and the buildkitd container both need it. The
restricted socket proxy on the deploy hosts does not qualify; the shared
self-hosted runners do.
Put smoke tests inside the Dockerfile rather than running the built image in CI.
A multi-platform build is pushed straight to the registry with no local image,
and a docker run check would only ever exercise the runner's own architecture.
Development
Standard node24 action layout (see actions/reconcile): logic in src/, bundled
to dist/ with @vercel/ncc and committed.
npm install
npm test # node --test test/*.test.js
npm run build # ncc build src/index.js -o dist → commit dist/
CI runs both and fails if dist/ does not match a fresh build. dist/ is
committed while node_modules/ is not, so an edit to src/ without a rebuild
ships a bundle that silently lacks the change.
computeTags is exported so the tag scheme can be exercised without a runner:
node -e "console.log(require('./src/index.js').computeTags({
ref: 'refs/tags/v1.2.3', refName: 'v1.2.3', event: 'push',
sha: 'abcdef1234567890', defaultBranch: 'main' }))"