talosctl-image/README.md

talos tools image

An OCI image (Wolfi-based) containing:

• talosctl
• talhelper
• sops

The image is built on Wolfi to keep size and surface area minimal, then built via Forgejo Actions. On pushes to main (or master), the image is pushed to your Forgejo container registry. On other branches, the workflow builds the image but does not push it (to validate PRs). The published tag encodes the versions of all three tools:

• Tag format: v<TALOSCTL>-<TALHELPER>-<SOPS> (for example: v1.9.2-3.0.39-3.11.0), plus latest.

Contents are defined in Dockerfile. Versions are pinned via build ARGs so they can be updated automatically by Renovate. Additionally, the build verifies SHA256 checksums for all downloaded binaries and includes their source URLs and checksums inside the image at /usr/local/share/checksums/.

Setup

1. Configure Forgejo variables and secrets

• Repository Variables (Settings → Variables):
  • REGISTRY: the registry hostname, e.g. forgejo.example.com
  • IMAGE_NAME: full image name including registry and path, e.g. forgejo.example.com/owner/talos-tools
• Repository Secrets (Settings → Secrets):
  • REGISTRY_USERNAME: username with push permission to the registry
  • REGISTRY_PASSWORD: the password or token

2. Enable the workflow The workflow file .forgejo/workflows/build.yml runs on any branch push and on manual dispatch.

• On main/master: it builds a multi-arch image (linux/amd64, linux/arm64) and pushes it, using a registry-backed Buildx cache (no extra infra needed).
• On other branches: it builds the image (no push) to ensure the change is buildable before merging.

3. Renovate configuration renovate.json configures Renovate to track GitHub releases and update the version ARGs in the Dockerfile for:

• siderolabs/talos (talosctl)
• budimanjojo/talhelper
• getsops/sops

When Renovate opens a PR and it is merged, the workflow will build and push a new image. The tag is computed from the three versions in the Dockerfile.

Local build To build locally (example versions):

docker build \
  --build-arg TALOSCTL_VERSION=1.9.2 \
  --build-arg TALHELPER_VERSION=3.0.39 \
  --build-arg SOPS_VERSION=3.11.0 \
  -t talos-tools:dev .

Image usage

docker run --rm -it your.registry/owner/talos-tools:v1.9.2-3.0.39-3.11.0 talosctl version --client

Notes

• The workflow uses Docker Buildx and QEMU to produce multi-arch images.
• The Dockerfile maps architectures to the upstream asset names as required (e.g., talhelper uses amd64 and arm64 asset names).
• Base image: cgr.dev/chainguard/wolfi-base:latest for a smaller footprint than Alpine. Renovate is enabled to track and pin the base image digest automatically.
• Runtime shell: bash is included because this image is intended to be used in Forgejo Actions jobs that require a shell.
• Integrity: SHA256 checksum verification is performed during the image build for talosctl, talhelper (tarball), and sops.