Container releases¶
The shared GitHub Actions workflows for Tuxcrate container images live in tuxcrate/github-actions.
Commands and paths on this page are relative to that repository unless noted.
Calling the workflow¶
Call .github/workflows/container.yml from an image repository:
name: Container
on:
pull_request:
push:
branches: [main]
schedule:
- cron: '23 4 * * 1'
workflow_dispatch:
permissions:
contents: read
jobs:
container:
permissions:
contents: write
packages: write
pull-requests: write
uses: tuxcrate/github-actions/.github/workflows/container.yml@main
secrets: inherit
Every caller repository must contain meta.yaml in its root, including single-track images.
The workflow checks for this file before building the release tooling, then validates the tracks and aliases before building or publishing any images.
There is no configurable metadata path or workflow-version fallback.
The Containerfile receives each track's exact version pin as APP_VERSION.
It must install that exact version. Keep useful installation assertions in the
Containerfile and put startup and shutdown tests in a host-side
tests/smoke.sh hook, without copying it into the image.
Keep the version or full APT package pin in meta.yaml and update it through a reviewed PR.
The workflow also supplies PACKAGE_VERSION for packaging identity, independently
of the upstream installation pin. Production builds receive the immutable image
tag, such as 4.0.20.3014-r1 or 5.0.0.2870-prerelease-r1. PR builds receive
<imageVersion>-pr-<number>-<track>-<short-merge-commit-sha> and never reserve a
production revision. Containerfiles can use ARG PACKAGE_VERSION to embed this
identity; Sonarr, Radarr, and Prowlarr expose it in System → Status alongside a
Tuxcrate link. Their local builds fall back to <APP_VERSION>-local when the
argument is omitted. Never use PACKAGE_VERSION to select upstream downloads.
Image labels and annotations¶
The shared workflow explicitly sets these three labels on every platform image, for both production and PR builds:
| Label | Production value | PR value |
|---|---|---|
org.opencontainers.image.source |
Caller repository URL, such as https://github.com/tuxcrate/sonarr |
Same caller repository URL |
org.opencontainers.image.version |
Full immutable image tag, including -rN |
Full preview package version |
org.opencontainers.image.revision |
Source Git commit SHA | Tested merge commit SHA |
The OCI revision label remains the source-control revision; the version label
includes the image rebuild counter. Labels are set for every track, even when
the Containerfile does not consume PACKAGE_VERSION.
For example, a production Sonarr image might have version 4.0.20.3014-r1,
while PR 12's stable track might have version
4.0.20.3014-pr-12-stable-abcdef0. The revision label contains the full Git SHA
in either case, never r1. The source label points to the packaging repository,
not the upstream Sonarr repository or tuxcrate.com.
These are image-configuration labels, available under Config.Labels in
docker image inspect. They are not automatically annotations on the
multiarchitecture OCI index. After pulling an image, inspect its labels with:
docker pull ghcr.io/tuxcrate/sonarr:latest
docker image inspect --format '{{json .Config.Labels}}' ghcr.io/tuxcrate/sonarr:latest
PR builds additionally set these OCI index annotations, including for fork PRs whose images remain local:
| Annotation | Value | Purpose |
|---|---|---|
io.tuxcrate.repository |
Caller repository, such as tuxcrate/sonarr |
Identifies the repository that owns the preview |
io.tuxcrate.pull-request |
PR number as a string, such as 12 |
Identifies the PR that owns the preview |
These annotations identify preview artifacts independently of their mutable
tags. They are not container labels and do not appear in Config.Labels.
Production indexes do not receive these preview annotations. For a published
preview, inspect the raw index with:
The keys appear in the index's annotations mapping. The index: prefix in
the workflow selects where Buildx writes them; it is not part of either key.
Other labels may be inherited from the base image or set by a repository's
Containerfile. The shared workflow does not explicitly set other predefined
OCI keys such as created, authors, url, documentation, vendor, or
licenses; do not assume those values are present. Provenance and SBOMs are
separate attestations, not additional image labels. The predefined label meanings
are described in the OCI annotations specification.
Shared tooling and integration inputs¶
Set image build settings in meta.yaml; workflow inputs cannot set them.
All repositories use the same defaults: ghcr.io/<caller repository>, context ., root Containerfile, and linux/amd64,linux/arm64.
Metadata can override these for individual tracks; the caller workflow stays the same.
| Input | Default | Purpose |
|---|---|---|
shared-ref |
main |
Shared tooling ref; must match the workflow's uses ref |
docs-repository |
tuxcrate/docs |
owner/repo to notify with an image-published repository dispatch; set to '' to disable |
For a pinned integration, use the same commit SHA in the workflow's uses and shared-ref.
Both repositories must be accessible to the caller.
For private repositories, configure GitHub Actions access to the shared workflow and shared tooling checkout; the normal caller token cannot check out a different private repository.
The current setup assumes this shared repository is public.
GitHub API requests during builds¶
The shared workflow passes the job's GITHUB_TOKEN as an optional BuildKit
secret named github_token for production and same-repository PR builds.
Containerfiles can mount /run/secrets/github_token and use it to authenticate
GitHub API requests. Do not use shell tracing (set -x) when reading the secret
or sending the authorization header. Never pass the token as a build argument,
copy it into an image, or write it to a persistent file.
BuildKit does not persist the secret mount in image layers, but the Containerfile can read and transmit the token. Only trusted contributors should have access to same-repository branches. Fork PRs receive no token and use unauthenticated requests, as do local builds without a secret. PyPI/APT Containerfiles need no changes and do not mount the secret.
For local authenticated builds, add
--secret id=github_token,env=GH_TOKEN to the normal Buildx invocation, with
GH_TOKEN set in the Docker client's environment, for example using
GH_TOKEN="$(gh auth token)" docker buildx build ....
Behavior and tags¶
- PRs build both platforms using QEMU, export a local OCI archive, and test each platform before any registry upload.
Same-repository PRs then publish test images to the production package under
pr-tags; fork PRs build and test locally, with no registry login or upload. PRs never create GitHub releases or update production aliases. The Containerfile'sRUNassertions execute on both architectures; no host ZFS kernel module is needed for zrepl's smoke tests. - Default-branch pushes build and publish only tracks whose build or publication inputs differ from their last successfully published release.
Scheduled and manual runs always rebuild every active track, even when its source is unchanged.
Builds run without layer cache, pull the configured base image reference, and publish to GHCR using
GITHUB_TOKEN. A digest-pinned base stays fixed until a source update (such as a Renovate digest-update PR) is merged. - Outside PR previews, other branches and other event types cannot publish.
Do not add
pull_request_targetas a publishing trigger. - An upstream version starts at
0.7.0-r0; each rebuild increments the image revision.0.7.1starts again at0.7.1-r0. - The revision tag never moves.
The track's explicitly configured
tagsmove to its new image revision. For example, tags["${version}", "${major}.${minor}", latest]publish0.7.0,0.7, andlatestfor0.7.0. Prereleases may use named aliases such aspreview, never stable aliases. Multiple current releases can share the same default branch through tracks. - Each track is built and tested before publication. BuildKit exports an OCI archive,
including provenance and SBOMs, without pushing it. The shared runner loads each
platform from that archive and invokes the optional repository-root
tests/smoke.shhook, then validates final-image OS metadata locally. Only after those checks pass does the workflow log in and upload the unchanged archive by digest. Failed builds or tests upload no image manifests or layers to GHCR and do not move preview or production tags. The GitHub Actions build cache is separate from image publication. - A draft GitHub release reserves the next revision before building the image,
allowing the exact revision to be embedded during the build. Its initial body
identifies the source commit and track and states that publication is pending.
Reservation also returns the numeric GitHub release ID. Finalization retrieves
the draft by this ID, since GitHub's get-by-tag endpoint excludes draft releases.
After tests and upload,
container-release finalizeverifies the draft still belongs to this commit and track, rechecks revision-tag availability, and fills its notes with the tested digest and final-image OS metadata. It does not allocate another revision or publish the draft. On success, the workflow publishes the release and createsv0.7.0-rNat the exact source commit. GitHub release notes contain the digest, platforms, and linked packaging commits since the previous published image release. - The release CLI lists all new commit subjects with commit links, oldest first, using
git log. Conventional Commits are not required. The first release includes all history; release notes identify rebuilds that have no new commits. - All releases are serialized across trigger types. Revision selection includes both Git tags and all GitHub releases, including drafts and paginated history.
- Stale default-branch runs fail before reserving a revision and are checked again before finalizing the draft, preventing aliases from moving backwards. Start a fresh run on the current branch HEAD.
- Each release includes a versioned
release.jsonasset with the image, track, application version, revision, digest, source commit, platforms, and historical aliases. It also includesos_flavor(such asalpineordebian) andos_version, read from the final image by digest on the first declared platform, not inferred from the base image tag. These useIDandVERSION_IDfrom/etc/os-release(falling back to/usr/lib/os-release); Debian uses/etc/debian_versionwhen available to include the point release, such as13.7. Metadata generation does not run the image's entrypoint and fails if OS identifiers are missing or invalid. PR builds generate a temporary, syntheticrelease.jsonusing the same metadata generation and validation as real releases, including for fork PRs that cannot publish images. They also rehearse revision reservation and draft finalization against the tested local image. A fake GitHub API models draft lookup by release ID and rejects draft lookup by tag, so that failure is caught before merge. The rehearsal never creates or edits real releases or contacts the registry. Validation checks all required fields, including OS metadata from a locally loaded image of the first declared platform. Empty or invalid required values fail the job. This fixture uses placeholder revisionr0and the real tested OCI archive digest. It stays in the runner's temporary directory and does not reserve a revision, create a GitHub release, or publish release tags. The GitHub release'spublished_atis the authoritative publication timestamp. Draft assets are not published versions. - Prerelease versions create GitHub prereleases and never become GitHub's latest release.
Tracks may also set
prerelease: truewhen upstream uses numeric versions without a prerelease suffix, as Sonarr does. Such tracks must suffix their image version, for example with"${version}-prerelease"; neither the bare numeric version nor its unsuffixed revision is published automatically. In track mode only the owner oflatestcan become the latest release.
If a production build or test fails after reservation, its draft remains and the revision is consumed. Published revision numbers can therefore have gaps. If publication fails, it may also leave an untagged image and a draft release. Keep the draft as a revision reservation and rerun the workflow, which allocates a new revision. Do not delete release history or repurpose revision tags. The workflow checks the registry before tagging. If the revision already exists or the registry response cannot be verified, the run fails to prevent an overwrite. GitHub releases and registry updates are not an atomic transaction: if an alias update fails, some aliases may already have moved. A successful rerun repairs them. Restrict other workflows and users from modifying these image tags.
PR preview images¶
Every eligible same-repository PR publishes two tags per track.
For PR 12's stable track in tuxcrate/zrepl:
The first tag follows the PR.
The second identifies the exact merge commit tested by pull_request, not just the PR branch's head commit.
Rerunning the same commit may refresh OS packages and replace either tag; pin the image digest when an exact artifact is required.
Tracks have separate tags to avoid collisions.
Previews use the same package as production, including any image override in
meta.yaml. The pr- prefix is reserved for PR previews and cannot be declared
as a production moving tag.
Preview builds include uncached multiarch smoke tests, provenance, and SBOMs. They do not allocate release revisions, publish GitHub releases, move production aliases, or notify the website.
Preview tags and artifacts are retained after PRs close; there is no automatic
cleanup. Reruns can also leave untagged artifacts. Actual preview pulls contribute
to the same package-wide download total as production pulls; retaining an image
does not itself increase that total. The website excludes pr- tags from its
release tables and tag selectors, even if they point to a production digest.
After a successful push, the workflow posts pull commands, the tested merge commit, platforms, image digest, and a build link in the PR.
The same comment includes the generated release.json in a collapsed section labeled as synthetic validation metadata. Its revision is a placeholder; its digest identifies the tested multiarchitecture artifact.
Subsequent builds update the same bot-authored comment for each track.
Fork PRs do not receive image comments because they do not publish images.
The caller must allow packages: write and pull-requests: write, as in the workflow example above.
Fork PRs do not log in or push.
Keep GitHub's default read-only token policy for fork PRs.
Never switch to pull_request_target to publish fork code.
Same-repository publishing uses GITHUB_TOKEN in the build job.
Publishing previews to the production package does not restrict what the token can access.
Only trusted contributors should be able to create branches in the repository.
Set the shared package's visibility to public if anonymous pulls are intended, and grant the caller repository Actions write access for an existing package.
Migrating from separate preview packages¶
Deploy the website's pr- tag filtering before publishing previews into production
packages. Remove .github/workflows/container-pr-cleanup.yml from every caller
before removing the shared cleanup workflow and tooling, so scheduled callers
cannot reference a deleted workflow. Then publish the updated shared container
workflow, keeping pinned uses and shared-ref values coordinated.
Existing -pr packages are not migrated or deleted automatically. Historical PR
comments still point to those packages; new successful builds update the comments
to the shared package. Existing preview artifacts remain available unless retired
separately. Rerun all jobs in open PR workflows after the rollout to use the new
shared workflow and tooling.
Required root metadata and release tracks¶
Keep application and base-image pins in the root meta.yaml.
A single stable track is enough; add preview or older maintained tracks only when needed.
For example:
tracks:
- name: stable
version: "1.2.3"
baseImage: debian:13-slim@sha256:a29215f6a35e51e22adffa17f89e9d2ef06214e64a2bad10d765c46aea49f11f
tags: ["${version}", latest, stable, "${major}.${minor}"]
- name: preview
version: "2.0.0-rc.1"
baseImage: debian:13-slim@sha256:a29215f6a35e51e22adffa17f89e9d2ef06214e64a2bad10d765c46aea49f11f
tags: ["${version}", preview]
buildArgs:
PACKAGE_REVISION: "1"
To migrate existing callers, remove app-version, tracks-file, image, context, containerfile, build-args, and platforms inputs from callers.
Move any non-default build settings into meta.yaml: image at the top level and context, containerfile, platforms, and buildArgs on the relevant tracks.
Move application versions into tracks with explicit aliases, and move metadata from any other directory to the repository root.
These workflow inputs and the release planner's legacy environment-based configuration are no longer supported.
A complete example is in examples/meta.yaml.
Its versions are fictional.
Each Containerfile must be able to install the chosen version on every configured architecture.
Track configuration does not discover upstream releases or make unavailable prerelease packages available.
Configuration supports an optional top-level image and per-track baseImage, context, containerfile, platforms (comma-separated), buildArgs (string map), and upstream discovery metadata.
Application versions may use three or four numeric components (X.Y.Z or X.Y.Z.W), with an optional prerelease suffix.
Set prerelease: true on tracks whose upstream releases are prereleases despite having purely numeric versions.
This flag is carried through the build matrix to release reservation and cannot be used to make a suffixed prerelease stable.
An image-version suffix also implies prerelease behavior, even if the upstream version is numeric.
Such tracks may only own named aliases like develop or preview, never latest, stable, or numeric series aliases.
The planner skips tracks explicitly marked prerelease: true when any non-prerelease track has a higher application version, regardless of track names or order.
This applies to both PR builds and production releases.
Versions are compared numerically across all three or four components; a missing fourth component is treated as zero.
A stable version is also newer than a suffixed prerelease with the same numeric components.
For example, stable 6.4.4.10685 suppresses a prerelease track pinned to 6.4.4.10684.
Tracks with a prerelease suffix but no explicit prerelease: true are not filtered.
Skipped tracks are still validated, including tag ownership; equal versions remain subject to the existing ownership checks.
Existing images, tags, and releases are left unchanged.
Supported datasources are:
deb: Debian packagedepName, HTTP(S)registryUrlwithsuite,components, andbinaryArchquery parameters, and full stableX.Y.Z-Npackageversion. The release tooling strips the package revision for image tags and releases, but passes the full package pin as theAPP_VERSIONbuild argument.pypi: PyPI packagedepNameand stableX.Y.Zpackageversion. An optional HTTP(S)registryUrlselects an alternate index; omit it for public PyPI. The package version becomesAPP_VERSIONunchanged. Other PEP 440 formats, including prereleases, post releases, epochs, and local versions, are not supported.- Other Renovate datasource identifiers, including
github-releases: a nonemptydepName, a supported three- or four-partversion, and an optional HTTP(S)registryUrl. Configure any tag-prefix extraction and versioning in Renovate; the Containerfile must install the exact version.
When using upstream, omit the track-level version.
All datasources inject the exact package or application pin as APP_VERSION.
Without upstream, the track's version is used unchanged.
Containerfiles use ARG APP_VERSION to receive the pin; ARG PACKAGE_VERSION
receives the packaging identity, not another upstream version pin.
For example:
tracks:
- name: stable
upstream:
datasource: pypi
depName: gallery-dl
version: "1.32.16"
baseImage: debian:13-slim@sha256:a29215f6a35e51e22adffa17f89e9d2ef06214e64a2bad10d765c46aea49f11f
tags: ["${version}", "${major}", "${major}.${minor}", latest]
The release tooling never uses registry metadata to fetch or execute anything.
Renovate parses it as YAML for discovery, regardless of key order.
The Containerfile configures the package source and installs the pinned version.
registryUrl is used only for discovery and is not a build argument.
baseImage belongs to each track; a top-level baseImage is rejected.
The YAML decoder also rejects unknown fields, duplicate keys, and multiple documents.
Omitted build settings use the standard defaults above.
Additional build arguments are declared only in each track's buildArgs;
APP_VERSION, BASE_IMAGE, and PACKAGE_VERSION are reserved and cannot be
overridden there.
APP_VERSION is always supplied by the release planner in the workflow's build arguments.
The ${version} placeholder uses the application version without the Debian package revision.
APP_VERSION remains the exact installation pin and never receives a synthetic image suffix.
Image labels use the expanded image version, including any configured suffix.
All tracks share one image repository; tracks installing the same application version must use distinct image versions and tags.
Explicit tags and immutable revisions¶
Every track must declare a nonempty tags list with exactly one template containing ${version}.
This template must be ${version} or ${version}-<suffix>, and its expanded value must be a supported three- or four-part version with an optional prerelease suffix.
Its position in the list does not matter.
The planner expands ${major} and ${minor} too; quote templates in YAML.
For an upstream release that is numeric but not stable:
tracks:
- name: prerelease
upstream:
datasource: github-releases
depName: Sonarr/Sonarr
version: "5.0.0.2668"
prerelease: true
tags:
- "${version}-prerelease"
- "${major}-prerelease"
- "${major}.${minor}-prerelease"
The installation pin is 5.0.0.2668, while the image version is 5.0.0.2668-prerelease.
The first publication creates immutable image tag 5.0.0.2668-prerelease-r0 and GitHub release tag v5.0.0.2668-prerelease-r0.
Configured tags 5.0.0.2668-prerelease, 5-prerelease, and 5.0-prerelease follow its newest revision.
Neither 5.0.0.2668 nor 5.0.0.2668-r0 is generated.
Revision allocation is per image version, so stable and prerelease namespaces are independent.
release.json schema version 2 retains version as the application version and adds required imageVersion for the expanded image version.
immutableTag is ${imageVersion}-rN; aliasesAtPublication records every configured expanded moving tag, including the version tag.
The website accepts both schemas: historical schema version 1 derives its image version from version.
Do not rewrite historical release assets during migration.
To migrate meta.yaml, rename aliases to tags, add "${version}" (or a suffixed equivalent), and replace {major} / {minor} with ${major} / ${minor}.
The old aliases field and placeholder syntax are rejected.
Deploy website schema support before publishing schema version 2 releases, and coordinate shared tooling and caller updates.
Old registry tags remain until explicitly retired; adding suffixed tags alone does not hide historical unsuffixed prerelease tags from Renovate.
If existing images are retagged into the new revision namespace, also reserve those revisions with matching Git tags at their original source commits so future releases cannot reuse them.
The following rules apply to all tracks:
- All tracks live on the default branch. PRs validate the complete configuration and build every track, publishing previews only when eligible. Releases build tracks one at a time under the existing repository-wide publishing lock. A failure in one track does not stop the others.
- Each track declares all moving tags explicitly in
tags, including its${version}template. Only the immutable revision tag is created automatically. - Tags may contain
${major}and${minor}, e.g."${major}.${minor}"becomes0.8for application version0.8.0. Expansion happens before validation and ownership checks, so duplicate or conflicting expanded aliases are rejected. Unknown placeholders are rejected. Prereleases still cannot own numeric series aliases. Removing a previously expanded series does not delete its old tag. - Track names, image versions, and tags must be unique where applicable. No two tracks may own the same tag. Full versions other than the track's image version and revision-shaped tags cannot be declared as moving tags.
- Prereleases cannot own
latest,stable, or numeric version-series aliases. Version build metadata (+...) is unsupported because+is not a Docker tag character. Versions ending in-rNare reserved for image revisions. - Revisions are allocated per exact image version, including prerelease identifiers, using both Git tags and releases/drafts. They do not reset when a track is renamed or a version is reassigned to another track.
- The
pr-tag prefix is reserved for PR previews and is rejected in production tags. - Promotion requires a reviewed configuration change; build order does not promote tracks. Removing a track stops its builds but does not delete historical tags or remove its old moving aliases from GHCR. Retire obsolete aliases explicitly; retaining one must not be interpreted as a promise of maintenance.
- Keep alias ownership consistent across configuration changes. Do not repurpose a former exact-version alias for another application version. Use only one publishing caller/configuration per image repository.
Skipping unchanged releases¶
Before a default-branch push builds production images, the shared workflow runs
container-release release-plan. It compares each active track with its newest
published GitHub release, using the release's Git tag to read historical files.
Drafts do not count as successful publication. A failed release therefore leaves
its source changes eligible for the next push, including a subsequent docs-only
commit. No new release assets or historical metadata changes are needed.
The comparison includes:
- Effective per-track build and publication settings: application and image versions, base-image pin, build arguments, paths, platforms, destination image, tags, and prerelease status.
- Git-tracked files in the build context, including file names, contents, symlink
targets, additions, deletions, and executable modes. Docker ignore patterns and
negations apply; a Containerfile-specific
.dockerignoretakes precedence over the context's.dockerignore. - The Containerfile and active ignore file, even if excluded by ignore patterns
or located outside the context, plus repository-root
tests/files used for host-side smoke testing.
There is no implicit exclusion for README files or metadata: a Containerfile may
use COPY .. Image repositories should explicitly keep non-build files out of
their context, for example with this root .dockerignore:
Excluding meta.yaml from the context lets the comparison use each track's
effective settings instead of treating every metadata edit as a change to every
track. Do not exclude files that the Containerfile needs to copy. Smoke tests
remain release inputs despite the tests exclusion because they run on the host.
Without an applicable exclusion, a tracked context file conservatively triggers
a rebuild even if the Containerfile does not currently copy it.
The planner records each track's build/skip decision in the workflow summary. When every track is unchanged, it skips the production build matrix entirely: no registry upload, revision reservation, tag movement, release, or website notification occurs. PRs still build and test every active track as before. New tracks, missing historical files, older unsupported metadata formats, and layouts that cannot be compared safely (such as symlinked Containerfiles or ignore files) cause a rebuild rather than a skip. Release-history API failures fail planning instead of silently treating a lookup error as unchanged inputs.
This detects source-input changes, not identical runtime contents. Image digests are unsuitable for this check because revision labels, timestamps, and attestations can change without meaningful application changes. Dependencies downloaded during a build can also change without a packaging commit. Scheduled and manual runs deliberately bypass the comparison to refresh these dependencies and to repair publication failures or aliases. Shared-tooling updates alone do not trigger a caller push; use a manual or scheduled run to apply them.
Publish the shared workflow and tooling before rolling out caller ignore files. Adding an ignore file is itself a build-input change and produces a release.
Required PR validation¶
PR builds are uncached on every configured platform so an earlier build cannot hide a missing APT package.
Require container / pull-request-check in GitHub branch protection/rulesets, not individual matrix-track checks.
This fixed aggregate check succeeds only when planning and every active track build succeed;
failed, cancelled, or unexpectedly skipped dependencies fail the check.
Superseded prerelease tracks are omitted from the matrix and do not need separate required checks.
When migrating existing protection, publish the shared workflow first, rerun all jobs in open PR workflows to create the new check,
then apply the OpenTofu configuration to replace the old per-track requirements.
Rerunning only failed jobs can reuse the old shared-workflow commit.
Package discovery for one architecture is not proof of availability for another; rerun failed checks after delayed upstream publication.
PRs publish only pr- preview tags in the shared package, never production tags
or aliases.
Packaging changelogs are scoped to the previous release of the same track; pre-existing stable releases without a track marker remain compatible.
Base-image configuration¶
Keep the full image name, readable tag, and multiarch manifest digest together:
tracks:
- name: stable
version: "1.2.3"
baseImage: debian:13-slim@sha256:a29215f6a35e51e22adffa17f89e9d2ef06214e64a2bad10d765c46aea49f11f
tags: ["${version}", latest]
Each track declares its own baseImage; there is no top-level default.
Every configured reference must include the image name, tag, and SHA-256 digest; 13-slim@sha256:... alone is not a full reference.
Verify the digest belongs to the selected tag and supports the target architectures.
Syntax validation cannot establish those registry facts.
Use this pattern in each applicable Containerfile:
The planner passes the effective BASE_IMAGE argument to both PR and release builds, so the workflow does not duplicate the pin.
In track mode, set the pin with baseImage; setting BASE_IMAGE in track build arguments creates competing values that the planner rejects.
baseImage remains optional for compatibility with images that retain a literal FROM reference.
A parameterized Containerfile has no fallback: local builds must also supply --build-arg BASE_IMAGE=....
The shared pipeline supplies BUILDKIT_DOCKERFILE_CHECK=skip=InvalidDefaultArgInFrom as a build argument in both PR and release builds.
This skips only the linter's requirement for a default FROM argument; all other checks remain enabled, and an absent or invalid BASE_IMAGE still fails the actual build.
No # check= directive or ARG declaration for this BuildKit option is needed in individual Containerfiles.
For the same behavior locally, pass --build-arg BUILDKIT_DOCKERFILE_CHECK=skip=InvalidDefaultArgInFrom.
The shared Renovate preset detects track baseImage fields in meta.yaml, using Docker versioning to retain suffixes such as -slim.
Tag and digest updates require review and trigger normal PR builds.
Publish the preset and shared tooling before migrating caller repositories.
Website integration¶
The website can read release.json assets from public GitHub releases and resolve all current tags directly against GHCR.
Historical alias lists record assignments at publication time, which may differ from current assignments.
Releases created before this metadata was added remain valid; the website lists them with only the data available.
For immediate refreshes, forward the organization's DOCS_TOKEN secret in the caller job.
The shared workflow defaults to notifying tuxcrate/docs, and shared-ref already defaults to main:
Use a GitHub App installation token or fine-grained token with contents: write on the docs repository only.
The organization secret must be available to each caller repository.
secrets: inherit forwards all secrets available to the caller, not just DOCS_TOKEN.
For narrower access, use an explicit mapping instead:
The old explicit docs-token mapping remains supported for existing callers and takes precedence if both names are provided.
Secrets stored only in the shared workflow repository are not available to callers.
The caller's GITHUB_TOKEN cannot dispatch to a different repository.
Never pass the website token into builds or PR jobs.
The workflow sends one notification after all release tracks finish successfully; PR builds and failed releases do not notify.
A missing token produces a warning.
If the notification fails, the release still succeeds; the website refreshes on its hourly schedule.
You can also configure DOCS_TOKEN as a repository secret.
Set with.docs-repository: '' to disable notifications, or override it to notify another repository.
Manual runs can also refresh the website without this token.
Setup¶
- Publish this repository's workflow and tooling before enabling a caller.
- Allow the caller to use the shared workflow under the organization's Actions policy and allow
contents: writeandpackages: writefor releases. - For an existing GHCR package, grant the caller repository Actions write access.
Set package visibility to public if anonymous pulls are intended; publishing with
GITHUB_TOKENdoes not itself guarantee public visibility. - Ensure repository tag rules allow
GITHUB_TOKENto create thevX.Y.Z-rNrelease tags (and prerelease equivalents when used).
Rebuilding refreshes installed packages. To update a digest-pinned base image, merge its digest update. Neither action fixes vulnerabilities compiled into an upstream binary. Those may require a new upstream release or an application rebuild with a newer toolchain. A scheduled rebuild does not necessarily fix a vulnerability.
Development¶
The release CLI lives in cmd/container-release.
It is written in Go and uses go.yaml.in/yaml/v3 for strict YAML parsing.
The workflow compiles it using the Go toolchain provided by the Ubuntu runner; Go 1.23 or newer is required.
Build it with go build -o /path/to/container-release ./cmd/container-release.
Run the binary from the container source checkout with plan, release-plan,
metadata, manifest, reserve, or finalize and the required workflow
environment variables set.
release-plan is read-only: on push events it needs full Git history, GH_TOKEN, and release-list access; it emits a filtered matrix and a changed boolean to GITHUB_OUTPUT.
Publication commands receive APP_VERSION (the application version, without an APT package revision), IMAGE_VERSION (the expanded version tag), and TAGS (a JSON array of expanded moving tags) from the planner's build matrix.
Only the Containerfile's build argument receives a full APT package pin.
The plan command always reads meta.yaml from the current directory; it has no alternate path or environment fallback.
The reserve command creates a real draft release before building and does not
require IMAGE_DIGEST. Its outputs include release-id, tag, tags, package-version,
and latest. After upload, finalize takes
RELEASE_ID, RELEASE_TAG, IMAGE_DIGEST, and PLATFORMS alongside the publication inputs
to fill that draft's release notes. Both commands modify GitHub releases;
use go test for validation without publishing.
Changelog integration tests use Git directly.
CI runs all tests on every PR and default-branch push.
Third-party actions are pinned to commit SHAs and updated through the shared Renovate preset.
The repository's renovate.json extends that preset; install and enable the Renovate GitHub App to activate updates.