The Chainguard Images repository holds the public build configuration for a comprehensive catalog of minimal, hardened OCI container images distributed through the cgr.dev registry under the chainguard namespace. The repository serves as the source of truth for how these production-ready container images are constructed, tested, and published, making it a critical component of Chainguard's container security and supply chain infrastructure.
Every image in this repository is built using apko, a tool designed for creating minimal container images from declarative configurations. The build process centers on locked_config.json files, which contain fully resolved and pinned package versions for each supported architecture. This pinning approach ensures reproducible builds, meaning the same configuration file will consistently produce identical image content across different build environments and time periods. This reproducibility is fundamental to the repository's security posture and allows users to verify image contents independently.
The publication workflow is automated through a GitHub Actions workflow defined in release.yaml, which monitors changes to locked_config.json files on the main branch and triggers builds on a daily schedule. When changes are detected, the workflow uses a Terraform module at main.tf to orchestrate the build and publication process. This module reads the locked configuration, builds each image variant using the apko Terraform provider, publishes the resulting OCI images to cgr.dev, and generates accompanying SBOMs and cosign attestations for supply chain security verification.
The repository is organized with per-image directories under images/ containing build configurations, tests, and documentation for each image. Shared Terraform modules are centralized in tflib/ to promote consistency across the build infrastructure. The codebase is primarily written in HCL, reflecting its heavy use of Terraform for orchestration and infrastructure as code practices.
The repository emphasizes security best practices through comprehensive documentation including image guidelines in BEST_PRACTICES.md, a security policy for vulnerability reporting, and detailed instructions for building images locally and withdrawing deprecated images. Users can browse the full catalog at images.chainguard.dev and access commercial offerings through Chainguard Console.
