Thin, hardened, version-pinned images for CI jobs and tooling: built from pinned inputs on Docker Hardened Images, scanned before and after publishing, signed, and published to GHCR and Docker Hub from the same digest.
- Overview
- Quick start
- How it works
- Using this as a starting point
- Images
- Choosing an image
- Tags, versions and support
- Usage
- Self-hosted CI agents
- Podman in a container
- Configuration reference
- Adding an organisation's CA bundle
- Pinning by digest or date tag
- Security and supply chain
- Built from source
- Changing the base image
- Troubleshooting
- Developing
- Contributing
- Licence
Twelve images, each a thin layer of pinned tools on a hardened base:
python: CPython and uv, with one tag for every supported CPython from 3.12 upwards.ansible: ansible-core, ansible-lint and Molecule in their own virtual environment, with the containers.podman collection, jmespath, netaddr, pywinrm, OpenSSH (built from its latest release: see Built from source) and uv. The current release, plus 2.16 for managing hosts whose only Python is 3.6, and apodmanflavour for Molecule scenarios that test against containers (see Ansible).ansible-azure: theansibleimage with the azure.azcollection collection and every Python library its modules need.azure-cli: the Azure CLI in its own virtual environment, andldo-cli. The current release, plus 2.72.0 as a long-lived line, and afunctionsflavour with Azure Functions Core Tools (func) (see Azure Functions).terraform: tenv with a default Terraform, TFLint, terraform-docs and Conftest. A repository's.terraform-versionwins over the default. Also as an Alpine variant (-alpinetags), about a third smaller.azure-terraform: theterraformimage with the azurerm, azapi and msgraph providers (the newest three minor releases of each) in a local mirror, soterraform initneeds no registry for them (see azure-terraform).powershell: PowerShell LTS with PSScriptAnalyzer, Pester, Az, Microsoft.Graph and LibreDevOpsHelpers.toolbox: Python, the Azure CLI, Terraform and PowerShell in one image, assembled from the same build stages.cicd-helper: Ansible with ansible-lint, Molecule, pytest and every libre_devops role and the collections they use, beside the Azure CLI, Terraform withazure-terraform's provider mirror, PowerShell with Az and Microsoft.Graph, yq and just. Assembled liketoolbox, without ldo-cli, LibreDevOpsHelpers or Podman (see cicd-helper).podman: Podman set up to run rootless inside a container (Podman in Podman, or in Docker or Kubernetes), with adockercommand that runs it.ansible,azure-cli,terraformandtoolboxalso come as-podmanflavours built on it, for CI jobs that build and push images or test against containers (see Podman in a container).azure-pipelines-agent,github-runnerandgitlab-runner: self-hosted CI agents that set themselves up from environment variables and run one job per container. Each also comes as atoolboxflavour with every toolbox tool in it, and atoolbox-podmanflavour that adds Podman, so jobs can build images (see Self-hosted CI agents).
What every image guarantees:
| Property | How |
|---|---|
| Hardened base | Docker Hardened Images on Debian 13 (Alpine 3.24 for -alpine tags), pinned by digest |
| No known fixable vulnerabilities at publication | Scanned on every pull request, at release (the exact digest pushed) and daily after; fixes are applied at the source, not excused |
| Every input pinned | Bases by digest; downloads by version and SHA-256 per platform; Go modules through the Go checksum database; Python packages by hash |
| Reproducible references | Date tags are never overwritten; every tag has the same digest in GHCR and Docker Hub |
| Verifiable | cosign keyless signature, SBOM and SLSA provenance on every published digest |
| Non-root | Runs as app (uid 10001) in /work; works rootless under Podman, and as an arbitrary uid in group 0 |
| Multi-platform | linux/amd64 and linux/arm64, each built natively |
| Portable | The same build runs on RHEL (UBI), Wolfi and Alpine bases, proven every two weeks |
| Current | Rebuilt every Monday, on every merge, and whenever a published image can be fixed by a rebuild |
# Pull from either registry; the digest is the same.
docker pull ghcr.io/libre-devops/terraform:1
docker pull docker.io/libredevops/terraform:1
# Run against the current directory.
docker run --rm -v "$PWD:/work" ghcr.io/libre-devops/terraform:1 terraform fmt -check
# Verify the signature before you trust it.
cosign verify ghcr.io/libre-devops/terraform:1 \
--certificate-identity https://github.com/libre-devops/container-images/.github/workflows/release.yml@refs/heads/main \
--certificate-oidc-issuer https://token.actions.githubusercontent.comEvery image, version and base is listed in versions.yml, and every change to
it reaches the registries the same way: a pull request that builds, tests and scans every image,
then a release from main. Bots keep the versions and pins current, and a published image is
rebuilt as soon as a fix for it exists. The numbers match the step key in the full diagram below.
flowchart TB
subgraph upstream["Upstream"]
rel["Tool releases<br/>GitHub, PyPI, Galaxy, Terraform registry,<br/>PowerShell Gallery"]
dhi["Docker Hardened Images<br/>Debian 13 and Alpine bases"]
end
subgraph current["Keeping current"]
renovate["Renovate<br/>weekly, and at once for security fixes"]
pins["Pins workflow, daily<br/>digests, providers and roles;<br/>SHA-256 pins; vulnerable dependencies patched"]
end
subgraph pr["Pull request: Build workflow"]
pull["Pull request"]
build["Build every image<br/>natively on amd64 and arm64"]
tests{{"Smoke tests"}}
scan{{"Trivy scan gate"}}
pass{"All pass?"}
end
subgraph main["Main: Release and Scan workflows"]
merge["Merge to main"]
release["Release<br/>one digest in both registries"]
readme["README digests<br/>pull request"]
daily["Scan workflow, daily"]
end
subgraph registries["Registries"]
ghcr["ghcr.io/libre-devops"]
hub["docker.io/libredevops"]
sig["cosign signature,<br/>SBOM, SLSA provenance"]
end
subgraph run["Where images run"]
ci["CI jobs"]
agents["Self-hosted agents"]
hosts["Workstations and clusters"]
end
rel -->|1| renovate
dhi -->|2| pins
renovate -->|3| pull
pins -->|4| pull
pull -->|5 every push| build
build -->|6| tests
tests -->|7| scan
scan --> pass
pass -->|8 fails| pull
pass -->|9 passes| merge
merge -->|10| release
release -->|11| ghcr
release --> hub
hub -.->|12| sig
release -->|13| readme
ghcr -->|14| ci
hub --> agents
hub --> hosts
daily -->|15 a fix exists| release
classDef step fill:#ffffff,stroke:#666666,color:#1a1a1a
classDef gate fill:#fff2cc,stroke:#d6b656,color:#1a1a1a
classDef upstreamNode fill:#f5f5f5,stroke:#666666,color:#1a1a1a
classDef registry fill:#dae8fc,stroke:#6c8ebf,color:#1a1a1a
classDef yours fill:#d5e8d4,stroke:#82b366,color:#1a1a1a
class renovate,pins,pull,build,merge,release,readme,daily,sig step
class tests,scan,pass gate
class rel,dhi upstreamNode
class ghcr,hub registry
class ci,agents,hosts yours
style upstream fill:#ffffff,stroke:#666666,color:#1a1a1a
style current fill:#ffffff,stroke:#b85450,color:#1a1a1a
style pr fill:#ffffff,stroke:#b85450,color:#1a1a1a
style main fill:#ffffff,stroke:#b85450,color:#1a1a1a
style registries fill:#ffffff,stroke:#6c8ebf,color:#1a1a1a
style run fill:#ffffff,stroke:#82b366,color:#1a1a1a
The full diagram, with icons and each step explained. Its source is
docs/diagrams/container-deployment.drawio: open
it in draw.io to edit it.
This repository is meant to be forked and owned: a working pipeline to start from, not a finished product. To make it yours:
- Registries. Set
registriesinversions.ymlto your GHCR organisation and Docker Hub namespace, andREPOSITORYinscripts/images.pyto your fork's URL. It goes into the image labels, the cosign signing identity and the Docker Hub overview. - Secrets and settings. Add
DOCKERHUB_USERNAMEandDOCKERHUB_TOKENas repository secrets. They push to Docker Hub and pull the Docker Hardened Images bases fromdhi.io, which needs an entitlement. Allow GitHub Actions to create pull requests (organisation and repository settings), and install Renovate. - Bases. Without a Docker Hardened Images entitlement, point
basesat Red Hat UBI or Wolfi; the portability builds show every image works on them.just pinresolves the digests. - Images. Delete the images you do not need from
versions.yml, with their stage inimages/Containerfileand theirtests/suite, and add your own the same way (see Adding a version).
Optional parts you can delete without breaking the rest:
| Part | Remove |
|---|---|
| The CI agents | Their entries in versions.yml, images/agents/, their stages and tests |
Podman and the -podman flavours |
The podman entry, the base_stage: podman lines, images/podman/, tests/podman.sh |
azure-terraform |
Its entry and terraform_providers in versions.yml, images/terraform/ |
| The OpenSSH source build | Only the ansible images use it: switch them to os_packages: [ssh] (see Built from source) |
| Portability builds | portability in versions.yml, and .github/workflows/portability.yml |
| Automatic re-runs | .github/workflows/retry.yml |
Locally, just build, just test, just scan and just lint run the same steps CI does.
| Image | Tags | Base | Contents | Pull |
|---|---|---|---|---|
python |
3.123.12-YYYYMMDD |
dhi.io/python:3.12-debian13-dev |
CPython 3.12, uv 0.13.7 | ghcr.io/libre-devops/python:3.12docker.io/libredevops/python:3.12 |
python |
3.133.13-YYYYMMDD |
dhi.io/python:3.13-debian13-dev |
CPython 3.13, uv 0.13.7 | ghcr.io/libre-devops/python:3.13docker.io/libredevops/python:3.13 |
python |
3.143.14-YYYYMMDD |
dhi.io/python:3.14-debian13-dev |
CPython 3.14, uv 0.13.7 | ghcr.io/libre-devops/python:3.14docker.io/libredevops/python:3.14 |
python |
3.15 3 latest3.15-YYYYMMDD |
dhi.io/python:3.15-debian13-dev |
CPython 3.15, uv 0.13.7 | ghcr.io/libre-devops/python:3.15docker.io/libredevops/python:3.15 |
podman |
5 latest5-YYYYMMDD |
dhi.io/debian-base:trixie-debian13-dev |
Podman 5 from the distribution, with crun, fuse-overlayfs and a docker command, rootless for the app user | ghcr.io/libre-devops/podman:5docker.io/libredevops/podman:5 |
azure-cli |
2.92.0 latest2.92.0-py3.12-YYYYMMDD |
dhi.io/python:3.12-debian13-dev |
Azure CLI 2.92.0 on Python 3.12, ldo-cli 0.8.1 | ghcr.io/libre-devops/azure-cli:2.92.0docker.io/libredevops/azure-cli:2.92.0 |
azure-cli |
2.92.0-podman podman2.92.0-py3.12-podman-YYYYMMDD |
dhi.io/python:3.12-debian13-dev |
Azure CLI 2.92.0 on Python 3.12, ldo-cli 0.8.1 | ghcr.io/libre-devops/azure-cli:2.92.0-podmandocker.io/libredevops/azure-cli:2.92.0-podman |
azure-cli |
2.92.0-functions functions2.92.0-py3.12-functions-YYYYMMDD |
dhi.io/python:3.12-debian13-dev |
Azure CLI 2.92.0 on Python 3.12, ldo-cli 0.8.1, and Azure Functions Core Tools 4.16.1 (func) | ghcr.io/libre-devops/azure-cli:2.92.0-functionsdocker.io/libredevops/azure-cli:2.92.0-functions |
azure-cli |
2.72.02.72.0-py3.12-YYYYMMDD |
dhi.io/python:3.12-debian13-dev |
Azure CLI 2.72.0 on Python 3.12, ldo-cli 0.8.1 | ghcr.io/libre-devops/azure-cli:2.72.0docker.io/libredevops/azure-cli:2.72.0 |
terraform |
1.17.2 1.17 1 latest1.17.2-YYYYMMDD |
dhi.io/debian-base:trixie-debian13-dev |
Terraform 1.17.2 by default (tenv 4.15.1; a repository's .terraform-version wins), TFLint 0.66.0, terraform-docs 0.24.0, Conftest 0.71.1 | ghcr.io/libre-devops/terraform:1.17.2docker.io/libredevops/terraform:1.17.2 |
terraform |
1.17.2-alpine 1.17-alpine 1-alpine alpine1.17.2-alpine-YYYYMMDD |
dhi.io/alpine-base:3.24-alpine3.24-dev |
Terraform 1.17.2 by default (tenv 4.15.1; a repository's .terraform-version wins), TFLint 0.66.0, terraform-docs 0.24.0, Conftest 0.71.1 | ghcr.io/libre-devops/terraform:1.17.2-alpinedocker.io/libredevops/terraform:1.17.2-alpine |
terraform |
1.17.2-podman 1.17-podman 1-podman podman1.17.2-podman-YYYYMMDD |
dhi.io/debian-base:trixie-debian13-dev |
Terraform 1.17.2 by default (tenv 4.15.1; a repository's .terraform-version wins), TFLint 0.66.0, terraform-docs 0.24.0, Conftest 0.71.1 | ghcr.io/libre-devops/terraform:1.17.2-podmandocker.io/libredevops/terraform:1.17.2-podman |
ansible |
2.22.0 2.22 latest2.22.0-py3.14-YYYYMMDD |
dhi.io/python:3.14-debian13-dev |
ansible-core 2.22.0 on Python 3.14, with ansible-lint, Molecule, containers.podman 1.21.2, jmespath, netaddr, pywinrm, OpenSSH 10.6p2 and uv 0.13.7 | ghcr.io/libre-devops/ansible:2.22.0docker.io/libredevops/ansible:2.22.0 |
ansible |
2.22.0-podman 2.22-podman podman2.22.0-py3.14-podman-YYYYMMDD |
dhi.io/python:3.14-debian13-dev |
ansible-core 2.22.0 on Python 3.14, with Molecule and containers.podman 1.21.2 for scenarios that test against containers, Podman 5, ansible-lint, OpenSSH 10.6p2 and uv 0.13.7 | ghcr.io/libre-devops/ansible:2.22.0-podmandocker.io/libredevops/ansible:2.22.0-podman |
ansible |
2.16.20 2.162.16.20-py3.12-YYYYMMDD |
dhi.io/python:3.12-debian13-dev |
ansible-core 2.16.20 on Python 3.12, for hosts whose only Python is 3.6 (RHEL 8): the last line that supports them. With ansible-lint, Molecule, containers.podman 1.21.2, jmespath, netaddr, pywinrm, OpenSSH 10.6p2 and uv 0.13.7 | ghcr.io/libre-devops/ansible:2.16.20docker.io/libredevops/ansible:2.16.20 |
ansible-azure |
4.2.0 4 latest4.2.0-YYYYMMDD |
dhi.io/python:3.14-debian13-dev |
azure.azcollection 4.2.0 and its Python requirements, on ansible-core 2.22.0 and Python 3.14, with ansible-lint, Molecule, containers.podman 1.21.2, OpenSSH 10.6p2 and uv 0.13.7 | ghcr.io/libre-devops/ansible-azure:4.2.0docker.io/libredevops/ansible-azure:4.2.0 |
azure-terraform |
1.17.2 1.17 1 latest1.17.2-YYYYMMDD |
dhi.io/debian-base:trixie-debian13-dev |
Terraform 1.17.2 by default, TFLint 0.66.0, terraform-docs 0.24.0, Conftest 0.71.1; in a local provider mirror, azurerm 5.14.0, 5.13.0, 5.12.0, azapi 2.14.0, 2.13.0, 2.12.0 and msgraph 0.6.0, 0.5.0, 0.4.0 | ghcr.io/libre-devops/azure-terraform:1.17.2docker.io/libredevops/azure-terraform:1.17.2 |
powershell |
7.6.10 7.6 7 lts latest7.6.10-YYYYMMDD |
dhi.io/debian-base:trixie-debian13-dev |
PowerShell 7.6.10, Az 16.5.0, Microsoft.Graph 2.41.2, Pester 6.2.0, PSScriptAnalyzer 1.25.0, LibreDevOpsHelpers 3.0.1 | ghcr.io/libre-devops/powershell:7.6.10docker.io/libredevops/powershell:7.6.10 |
toolbox |
1 latest1-YYYYMMDD |
dhi.io/python:3.12-debian13-dev |
Python 3.12 and uv 0.13.7, Azure CLI 2.92.0, ldo-cli 0.8.1, Terraform 1.17.2 by default (tenv 4.15.1), TFLint 0.66.0, terraform-docs 0.24.0, Conftest 0.71.1, PowerShell 7.6.10 with Az 16.5.0, Microsoft.Graph 2.41.2, Pester 6.2.0, PSScriptAnalyzer 1.25.0 and LibreDevOpsHelpers 3.0.1 | ghcr.io/libre-devops/toolbox:1docker.io/libredevops/toolbox:1 |
toolbox |
1-podman podman1-podman-YYYYMMDD |
dhi.io/python:3.12-debian13-dev |
Python 3.12 and uv 0.13.7, Azure CLI 2.92.0, ldo-cli 0.8.1, Terraform 1.17.2 by default (tenv 4.15.1), TFLint 0.66.0, terraform-docs 0.24.0, Conftest 0.71.1, PowerShell 7.6.10 with Az 16.5.0, Microsoft.Graph 2.41.2, Pester 6.2.0, PSScriptAnalyzer 1.25.0 and LibreDevOpsHelpers 3.0.1 | ghcr.io/libre-devops/toolbox:1-podmandocker.io/libredevops/toolbox:1-podman |
cicd-helper |
2.21.6 2.21 latest2.21.6-py3.12-YYYYMMDD |
dhi.io/python:3.12-debian13-dev |
ansible-core 2.21.6 on Python 3.12, with ansible-lint, yamllint, Molecule, pytest, every libre_devops role and the collections they use; Azure CLI 2.92.0; Terraform 1.17.2 by default (tenv 4.15.1), TFLint, terraform-docs and Conftest, with azurerm, azapi and msgraph in a local mirror; PowerShell 7.6.10 with Az 16.5.0, Microsoft.Graph 2.41.2, Pester 6.2.0 and PSScriptAnalyzer 1.25.0; uv 0.13.7, yq 4.54.3, just 1.59.0, OpenSSH 10.6p2, sshpass, rsync, zip and Requests for python3 | ghcr.io/libre-devops/cicd-helper:2.21.6docker.io/libredevops/cicd-helper:2.21.6 |
azure-pipelines-agent |
5.282.0 5 latest5.282.0-YYYYMMDD |
dhi.io/debian-base:trixie-debian13-dev |
Azure Pipelines agent 5.282.0, with git, curl, jq, ShellCheck and shfmt | ghcr.io/libre-devops/azure-pipelines-agent:5.282.0docker.io/libredevops/azure-pipelines-agent:5.282.0 |
azure-pipelines-agent |
5.282.0-toolbox 5-toolbox toolbox5.282.0-toolbox-YYYYMMDD |
dhi.io/python:3.12-debian13-dev |
Azure Pipelines agent 5.282.0 with everything in toolbox 1: Azure CLI 2.92.0, Terraform 1.17.2, PowerShell 7.6.10 with Az and Microsoft.Graph, Python 3.12 | ghcr.io/libre-devops/azure-pipelines-agent:5.282.0-toolboxdocker.io/libredevops/azure-pipelines-agent:5.282.0-toolbox |
azure-pipelines-agent |
5.282.0-toolbox-podman 5-toolbox-podman toolbox-podman5.282.0-toolbox-podman-YYYYMMDD |
dhi.io/python:3.12-debian13-dev |
Azure Pipelines agent 5.282.0 with everything in toolbox 1 and Podman 5, which jobs can use to build and run images (rootless; see the README for the outer container's flags) | ghcr.io/libre-devops/azure-pipelines-agent:5.282.0-toolbox-podmandocker.io/libredevops/azure-pipelines-agent:5.282.0-toolbox-podman |
github-runner |
2.338.2 2 latest2.338.2-YYYYMMDD |
dhi.io/debian-base:trixie-debian13-dev |
GitHub Actions runner 2.338.2, with git, curl, jq, ShellCheck and shfmt | ghcr.io/libre-devops/github-runner:2.338.2docker.io/libredevops/github-runner:2.338.2 |
github-runner |
2.338.2-toolbox 2-toolbox toolbox2.338.2-toolbox-YYYYMMDD |
dhi.io/python:3.12-debian13-dev |
GitHub Actions runner 2.338.2 with everything in toolbox 1: Azure CLI 2.92.0, Terraform 1.17.2, PowerShell 7.6.10 with Az and Microsoft.Graph, Python 3.12 | ghcr.io/libre-devops/github-runner:2.338.2-toolboxdocker.io/libredevops/github-runner:2.338.2-toolbox |
github-runner |
2.338.2-toolbox-podman 2-toolbox-podman toolbox-podman2.338.2-toolbox-podman-YYYYMMDD |
dhi.io/python:3.12-debian13-dev |
GitHub Actions runner 2.338.2 with everything in toolbox 1 and Podman 5, which jobs can use to build and run images (rootless; see the README for the outer container's flags) | ghcr.io/libre-devops/github-runner:2.338.2-toolbox-podmandocker.io/libredevops/github-runner:2.338.2-toolbox-podman |
gitlab-runner |
19.5.3 19 latest19.5.3-YYYYMMDD |
dhi.io/debian-base:trixie-debian13-dev |
GitLab Runner 19.5.3 (shell executor), with git, curl, jq, ShellCheck and shfmt | ghcr.io/libre-devops/gitlab-runner:19.5.3docker.io/libredevops/gitlab-runner:19.5.3 |
gitlab-runner |
19.5.3-toolbox 19-toolbox toolbox19.5.3-toolbox-YYYYMMDD |
dhi.io/python:3.12-debian13-dev |
GitLab Runner 19.5.3 (shell executor) with everything in toolbox 1: Azure CLI 2.92.0, Terraform 1.17.2, PowerShell 7.6.10 with Az and Microsoft.Graph, Python 3.12 | ghcr.io/libre-devops/gitlab-runner:19.5.3-toolboxdocker.io/libredevops/gitlab-runner:19.5.3-toolbox |
gitlab-runner |
19.5.3-toolbox-podman 19-toolbox-podman toolbox-podman19.5.3-toolbox-podman-YYYYMMDD |
dhi.io/python:3.12-debian13-dev |
GitLab Runner 19.5.3 (shell executor) with everything in toolbox 1 and Podman 5, which jobs can use to build and run images (rootless; see the README for the outer container's flags) | ghcr.io/libre-devops/gitlab-runner:19.5.3-toolbox-podmandocker.io/libredevops/gitlab-runner:19.5.3-toolbox-podman |
Every image also has bash, git, curl, ca-certificates, ShellCheck 0.11.0, shfmt 3.14.1, jq 1.8.2, runs as app (uid 10001) in /work, and is a multi-platform image for linux/amd64 and linux/arm64. The Go tools are built from source with Go 1.27.4.
| If you need | Use | Why |
|---|---|---|
| One tool family in a CI job | python, ansible, azure-cli, terraform or powershell |
Smaller pulls, smaller attack surface, fewer reasons to rebuild |
| Terraform for Azure in an air-gapped or restricted network | azure-terraform |
azurerm, azapi and msgraph install from a local mirror, with no registry |
| Ansible playbooks against Azure | ansible-azure |
The Azure collection and its many Python libraries, already installed and patched |
| Ansible for hosts whose only Python is 3.6, such as RHEL 8 | ansible:2.16 |
ansible-core 2.17 and later cannot manage them; see Ansible |
| Testing Ansible roles and collections with Molecule against containers | ansible:podman |
Molecule starts the test containers with Podman inside the image; see Molecule |
| Building and pushing images in a CI job, without Docker or a privileged container | podman, or a -podman flavour such as azure-cli:podman or toolbox:podman |
Rootless Podman inside the container; see Podman in a container |
| Self-hosted Azure Pipelines agents, GitHub Actions runners or GitLab runners | azure-pipelines-agent, github-runner, gitlab-runner |
Ephemeral by default; the toolbox tags carry every toolbox tool |
| Running the libre_devops Ansible roles, or Ansible beside Azure, Terraform and PowerShell | cicd-helper |
The roles and their collections installed, with the Azure CLI, Terraform and its provider mirror, and PowerShell; see cicd-helper |
| Several tool families in one job, or an interactive shell | toolbox |
Everything together; the largest image (the Az PowerShell modules and the Azure CLI dominate its size) |
| A specific CPython | python:<major.minor> |
One tag per supported CPython |
| The smallest Terraform image | terraform:alpine |
About a third smaller than the Debian image. musl, so not for Azure Pipelines container jobs, which need glibc |
| The Azure CLI behind TLS inspection that rejects Python 3.13's stricter checks | azure-cli:2.72.0 |
Long-lived line on Python 3.12 |
| Building, running or publishing Azure Functions apps | azure-cli:functions |
Azure Functions Core Tools (func) with the Azure CLI; about 600 MB more than azure-cli, so only on this flavour |
| Your organisation's CA, mirrors or internal tools | A thin layer FROM a pinned digest of one of these |
See Adding an organisation's CA bundle |
| Tag | Example | Moves? |
|---|---|---|
| Version and build date | python:3.12-20261107, azure-cli:2.72.0-py3.12-20261107 |
Never. A second build on the same day gets .2, .3 and so on |
| Version | python:3.12, azure-cli:2.72.0 |
Yes, to the newest build of that version |
| Major or major.minor | terraform:1, terraform:1.17, python:3, toolbox:1 |
Yes |
| Alias | powershell:lts |
Yes |
| Flavour | terraform:1.17.1-alpine, terraform:1-alpine, terraform:alpine |
As above, with the flavour as a suffix; the flavour's own name is its newest version |
latest |
python:latest |
Yes, to the newest supported version |
Every release records its digests in this README and in
releases.json.
What is built. Every version listed in versions.yml:
| Image | Versions |
|---|---|
python |
Every CPython release from 3.12 upwards that upstream still supports |
ansible |
The current ansible-core, on its own and with Podman (-podman tags), and 2.16 for managed hosts on Python 3.6 |
ansible-azure |
The current azure.azcollection, on the current ansible |
azure-cli |
The current release, on its own, with Podman (-podman tags) and with Azure Functions Core Tools (-functions tags), and 2.72.0 as a long-lived line for networks whose TLS inspection fails the stricter certificate checks in Python 3.13 and later |
terraform |
The current Terraform 1.x as the default, on Debian and on Alpine; any other version through .terraform-version |
azure-terraform |
The current terraform, with the newest three minor releases of azurerm, azapi and msgraph |
powershell |
The current PowerShell LTS |
toolbox |
The latest azure-cli, terraform and powershell, with the Azure CLI's Python |
cicd-helper |
ansible-core 2.21 (the last line on the Azure CLI's Python, 3.12), with the latest roles, azure-cli, terraform and its provider mirror, and powershell |
podman |
Podman 5 from the distribution, and -podman flavours of the latest ansible, azure-cli, terraform and toolbox |
azure-pipelines-agent, github-runner, gitlab-runner |
The current agent release, on its own, atop toolbox, and atop toolbox with Podman |
Support. A version is supported while it is listed in versions.yml: its moving tags are
rebuilt weekly and whenever a fix is available. When a version leaves versions.yml (for
example when upstream support ends), its tags stop moving and receive no further fixes, but
nothing published is ever deleted or re-tagged, so pinned references keep working.
The examples use moving tags for brevity. For anything you need to reproduce, pin a date tag or a digest (see Pinning by digest or date tag).
Every image runs as app (uid 10001) in /work, so mount what you work on there. On Linux,
add --user "$(id -u):0" so that the files the container writes stay yours; the images' home
and tool directories are writable by any uid in group 0. Docker Desktop on macOS and Windows
handles ownership itself.
# Python: the tests of a uv project
docker run --rm --user "$(id -u):0" -v "$PWD:/work" ghcr.io/libre-devops/python:3.13 uv run pytest
# Ansible (see Ansible below for SSH keys and collections)
docker run --rm --user "$(id -u):0" -v "$PWD:/work" -v "$HOME/.ssh:/home/app/.ssh:ro" \
ghcr.io/libre-devops/ansible:2.22 ansible-playbook -i inventory.ini site.yml
# Azure CLI: log in once, and keep the login in your own ~/.azure
mkdir -p ~/.azure # otherwise Docker creates it, owned by root
docker run --rm -it --user "$(id -u):0" -v "$HOME/.azure:/home/app/.azure" \
ghcr.io/libre-devops/azure-cli:latest az login --use-device-code
# Terraform, with a service principal from your environment
docker run --rm --user "$(id -u):0" -v "$PWD:/work" \
-e ARM_TENANT_ID -e ARM_SUBSCRIPTION_ID -e ARM_CLIENT_ID -e ARM_CLIENT_SECRET \
ghcr.io/libre-devops/terraform:1 terraform plan
# PowerShell, with Az and Microsoft.Graph
docker run --rm -it ghcr.io/libre-devops/powershell:lts
# Everything, as an interactive shell, with the Azure CLI login above. Terraform's
# azurerm and azapi can use that login here, since toolbox has the Azure CLI they call.
docker run --rm -it --user "$(id -u):0" -v "$PWD:/work" -v "$HOME/.azure:/home/app/.azure" \
ghcr.io/libre-devops/toolbox:latestPodman images need a few more flags (see Podman in a container), and the CI agents have their own section (Self-hosted CI agents).
Starting points in examples/compose/:
| File | Runs |
|---|---|
toolbox.yaml |
toolbox as a workstation shell in the current directory, with your Azure CLI login; and toolbox:podman, keeping its images in a volume |
agents.yaml |
The three CI agents, one profile each (azure, github, gitlab, and gitlab-podman for a GitLab runner whose jobs build images), with their settings from a .env file (.env.example) |
HOST_UID=$(id -u) docker compose -f examples/compose/toolbox.yaml run --rm toolbox
cp examples/compose/.env.example examples/compose/.env # then fill in a token
docker compose -f examples/compose/agents.yaml --profile gitlab up -d --scale gitlab-runner=3As a container job. The runner mounts the workspace and HOME as uid 1001, so run the job as
that uid in group 0; the images' home, work and tool directories are writable by group 0.
jobs:
plan:
runs-on: ubuntu-26.04
container:
image: ghcr.io/libre-devops/terraform:1
options: --user 1001:0
steps:
- uses: actions/checkout@v7
- run: terraform init -backend=false && terraform validate
- run: tflint --init && tflinttest:
image: ghcr.io/libre-devops/python:3.13
script:
- uv sync --locked
- uv run pytestThe Azure Pipelines agent adds its own user inside a container job, which needs root, so start
the container as root. useradd and groupadd are in every image for this.
resources:
containers:
- container: azure
image: ghcr.io/libre-devops/azure-cli:2.92.0
options: --user 0:0
jobs:
- job: deploy
container: azure
steps:
- script: az versionOr run a single command with docker run, as your own uid so that files written to the
workspace stay yours:
steps:
- script: >-
docker run --rm --user "$(id -u):0" -v "$(Build.SourcesDirectory):/work"
ghcr.io/libre-devops/powershell:lts pwsh -File ./build.ps1terraform init installs azurerm, azapi and msgraph from the image's own mirror, at
/usr/local/share/terraform/providers, and needs no registry for them; any other provider still
comes from the registry. The mirror holds the newest patch of each of the newest three minor
releases of each provider, each at least three days old, and the image tables above list
them. They move forward as new releases appear.
docker run --rm -v "$PWD:/work" ghcr.io/libre-devops/azure-terraform:1 terraform init- Constraints. A configuration whose version constraints allow one of the mirrored
versions, such as
~> 5.12or>= 5.0, installs offline. One that pins a version the mirror lacks needs the registry. - Online, and a version the mirror lacks. Terraform cannot fall back from the mirror to the
registry by itself, so switch to the registry configuration:
TF_CLI_CONFIG_FILE=/usr/local/share/terraform/registry.tfrc. - Lock files. The mirror holds the release zips themselves, so a
.terraform.lock.hclmade online matches them. Terraform reports mirrored providers as "unauthenticated" because it does not check signatures on local files: each zip's checksum was verified against the provider's signed release when it was pinned, and again when the image was built. - Other Terraform versions from a
.terraform-versionstill download on demand; setTENV_AUTO_INSTALL=falseoffline and use the default. - Terraform Stacks.
terraform stacksdownloads its plugin,tfstacks, on first use, and always needs HCP Terraform or your Terraform Enterprise host (TF_STACKS_HOSTNAME). The image does not carry the plugin: its current release (1.4.0) is built with a Go version that has fixable high vulnerabilities, so it fails the scan gate.
azure-cli:functions adds Azure Functions Core Tools
(func) to the Azure CLI, to create, run and publish function apps. Log in with the Azure CLI
as above, then publish from the project's directory:
docker run --rm -it --user "$(id -u):0" -v "$PWD:/work" -v "$HOME/.azure:/home/app/.azure" \
ghcr.io/libre-devops/azure-cli:functions func azure functionapp publish my-function-app- Languages:
funcbrings the Python, Node.js and PowerShell language workers, and runs .NET apps in the isolated worker model. The image has the Azure CLI's Python, 3.12; a Node.js or .NET project needs that runtime or SDK to build and run locally. The Java worker is left out, since running Java functions needs a JDK, which the image does not have. - No in-process .NET hosts. The release's in-process hosts (
in-proc6,in-proc8, about 750 MB, amd64 only) are left out: Microsoft's support for the in-process model ended on 10 November 2026. Move such apps to the isolated worker model. - Size: about 600 MB on top of
azure-cli, which is why it is a flavour rather than in everyazure-clitag,toolboxorcicd-helper.
Mount the playbooks and an SSH key, and run as your own uid so that what Ansible writes stays yours:
docker run --rm --user "$(id -u):0" -v "$PWD:/work" -v "$HOME/.ssh:/home/app/.ssh:ro" \
ghcr.io/libre-devops/ansible:2.22 ansible-playbook -i inventory.ini site.ymlInstall collections per project from a requirements.yml with ansible-galaxy collection install -r requirements.yml; they go to ~/.ansible/collections. Every ansible image has
containers.podman installed for every user, and ansible-azure has
azure.azcollection as well, so authenticate the usual ways
(AZURE_CLIENT_ID and friends, a managed identity, or ~/.azure/credentials). Azure modules
run on localhost, where they need Ansible's own Python, which has their libraries: that is
what Ansible uses for an implicit localhost. If your inventory lists localhost, give it
ansible_python_interpreter: "{{ ansible_playbook_python }}".
ansible:2.16 is for one job only. ansible-core runs Python on every host it manages,
and from 2.17 that must be Python 3.7 or newer. RHEL 8 and its rebuilds ship Python 3.6 as
the system (platform) Python, so the current ansible-core cannot manage them without first
installing a newer Python on each. The 2.16 line still can, and Renovate keeps it on 2.16
patch releases. Use it for those hosts, and the current line for everything else.
Every ansible image has Molecule, with molecule-plugins for scenarios written for its
podman driver. Run molecule test from the root of a role or collection:
# Scenarios that test against hosts you already have (the default driver)
docker run --rm --user "$(id -u):0" -v "$PWD:/work" -v "$HOME/.ssh:/home/app/.ssh:ro" \
ghcr.io/libre-devops/ansible:2.22 molecule test
# Scenarios that test against containers: ansible:podman starts them with its own Podman
docker run --rm --device /dev/fuse --security-opt label=disable \
--security-opt seccomp=unconfined --security-opt apparmor=unconfined \
--security-opt systempaths=unconfined \
-v "$PWD:/work" ghcr.io/libre-devops/ansible:podman molecule test- Containers. Both of Molecule's container layouts work in
ansible:podman: its ansible-native scenarios, whosecreate.ymlanddestroy.ymlcallcontainers.podmanthemselves, and scenarios withdriver: name: podman. Podman runs as uid 10001, so leave out--user, and see Podman in a container for the flags and for Podman on the host. Thedockerdriver needs a Docker daemon, so it does not work here. - The test images need Python for most modules, as Molecule's documentation says. A
minimal image works with
gather_facts: falseandansible.builtin.raw. - Dependencies. A scenario's
dependencystep installs itsrequirements.ymlfrom Galaxy at run time, so it needs the network.containers.podmanis already installed.
Everything the libre_devops roles need to run, in one image, for a CI job or a workstation:
# A playbook that uses the roles, against hosts in an inventory
docker run --rm --user "$(id -u):0" -v "$PWD:/work" -v "$HOME/.ssh:/home/app/.ssh:ro" \
ghcr.io/libre-devops/cicd-helper:latest ansible-playbook -i inventory.ini site.yml- The roles: every role in the
libre_devopsnamespace, at its newest release, installed for every user in/usr/share/ansible/roles, so a play names them directly (roles: [libre_devops.mde_linux]);ansible-galaxy role listshows the versions. The daily Pins run picks up a new role or release by itself, and its pull request merges once Build passes. Build checks that every role'srequirements.ymland dependencies are met, so a role that needs a collection the image lacks stops there, not at run time. - Collections: community.general (on 11.x, which the roles'
requirements.ymlallows), ansible.posix, containers.podman and theforeman.foreman, with the Python libraries their modules need on the controller, andrpmfor uploading RPMs to Satellite. - ansible-core 2.21, not 2.22 as in
ansible: 2.22 needs Python 3.13, and this image is on the Azure CLI's Python, 3.12. It is also the line the roles test against. - pytest runs in Ansible's own virtual environment, so unit tests can import Ansible's
libraries. Molecule is there for scenarios that test against hosts you already have; with no
Podman, use
ansible:podmanfor the roles' container scenarios. - JUnit XML for CI test views:
libre_devops.test_results_reportwrites it from the checks roles' results,pytest --junitxml=report.xmlfrom tests, and Ansible's own callback from any playbook (ANSIBLE_CALLBACKS_ENABLED=ansible.builtin.junit, withJUNIT_OUTPUT_DIR). TFLint (--format junit) and Pester write it too. - Other tools: yq, just (which the roles' own CI runs), yamllint, sshpass (a first login
with a password,
ansible -k), rsync (ansible.posix.synchronize), zip and unzip, with curl, jq, git and the CA tooling every image has. The image's ownpython3has Requests, for scripts. - Terraform installs azurerm, azapi and msgraph from the local mirror, as in azure-terraform, and the Azure CLI is there for azurerm to log in with.
--userns=keep-id maps your user to the image's uid 10001, so files in the mounted directory
are owned by you on both sides:
podman run --rm -it --userns=keep-id:uid=10001,gid=10001 \
-v "$PWD:/work:Z" ghcr.io/libre-devops/terraform:1 terraform fmt -checkThe images run as a non-root numeric uid, so runAsNonRoot: true is satisfied as is. An
arbitrary uid (OpenShift's default) works too, because the writable directories belong to
group 0:
securityContext:
runAsNonRoot: true
runAsUser: 10001
runAsGroup: 10001
allowPrivilegeEscalation: false
capabilities:
drop: ["ALL"]azure-pipelines-agent, github-runner and gitlab-runner set themselves up when the
container starts, from environment variables, and are ephemeral by default: each runs one
job, leaves no registration behind and exits. The toolbox tags
(azure-pipelines-agent:toolbox, github-runner:toolbox, gitlab-runner:toolbox) add
everything in the toolbox image. Run them under something that starts them again:
| Under | A fresh container for every job? |
|---|---|
Kubernetes, as a Deployment (examples/kubernetes/) |
Yes: a restarted container starts from the image |
A systemd unit around docker run --rm (below) |
Yes |
docker run --restart always, or Compose's restart: always (examples/compose/agents.yaml) |
No: the same container restarts, so a job can see what the one before it left in its workspace and HOME. Fine for one team's pool |
Each agent's default name is the image's agent name, the time it started (UTC,
ddmmyyyyhhmmss) and four random hex digits, such as azdo-agent-15112026093012-3f9a: agents
started in the same second, as a scaled Deployment's are, still get different names.
Azure Pipelines. A personal access token with the Agent Pools (Read & manage) scope
registers the agent; AZP_TOKEN_FILE, a mounted secret, keeps it out of the environment.
docker run -d --restart always \
-e AZP_URL=https://dev.azure.com/contoso -e AZP_POOL=containers \
-e AZP_TOKEN_FILE=/run/secrets/azp-token -v "$PWD/azp-token:/run/secrets/azp-token:ro" \
ghcr.io/libre-devops/azure-pipelines-agent:toolbox| Variable | Default | Meaning |
|---|---|---|
AZP_URL |
required | The organisation, such as https://dev.azure.com/contoso |
AZP_TOKEN or AZP_TOKEN_FILE |
required | The token, or a file holding it |
AZP_POOL |
Default |
The agent pool |
AZP_AGENT_NAME |
azdo-agent-<ddmmyyyyhhmmss>-<random> |
The agent's name |
AZP_WORK |
_work |
The work directory, in /opt/azure-pipelines-agent |
AZP_EPHEMERAL |
true |
false keeps the agent running jobs until the container stops |
GitHub Actions. Give the runner a registration token, a token that can create one, or a
just-in-time configuration (the API's generate-jitconfig, the best fit for autoscalers).
docker run -d --restart always \
-e RUNNER_URL=https://github.com/contoso -e RUNNER_ACCESS_TOKEN \
-e RUNNER_LABELS=containers \
ghcr.io/libre-devops/github-runner:toolbox| Variable | Default | Meaning |
|---|---|---|
RUNNER_URL |
required, unless RUNNER_JIT_CONFIG |
https://github.com/<org> or https://github.com/<owner>/<repo>, or the same on GitHub Enterprise Server |
RUNNER_TOKEN |
A registration token | |
RUNNER_ACCESS_TOKEN |
Creates registration tokens itself: a GitHub App installation token or a fine-grained token with Administration write (repository) or Self-hosted runners write (organisation) | |
RUNNER_JIT_CONFIG |
A just-in-time configuration; nothing else is needed | |
RUNNER_NAME |
github-runner-<ddmmyyyyhhmmss>-<random> |
The runner's name |
RUNNER_LABELS |
Extra labels, comma-separated, on top of self-hosted, linux and the architecture |
|
RUNNER_GROUP |
The runner group | |
RUNNER_WORKDIR |
_work |
The work directory, in /opt/actions-runner |
RUNNER_EPHEMERAL |
true |
false keeps the runner running jobs until the container stops |
GitLab. Create the runner in GitLab first (Settings > CI/CD > Runners on a project or
group, the Admin area for an instance runner, or the API), with its tags, and give the
container its authentication token (glrt-...). One token serves any number of containers:
each shows in GitLab as one of the runner's managers. Jobs run with the shell executor, in the
container itself.
docker run -d --restart always \
-e GITLAB_URL=https://gitlab.com \
-e GITLAB_RUNNER_TOKEN_FILE=/run/secrets/glrt -v "$PWD/glrt:/run/secrets/glrt:ro" \
ghcr.io/libre-devops/gitlab-runner:toolbox| Variable | Default | Meaning |
|---|---|---|
GITLAB_URL |
required | The GitLab instance, such as https://gitlab.com |
GITLAB_RUNNER_TOKEN or GITLAB_RUNNER_TOKEN_FILE |
required | The runner's authentication token, or a file holding it |
GITLAB_RUNNER_NAME |
gitlab-runner-<ddmmyyyyhhmmss>-<random> |
The name in job logs |
GITLAB_RUNNER_EPHEMERAL |
true |
false keeps the runner running jobs until the container stops |
GitLab Runner's own RUNNER_* variables set anything else run-single takes, such as
RUNNER_SHELL=pwsh (on the toolbox tags). Builds and the cache go in /opt/gitlab-runner.
Jobs reach the runner through the tags you gave it (or untagged, if you allowed that), and run with everything in its image:
plan:
tags: [containers]
script:
- terraform init
- terraform planTo create runners from automation, POST /api/v4/user/runners (with a token that has the
create_runner scope; for example runner_type=group_type, group_id and
tag_list=containers) returns the new runner's glrt- token.
Things to know:
- Updates come as images. No agent updates itself. Renovate bumps them and a release follows, so keep pulling the moving tags: GitHub stops sending jobs to a runner 30 days after a newer release.
- Jobs run as the agent's user, so a job can read any credential the agent holds. Scope the tokens as above and nothing more.
- No npm in the agents' own Node. The Azure and GitHub agents run tasks with Node
runtimes they bundle, and those come without npm, npx and corepack, which the agents never
use and whose dependencies carry known vulnerabilities. A job that needs npm installs Node
itself (
actions/setup-node, or theNodeTooltask). - Building images in jobs. The
toolbox-podmantags add rootless Podman and adockercommand that runs it, so jobs can build, run and push images; start the agent with the flags in Podman in a container. Container jobs and service containers, which the agents run through a Docker daemon, are not supported. - GitLab jobs run in the runner's container (the shell executor), with every tool in its
image. A job's
image:andservices:keywords are ignored: they ask GitLab to start a separate container for the job, or a sidecar such as a database, which only GitLab's Docker and Kubernetes executors do. A job that needs containers of its own can run them itself with Podman, on thetoolbox-podmantag. For each job in an image of its own choosing, run GitLab's own runner with one of those executors, and use these images as the jobs'image:. - glibc only for the GitHub runner. GitHub publishes no musl build, so there is no Alpine flavour.
A systemd template unit runs each agent as docker run --rm, so every job gets a new container
from the image. --pull always picks up a new release of the moving tag on the next job. For
GitLab:
# /etc/systemd/system/gitlab-runner@.service
[Unit]
Description=GitLab Runner %i
After=docker.service
Requires=docker.service
[Service]
# GITLAB_URL=... and GITLAB_RUNNER_TOKEN=..., in a file only root can read.
EnvironmentFile=/etc/gitlab-runner.env
ExecStartPre=-/usr/bin/docker rm -f gitlab-runner-%i
ExecStart=/usr/bin/docker run --rm --pull always --name gitlab-runner-%i \
-e GITLAB_URL -e GITLAB_RUNNER_TOKEN ghcr.io/libre-devops/gitlab-runner:toolbox
Restart=always
[Install]
WantedBy=multi-user.targetsudo systemctl daemon-reload
sudo systemctl enable --now gitlab-runner@1 gitlab-runner@2 gitlab-runner@3The same unit runs the other agents with their own image and variables (-e AZP_URL -e AZP_TOKEN -e AZP_POOL, or -e RUNNER_URL -e RUNNER_ACCESS_TOKEN -e RUNNER_LABELS).
Build, run and push images inside a CI job or a pod, with no Docker daemon, no Docker socket
and, on hosts that allow user namespaces, no --privileged. Podman runs rootless, as the
image's app user (uid 10001), inside the container.
| Image | Use it for |
|---|---|
podman:5 |
Podman on its own, with a docker command that runs it |
azure-cli:podman, terraform:podman, toolbox:podman |
The image's tools, plus Podman |
ansible:podman |
Molecule scenarios that test against containers (see Molecule) |
azure-pipelines-agent:toolbox-podman, github-runner:toolbox-podman, gitlab-runner:toolbox-podman |
Self-hosted agents whose jobs build images |
Every one of them is tested on every pull request the same way: inside the container, as uid
10001, Podman pulls and runs an image, builds a new one, and runs that. ansible:podman also
runs a Molecule scenario against a container it starts.
| Where it runs | Start it with |
|---|---|
| Podman | --device /dev/fuse, and on SELinux hosts (RHEL, Fedora) --security-opt label=disable |
| Docker | --device /dev/fuse --security-opt seccomp=unconfined --security-opt apparmor=unconfined --security-opt systempaths=unconfined, and --security-opt label=disable on SELinux hosts |
| Kubernetes | /dev/fuse and user namespaces: privileged: true, or a pod in its own user namespace with a device plugin for /dev/fuse (see Kubernetes) |
Also:
- Run as uid 10001. Rootless Podman needs the user's subordinate ids, which
apphas. An arbitrary uid, such as OpenShift's, has none. - Ubuntu 23.10 and later hosts keep unprivileged user namespaces from processes without an
AppArmor profile, which includes Podman in a container. Allow them on the host:
sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0(or persist it in/etc/sysctl.d/). - Image storage. Podman keeps images in
/home/app/.local/share/containers. Mount a volume there to keep them between runs, or to keep them off the container's own filesystem, asexamples/compose/toolbox.yamldoes.
On a workstation or a build host:
# Podman on the host
podman run --rm --device /dev/fuse --security-opt label=disable \
-v "$PWD:/work" ghcr.io/libre-devops/podman:5 \
podman build -t registry.example.com/team/app:1 .
# Docker on the host
docker run --rm --device /dev/fuse --security-opt label=disable \
--security-opt seccomp=unconfined --security-opt apparmor=unconfined \
--security-opt systempaths=unconfined \
-v "$PWD:/work" ghcr.io/libre-devops/toolbox:podman \
podman build -t registry.example.com/team/app:1 .GitHub Actions, on a GitHub-hosted runner (Ubuntu, so allow user namespaces first). The job
needs permissions: packages: write to push to GHCR:
steps:
- uses: actions/checkout@v7
- run: sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0
- env:
TOKEN: ${{ secrets.GITHUB_TOKEN }}
IMAGE: ghcr.io/example/app:${{ github.sha }}
run: >-
docker run --rm --device /dev/fuse --security-opt label=disable
--security-opt seccomp=unconfined --security-opt apparmor=unconfined
--security-opt systempaths=unconfined
-v "$PWD:/work" -e TOKEN -e IMAGE ghcr.io/libre-devops/podman:5
bash -c 'echo "$TOKEN" | podman login ghcr.io -u token --password-stdin &&
podman build -t "$IMAGE" . && podman push "$IMAGE"'A self-hosted Azure Pipelines agent whose jobs can build images (see Self-hosted CI agents for its settings):
docker run -d --restart always --device /dev/fuse --security-opt label=disable \
--security-opt seccomp=unconfined --security-opt apparmor=unconfined \
--security-opt systempaths=unconfined \
-e AZP_URL=https://dev.azure.com/contoso -e AZP_POOL=containers \
-e AZP_TOKEN_FILE=/run/secrets/azp-token -v "$PWD/azp-token:/run/secrets/azp-token:ro" \
ghcr.io/libre-devops/azure-pipelines-agent:toolbox-podmanJobs then run podman build, or docker build, as plain script steps.
Three manifests in examples/kubernetes/, each checked against the
Kubernetes 1.33 and 1.34 API schemas:
| File | What it is |
|---|---|
podman-build-job.yaml |
A Job that clones a repository, builds and pushes, privileged: works on most clusters |
podman-build-job-user-namespaces.yaml |
The same Job without privileged, in the pod's own user namespace (hostUsers: false, Kubernetes 1.33 and later) with /dev/fuse from a device plugin |
azure-pipelines-agent-podman.yaml |
A Deployment of ephemeral Azure Pipelines agents whose jobs can build images |
The core of the first:
spec:
template:
spec:
restartPolicy: Never
securityContext:
runAsNonRoot: true
runAsUser: 10001
runAsGroup: 10001
containers:
- name: build
image: ghcr.io/libre-devops/podman:5
command: ["bash", "-c", "git clone --depth 1 \"$REPOSITORY\" /work/src && podman build -t \"$IMAGE\" /work/src && podman push \"$IMAGE\""]
env:
- name: REGISTRY_AUTH_FILE
value: /run/secrets/registry/auth.json
securityContext:
privileged: true
runAsNonRoot: true
runAsUser: 10001
runAsGroup: 10001
volumeMounts:
- name: containers
mountPath: /home/app/.local/share/containersprivileged is what most clusters need: it gives the container /dev/fuse and lets Podman
create its user namespace. Podman still runs as uid 10001 inside it. Where the cluster runs pods
in their own user namespace, the second manifest removes privileged: the pod's root then maps
to an unprivileged user on the node. Pod Security Admission's restricted and baseline
levels reject both, so run them in a namespace labelled privileged.
- Works:
podman build,run,push,pull,loginandsave; multi-stage builds;docker buildand the otherdockercommands, through thedockercommand that runs Podman. - Network: nested containers share the outer container's network, so builds reach whatever the job can reach.
- Does not work: tools that talk to a Docker daemon over its socket (Testcontainers,
docker-compose against
/var/run/docker.sock), and the CI agents' container jobs and service containers, which need a real Docker daemon.
apphas subordinate uids and gids 1 to 65535 apart from its own, which fits inside the 65536 ids a rootless outer container usually maps.newuidmapandnewgidmapcarry file capabilities instead of the setuid bit. A setuidnewuidmapcannot write a nested container's id map; this is what Red Hat'squay.io/podman/stabledoes too.- Storage goes through fuse-overlayfs, since the kernel's overlay cannot mount over the outer container's own overlay. Newer Buildah overlays the build context as well.
- Nested containers share the outer container's namespaces and need no cgroups
(
/etc/containers/containers.conf), and builds isolateRUNsteps with chroot (BUILDAH_ISOLATION=chroot): a container cannot create most namespaces of its own. The exception is the UTS namespace, so a nested container can have its own hostname, as Molecule's test containers do.
| Path | Purpose | Writable by |
|---|---|---|
/home/app |
HOME for every user the image runs as |
app, and any uid in group 0 |
/work |
Working directory; mount your project here | app, and any uid in group 0 |
/opt/az |
The Azure CLI's virtual environment (azure-cli, toolbox, cicd-helper) |
root |
/opt/azure-functions-core-tools |
Azure Functions Core Tools (azure-cli:functions) |
root |
/opt/ldo-cli |
ldo-cli's virtual environment (azure-cli, toolbox) |
root |
/opt/microsoft/powershell/7 |
PowerShell (powershell, toolbox, cicd-helper) |
root |
/usr/local/share/powershell/Modules |
Pinned PowerShell modules, for all users | root |
/home/app/.tenv |
tenv's Terraform installs (TENV_ROOT) |
app, and any uid in group 0 |
/opt/ansible |
Ansible's virtual environment (ansible, ansible-azure, cicd-helper) |
root |
/usr/share/ansible/roles |
Galaxy roles for every user (cicd-helper) |
root |
/usr/local/share/terraform |
The provider mirror and the two CLI configurations (azure-terraform, cicd-helper) |
root |
/usr/share/ansible/collections |
Collections for every user: containers.podman (every ansible image), azure.azcollection (ansible-azure), and the roles' collections (cicd-helper) |
root |
/opt/azure-pipelines-agent, /opt/actions-runner, /opt/gitlab-runner |
The agents, their registration and their work (azure-pipelines-agent, github-runner, gitlab-runner) |
app, and any uid in group 0 |
Set by the images; override any of them with -e or your CI system's environment settings.
| Variable | Value | Image | Effect |
|---|---|---|---|
HOME |
/home/app |
all | Consistent home for any uid |
REQUESTS_CA_BUNDLE |
/etc/ssl/certs/ca-certificates.crt |
all | Python requests (and the Azure CLI) use the system trust store |
NODE_EXTRA_CA_CERTS |
/etc/ssl/certs/ca-certificates.crt |
all | Node.js, which the CI agents run tasks with, trusts the system store too |
UV_NATIVE_TLS |
true |
all | uv uses the system trust store rather than its own |
LANG |
C.UTF-8 |
ansible, ansible-azure, cicd-helper |
ansible-core refuses to run without a UTF-8 locale |
BUILDAH_ISOLATION |
chroot |
podman, -podman flavours |
podman build isolates RUN steps with chroot, which works inside a container |
TF_CLI_CONFIG_FILE |
/usr/local/share/terraform/airgapped.tfrc |
azure-terraform, cicd-helper |
Mirrored providers install from the mirror; registry.tfrc uses the registry for everything |
PYTHONUNBUFFERED |
1 |
python, azure-cli, toolbox, cicd-helper |
Unbuffered output in CI logs |
AZURE_CORE_COLLECT_TELEMETRY |
no |
azure-cli, toolbox, cicd-helper |
No Azure CLI telemetry |
FUNCTIONS_CORE_TOOLS_TELEMETRY_OPTOUT |
1 |
azure-cli |
No Azure Functions Core Tools telemetry |
TENV_ROOT |
/home/app/.tenv |
terraform, toolbox, cicd-helper |
Where tenv keeps Terraform versions |
TENV_AUTO_INSTALL |
true |
terraform, toolbox, cicd-helper |
A .terraform-version installs on demand; set false offline |
CHECKPOINT_DISABLE |
1 |
terraform, toolbox, cicd-helper |
No HashiCorp update checks |
POWERSHELL_TELEMETRY_OPTOUT |
1 |
powershell, toolbox, cicd-helper |
No PowerShell telemetry |
POWERSHELL_UPDATECHECK |
Off |
powershell, toolbox, cicd-helper |
No update notices |
DOTNET_CLI_TELEMETRY_OPTOUT, DOTNET_NOLOGO |
1 |
powershell, toolbox, cicd-helper |
No .NET telemetry or banners |
git trusts every directory (safe.directory = * in the system configuration), because CI
systems mount workspaces owned by other uids.
Networks with TLS inspection need their root CA in the image. Build a thin layer FROM a
pinned digest of these images, add the certificate with add-ca-certificates, and switch
back to the app user:
FROM ghcr.io/libre-devops/azure-cli:2.92.0@sha256:<digest>
USER root
COPY organisation-root-ca.pem /tmp/organisation-root-ca.pem
RUN add-ca-certificates /tmp/organisation-root-ca.pem && rm /tmp/organisation-root-ca.pem
USER 10001:10001That is all. add-ca-certificates works on every base (Debian, Alpine, RHEL and Wolfi), takes
files holding one or several PEM certificates, and adds them to the system trust store, which
every tool in the images uses:
| Tool | Trusts the system store through |
|---|---|
| curl, git, Terraform and the Go tools, PowerShell and .NET | The operating system's TLS libraries |
| The Azure CLI, ldo-cli and Ansible | pip-system-certs, installed in each of their virtual environments |
Python requests in your own environments |
REQUESTS_CA_BUNDLE |
| pip | Its built-in use of the system store (pip 24.2 and later) |
| uv | UV_NATIVE_TLS=true |
| Node.js, and the CI agents' tasks | NODE_EXTRA_CA_CERTS |
The system bundle is /etc/ssl/certs/ca-certificates.crt on every base (a link to
/etc/pki/tls/certs/ca-bundle.crt on RHEL). Every pull request proves all of the above: the
smoke tests add a throwaway CA and check each client against a server it signed.
Moving tags (3.12, 1, latest) follow each rebuild. If you cannot refresh a tag you
already pulled, or need a build to be reproducible, pin a date tag, which is never
overwritten, or a digest, which is the same in GHCR and Docker Hub:
ghcr.io/libre-devops/python:3.12-20261107
docker.io/libredevops/python@sha256:<digest>
Renovate and Dependabot both update digest pins in your own repositories.
The newest digest of every version, as of the last release:
| Image | Version | Newest date tag | Digest | Released |
|---|---|---|---|---|
python |
3.12 |
3.12-20261120 |
sha256:e804bfd87c98cc96a5f079ff45d8c6d847c8c0e160379692cdf2d7bfc46694d0 |
2026-11-20 |
python |
3.13 |
3.13-20261120 |
sha256:da206df1dbcde016cf91df7226a2d942239241e64a3558491abe584673baf7a6 |
2026-11-20 |
python |
3.14 |
3.14-20261120 |
sha256:15f38d4fe383502daebdaae631ae5a512c6d9be9b7043f5e3677f22ecf309d01 |
2026-11-20 |
python |
3.15 |
3.15-20261120 |
sha256:857a935a0fadc61b23ff0ef20a4e169cd26961f4460c47a279d5ebc7e32e4869 |
2026-11-20 |
podman |
5 |
5-20261120 |
sha256:bc2ba69cf645296a29042c04e83d60b691d6afab462e28a4fe80df5def3e3b0b |
2026-11-20 |
azure-cli |
2.92.0 |
2.92.0-py3.12-20261120 |
sha256:03e14ecddb9936500c6d9a629ce924334bd34d6ffc81242fdf8a3f50ae7de629 |
2026-11-20 |
azure-cli |
2.92.0-podman |
2.92.0-py3.12-podman-20261120 |
sha256:14f2ba503c7e3dd0f8f6ccec558fd8094720c219dac549f25484e8af33dcf124 |
2026-11-20 |
azure-cli |
2.92.0-functions |
2.92.0-py3.12-functions-20261120 |
sha256:c26d84aa617c198a92fcb365acbcffa0cbed8420b409f4796aa497c5a80acfb0 |
2026-11-20 |
azure-cli |
2.72.0 |
2.72.0-py3.12-20261120 |
sha256:22ead65935f155be3882e6a76fd281d72afba0e969a7675e4a46a795507f574f |
2026-11-20 |
terraform |
1.17.2 |
1.17.2-20261120 |
sha256:a20998b56e0eb544d85a8b694ccc9d8b55e0825e6a576b2c2737be4c985d20da |
2026-11-20 |
terraform |
1.17.2-alpine |
1.17.2-alpine-20261120 |
sha256:3b0d4af5a381562315844766014d8affc54e8ecb424043e4b18a4b9046136dff |
2026-11-20 |
terraform |
1.17.2-podman |
1.17.2-podman-20261120 |
sha256:7b08196757c8b26316d11b563b5ea01f9960fc37edd6398cf848091ab07faee0 |
2026-11-20 |
ansible |
2.22.0 |
2.22.0-py3.14-20261120 |
sha256:d9f8191511be0c8fefc57c34b3c026de9177d51b220031fe65068b30faf1a5d2 |
2026-11-20 |
ansible |
2.22.0-podman |
2.22.0-py3.14-podman-20261120 |
sha256:67578ed77adda1763e4beb0a2254a686159018475a57bab1001f74798fc6ffad |
2026-11-20 |
ansible |
2.16.20 |
2.16.20-py3.12-20261120 |
sha256:27ec74400617d660009b31dae85072d21885551fb1e43dfcdf698c1f05cb5837 |
2026-11-20 |
ansible-azure |
4.2.0 |
4.2.0-20261120 |
sha256:10906e9ce0b26a8a2b413b9fa033fe4b05a890f28c49aea135037c29aa21c73f |
2026-11-20 |
azure-terraform |
1.17.2 |
1.17.2-20261120 |
sha256:067498164195695fb7524425cba234bd78e36ed0853703178e98f4969e983741 |
2026-11-20 |
powershell |
7.6.10 |
7.6.10-20261120 |
sha256:adf24011028fc191464229d6ff350be9e18404ad22bc1dc46ca5ae76c5e127ae |
2026-11-20 |
toolbox |
1 |
1-20261120 |
sha256:75dc20ccbf10c9241425cad593d20d8e49f81bce035dfe87b3b250a1ad463252 |
2026-11-20 |
toolbox |
1-podman |
1-podman-20261120 |
sha256:a89c47f63532c098fc4caef8415459eb8faf72068e79e4c0e3e11e39d133afa6 |
2026-11-20 |
cicd-helper |
2.21.6 |
2.21.6-py3.12-20261120 |
sha256:7b8f82b7d8fb90110c28ed584955436e652c2163fafd36c5c487e41551cddcba |
2026-11-20 |
azure-pipelines-agent |
5.282.0 |
5.282.0-20261120 |
sha256:8130205fae7e75cfc37ef3e59cfba4791303df2db515857a522f0ad1b073e40c |
2026-11-20 |
azure-pipelines-agent |
5.282.0-toolbox |
5.282.0-toolbox-20261120 |
sha256:646ba09abfa73e1decf70ae20a3f5af8d6c91b418ad82b0cc7fa9f5ad0f66c23 |
2026-11-20 |
azure-pipelines-agent |
5.282.0-toolbox-podman |
5.282.0-toolbox-podman-20261120 |
sha256:19134773df5a0a6366339a6a7668be3a25b862554fbf4fd1bca5d6db072b28f8 |
2026-11-20 |
github-runner |
2.338.2 |
2.338.2-20261120 |
sha256:52a8aa220689a01d7dc71adb67043b14c51c3b3441836a3d201feab3c6829601 |
2026-11-20 |
github-runner |
2.338.2-toolbox |
2.338.2-toolbox-20261120 |
sha256:dcea175f8d01f62fb3d0947206c9b6b70b507508ffa75d5e9199e33f7677497a |
2026-11-20 |
github-runner |
2.338.2-toolbox-podman |
2.338.2-toolbox-podman-20261120 |
sha256:718cfe05b1f1c250c8f720ef3cf64014bafbdad2150abf12972d2616d73fba21 |
2026-11-20 |
gitlab-runner |
19.5.3 |
19.5.3-20261120 |
sha256:3d9f808129e4e504bb289aec91201516407166a1adefefeeaf24bdfd5f3a4e4c |
2026-11-20 |
gitlab-runner |
19.5.3-toolbox |
19.5.3-toolbox-20261120 |
sha256:becbb9a9164c6cf247fc8cbb8b56b07e5e8bafb916705c1a3af7942349f8ea5f |
2026-11-20 |
gitlab-runner |
19.5.3-toolbox-podman |
19.5.3-toolbox-podman-20261120 |
sha256:f596970c9c56919a55c8c3f02c13c7c893a99dc597717f8eeca168b89b6945ae |
2026-11-20 |
Security problems are found as early as possible and fixed at the source.
flowchart LR
subgraph pr["Every pull request"]
check["Validate pins, lint, zizmor, actionlint, Trivy repository scan"] --> build["Build every version, amd64 and arm64"]
build --> test["Smoke tests"] --> gate["Trivy gate"]
end
subgraph fortnight["Every two weeks"]
port["Portability: build and smoke test on UBI, Wolfi and Alpine bases"]
end
subgraph release["Release: merges, Mondays, on demand"]
push["Build once per platform, push by digest"] --> verify["Smoke test and scan that digest"]
verify --> tag["Tag GHCR and Docker Hub from one manifest"] --> sign["Check digests match, sign with cosign"]
end
subgraph daily["Every day"]
pins["Pins: base digests, OSV patches, Python locks"] --> prs["Pull request, built, tested, merged"]
scan["Scan every published image"] --> tab["Security tab"]
end
gate --> push
prs --> push
scan -- "fails the gate" --> push
- Before anything is built. Every pull request lints the workflows for security problems with zizmor (template injection, excessive permissions, persisted credentials, unpinned actions) and for correctness with actionlint, scans the repository for secrets and misconfigurations with Trivy, and lints the Containerfile and every script.
- Least privilege in CI. Every workflow starts from
permissions: {}and grants each job only what it needs. Every action is pinned by commit SHA. No checkout persists credentials. - Go tools built from source. shfmt, tenv, TFLint, terraform-docs and Conftest are built
with the pinned, current Go rather than downloaded, so they carry no old toolchain's
vulnerabilities.
just lockchecks every dependency of each against OSV and records the fixed version of any that is vulnerable; the build raises it, never lowering anything. Sources and dependencies are verified against the Go checksum database. - Python dependencies hash-locked and patched. The Azure CLI and ldo-cli install from
locks in
images/locks/that pin every package by version and SHA-256, with any package OSV knows to be vulnerable raised to a fixed version. - Scanning before publishing. Trivy scans every image on every pull request and scans the exact pushed digest on every release. A critical finding, or a high one with a fix available, fails the build and nothing is tagged.
- Scanning after publishing. Every day, the Scan workflow rescans every published image, reports every finding in the repository's Security tab, and starts a rebuild if a published image fails the gate.
- Fixes as soon as they exist. Every day, the Pins workflow re-resolves the base images, re-audits every pinned dependency and opens a pull request with any fix, which merges itself and releases once Build passes. Renovate raises security updates immediately, outside its weekly schedule, and merges any update but a major one once its checks pass.
A finding is resolved by removing it: a newer base, a patched dependency, or a newer tool. Where a scanner reports something that does not apply, it is set aside only by a VEX statement that says why:
| Source | What it covers |
|---|---|
| The base image's publisher | Docker Hardened Images attach signed OpenVEX statements to every image, recording packages they have patched in place or that are not affected. The scan applies the statements attached to the pinned base digest, and no others. |
This repository, vex/libre-devops.openvex.json |
Findings examined here and shown not to apply, each with its justification. Reviewed in pull requests like any other change. |
Time-boxed exceptions go in .trivyignore.yaml with a reason and an
expiry date, after which the finding fails the gate again. In force:
| Findings | Where | Why accepted | Expires |
|---|---|---|---|
| CVE-2026-84008 in System.Security.Cryptography.Pkcs 9.0.10 | The Azure Pipelines agent's bundled .NET libraries (azure-pipelines-agent) |
Only Microsoft can update it, in an agent release; this finding applies | 2026-12-13 |
| CVE-2026-114149 in Microsoft.AspNetCore.WebUtilities 8.0.25 | The GitHub Actions runner's bundled libraries (github-runner) |
Only GitHub can update it, in a runner release; this finding applies | 2026-12-13 |
| CVE-2026-116587 in go-jose 4.1.4, CVE-2026-78661 and CVE-2026-78669 in golang.org/x/net 0.58.0 | The Go modules built into GitLab Runner 19.5.3 (gitlab-runner) |
Only GitLab can rebuild it; its main branch has both fixes, for 19.6; these findings apply | 2026-12-13 |
| CVE-2026-84008 in System.Security.Cryptography.Pkcs; CVE-2026-96222, CVE-2026-96958, CVE-2026-96959 and CVE-2026-96960 in System.Security.Cryptography.Xml | The PowerShell language worker that Azure Functions Core Tools 4.16.1 bundles (azure-cli:functions) |
Only Microsoft can update it, in a Core Tools release; these findings apply | 2026-12-16 |
Renovate brings in each agent and Core Tools release as it appears; an exception whose finding is gone has no effect, and is removed.
Every published digest is signed by the Release workflow on main, in both registries, and
carries an SBOM and SLSA provenance as attestations. The signature covers the image index, and
with it the attestations it references.
# Signature
cosign verify ghcr.io/libre-devops/python:3.13 \
--certificate-identity https://github.com/libre-devops/container-images/.github/workflows/release.yml@refs/heads/main \
--certificate-oidc-issuer https://token.actions.githubusercontent.com
# SBOM and provenance
docker buildx imagetools inspect ghcr.io/libre-devops/python:3.13 --format '{{ json .SBOM }}'
docker buildx imagetools inspect ghcr.io/libre-devops/python:3.13 --format '{{ json .Provenance }}'
# The same digest in both registries
for r in ghcr.io/libre-devops docker.io/libredevops; do
docker buildx imagetools inspect "$r/python:3.13" --format '{{ json .Manifest }}' | jq -r .digest
doneTo report a vulnerability, see SECURITY.md.
Everything in the images comes from the distribution's packages or a pinned upstream release, except what is listed here. Each is built from its latest signed or checksummed release, which Renovate bumps, because the packaged version lags behind a security fix; each goes back to the package once that catches up.
| What | Images | Why | Back to the package when |
|---|---|---|---|
OpenSSH client (ssh, scp, sftp, ssh-keygen and friends), from its signed release |
ansible, ansible-azure |
Debian 13's openssh-client lacked the fix for CVE-2026-60002 (critical, fixed in OpenSSH 10.4) on 2026-11-13 |
The base's openssh-client passes the scan gate: use os_packages: [ssh] and remove the openssh stage |
| shfmt, tenv, TFLint, terraform-docs, Conftest | all, terraform, toolbox |
Built with the current Go and patched dependencies by design, not as a stopgap (see Controls) | Not planned |
The published images build on Docker Hardened Images, but nothing in the build depends on that. A base needs only:
- glibc or musl. On musl (Alpine), uv and PowerShell use their musl builds and everything
else is a static binary, so every image builds, with one exception: Microsoft publishes no
musl build of PowerShell for arm64, so
powershellandtoolboxare amd64 only on musl, - a POSIX shell at
/bin/sh, - one of
apt-get,dnf,microdnforapk.
Every image is a target in one multi-stage images/Containerfile.
Package installs go through images/common/os-packages.sh, which maps logical names to each
package manager's; the user is created by writing the account files directly; tools are pinned
downloads or built from source; and if the base lacks the requested CPython, uv installs it.
The CPython uv installs comes without the pip it bundles, whose vendored libraries lag behind
their security fixes: use uv pip, and virtual environments get a current pip of their own.
To build on another base locally, name a key from versions.yml or give a full reference:
just test terraform "" rhel-minimal
just build python 3.13 registry.access.redhat.com/ubi10/ubi:10.1@sha256:<digest>To publish on another base, change the entries under bases in versions.yml and run
just pin. To publish an extra variant on another base, as the -alpine tags are, add a
version line with a flavour (see versions.yml). The portability bases (UBI 10, UBI 10
minimal, Wolfi and Docker Hardened Images Alpine) are built and smoke tested every two weeks
by the Portability workflow, and on demand, so either edit stays safe: start it by hand
before a change of base. If a hardened variant you need does not exist,
docker.io/library/debian:13-slim, pinned by digest, is a drop-in fallback.
| Symptom | Cause | Fix |
|---|---|---|
Permission denied writing to the workspace in a GitHub Actions container job |
The runner's workspace belongs to uid 1001 | Add options: --user 1001:0 to the container |
| Files created in a mounted directory are owned by uid 10001 on the host | The container ran as app |
docker run --user "$(id -u):0", or podman run --userns=keep-id:uid=10001,gid=10001 |
certificate verify failed or self-signed certificate in certificate chain |
TLS inspection with a CA the image does not trust | Add your organisation's CA bundle |
A .terraform-version fails to install in a network without internet access |
tenv downloads it from HashiCorp | Use the default Terraform with TENV_AUTO_INSTALL=false, or point tenv at an internal mirror |
toomanyrequests pulling from Docker Hub |
Docker Hub's anonymous pull limits | Pull the same digest from ghcr.io/libre-devops |
| A container job in Azure Pipelines fails before the first step | The agent could not add its user | Start the container as root: options: --user 0:0 |
An -alpine image fails as an Azure Pipelines container job |
The agent's Node.js needs glibc, and Alpine uses musl | Use the Debian tags (the ones without -alpine) |
Import-Module Az is slow |
Az loads every service module | Import only what you use, for example Import-Module Az.Accounts, Az.Resources |
Import-Module Microsoft.Graph is slow |
It loads about forty modules | Import only what you use, for example Import-Module Microsoft.Graph.Users |
azure-terraform: Failed to query available provider packages or no available releases match for azurerm, azapi or msgraph |
The constraints exclude every mirrored version | Loosen the constraint, or use the registry: TF_CLI_CONFIG_FILE=/usr/local/share/terraform/registry.tfrc |
| Ansible fails on a RHEL 8 host with a Python version error | ansible-core 2.17 and later need Python 3.7 or newer on the host | Use ansible:2.16 for those hosts |
crun: mount proc to proc: Operation not permitted from Podman in a container |
Docker masks parts of /proc, and the kernel then refuses nested containers their own |
Add --security-opt systempaths=unconfined (Docker) or --security-opt unmask=ALL (Podman) |
newuidmap: write to uid_map failed or cannot set up namespace from Podman in a container |
User namespaces are blocked: Docker's seccomp or AppArmor profile, or Ubuntu's apparmor_restrict_unprivileged_userns |
Start the container with the flags in Podman in a container, and on Ubuntu hosts set the sysctl there |
fuse: device not found from Podman in a container |
No /dev/fuse |
Add --device /dev/fuse |
| A self-hosted runner gets no jobs | GitHub stops sending jobs to a runner 30 days after a newer release | Pull the moving tag again; new runner versions are released automatically |
You need Docker or Podman, just and uv.
just tools installs the pinned linters and Trivy into .tools.
| Recipe | Does |
|---|---|
just build <image> [version] [base] |
Build for this machine, with CI's build arguments (a flavour is a version: just build terraform 1.17.1-alpine) |
just test <image> [version] [base] |
Build, then run the smoke tests |
just scan <image> [version] [base] |
Build, then scan with the release gate |
just docs / just docs-check |
Write README.md, or fail if it is out of date |
just lock |
Pin new downloads and patch known vulnerabilities |
just pin |
Re-resolve every base image tag to its current digest |
just validate |
Check versions.yml, the lock and the base pins |
just lint |
hadolint, ShellCheck, shfmt, actionlint, zizmor, Trivy and the text rules |
just snapshot <dir> |
Record every package and tag in both registries |
| Workflow | Runs on | Does | Publishes |
|---|---|---|---|
| Build | Every pull request; started by Pins and Release; pushes to main (the check only) |
Check, build every version for both platforms, smoke test, scan; merge the pull requests Pins and Release open, once they pass | No |
| Release | Merges to main that change the images, not only docs or workflows (Build starts it after merging the pins refresh), Mondays 03:00 UTC, on demand, and Scan |
Build once per platform, test and scan the pushed digest, tag both registries, sign, open a pull request with the new digests | Yes |
| Pins | Pull requests that change versions.yml; daily 02:00 UTC |
Repin and patch on the branch and re-run Build; daily, refresh base digests and patches as a pull request, and re-run Build on it | No |
| Scan | Daily 06:00 UTC | Rescan every published image, report to the Security tab, rebuild if needed | No |
| Portability | The 1st and 15th of each month, 04:00 UTC; on demand | Build the latest version of each image on the portability bases and smoke test it | No |
| Retry | A Build, Release, Pins, Scan or Portability run that fails | Re-run its failed jobs once, so a flaky registry or network heals by itself; a second failure stands | No |
Add one line under the image's versions in versions.yml (and, for a new CPython, a line
under bases), then run just lock pin docs, or push the branch and let the Pins workflow do
it. The CI matrix, tags, tests and README follow from versions.yml.
| Pin | Lives in | Kept current by |
|---|---|---|
| Tool and image versions | versions.yml |
Renovate: weekly, and at once for a security fix |
| SHA-256 of every download, per platform | versions.lock.json |
The Pins workflow, on every pull request branch in this repository that changes versions.yml |
| Fixed versions of vulnerable Go dependencies | versions.lock.json |
The Pins workflow, on those branches and every day |
| Hash-locked Python dependencies | images/locks/ |
The Pins workflow, on those branches and every day |
| Base image digests | versions.yml |
The Pins workflow, every day, as a pull request that merges itself once Build passes |
Terraform providers in azure-terraform |
versions.yml (terraform_providers), and their SHA-256 in versions.lock.json |
The Pins workflow, every day: the newest three minor releases, each pinned once its signed checksums verify |
Galaxy roles in cicd-helper |
versions.yml (ansible_roles), and the SHA-256 of each release's archive in versions.lock.json |
The Pins workflow, every day: every role in the namespace, at its newest release |
| GitHub Actions | the workflows, by commit SHA | Renovate |
A download pin, once written, is never re-fetched: an upstream asset that changes after it was
pinned fails the build rather than being trusted. Vulnerability patches, by contrast, are
recomputed on every run, so a newly published advisory is acted on the next day. Because a
push made with GITHUB_TOKEN does not trigger workflows, the Pins workflow starts the Build
workflow on the commit it pushes.
versions.yml The single source: images, versions, tags, bases
versions.lock.json Generated: download SHA-256s, Go dependency fixes, Python locks
releases.json Generated by releases: the newest digest of every version
images/Containerfile One multi-stage build; every image is a target
images/common/ Distribution-neutral build steps shared by every image
images/<image>/ An image's own install steps
images/locks/ Generated: hash-locked Python requirements
vex/ VEX statements for findings shown not to apply
docs/diagrams/ The build and release flow, in draw.io with an SVG preview
examples/kubernetes/ Kubernetes manifests for Podman in a container and the CI agents
examples/compose/ Docker Compose files: the toolbox as a shell, and the CI agents
tests/ Smoke tests, run in every image as the app user
scripts/ Matrix, tags, pins, VEX and docs (images.py), and CI helpers
.github/workflows/ Build, Release, Pins and Scan
Contributions are welcome. See CONTRIBUTING.md for the workflow and conventions, and SECURITY.md to report a vulnerability privately.