Image Configuration Reference

Complete reference for properties.yml configuration and image settings

Complete reference for configuring container images via properties.yml.

properties.yml Overview

Each image can have custom settings via a properties.yml file. This reference documents all available configuration options.

Minimal example:

---
rpm_packages:
  all:
    - nginx
main_package: nginx
tags:
  - value: latest

Complete structure:

---
# Distro configuration (see Image Variants section)
# distros: [hummingbird]  # Override default distros (use when package unavailable in some distros)

# Image variants (see Image Variants section)
# Use additional_variants to extend defaults, or variants to override completely
additional_variants: [fpm, fpm-builder] # Adds to default variants
# variants: [default, builder]  # Alternative: completely replaces defaults

# Container runtime configuration (see Container Configuration section)
user: default # Optional: 'default' for default_user (65532), or literal user ID/name

# Package management (see Package Management section)
rpm_packages:
  build-deps: [...]
  all:
    - package-name # All architectures
    - name: arch-specific-package # Arch-specific (see Package Management)
      arches:
        only: x86_64
  <distro>: [...]
  <variant>: [...]
additional_repos: [...]
allow_fedora_repos: true # Optional: allow Fedora repos for hummingbird images (temporary workaround)

# Build configuration (see Build Configuration section)
architectures:
  hummingbird: [aarch64, x86_64, s390x] # Optional: replace distro architectures
hermetic: true
# Exceptional legacy source builds only; do not use for new images:
# build_from_source: true
# prefetch_gomod_path: upstream-submodule

# Versioning (see Versioning section)
main_package: package-name
# version_package:            # Optional: override package for version lookup per variant/distro
#   fips: package-fips-name   # Example: variant-specific package name

# Testing configuration (see Testing Configuration section)
reverse_dependency_tests: false # Optional: disable for images like curl

# Release configuration (see Release Configuration section)
repository: image-name # Required: Quay.io repository name
# <reasoning for stream choice>
stream: "latest" # Required: version series identity for the image catalog
application_category: "Storage" # Required: Pyxis application category
# support_level: community        # Optional: community or experimental (default: Red Hat supported)
# deprecated: true                # Optional: mark the image stream as deprecated

# Image metadata (see Image Metadata section)
summary: "Short one-liner description" # Required when adding labels
description: >- # Required when adding labels
  Short paragraph describing the image.
  1-2 sentences about key features.
url: "https://upstream-project.org" # Required when adding labels

tags:
  - value: latest
  - value: '{{ package_major_version("package-name") }}'
    label: io.hummingbird-project.major-version

# Compliance scanning (enabled by default, see Compliance Scanning section)
# oscap:
#   enabled: false         # Optional: set to false to opt out
#   profiles:              # Optional: override which profiles run per variant
#     cis: true
#     stig:
#       variants: ["*fips*"]
#   exclude_rules:         # Optional: exclude specific rules (concatenated with globals)
#     - id: xccdf_org.ssgproject.content_rule_example
#       reason: "Reason for exclusion"
#       variants: ["*fips*"]   # Optional: glob patterns
#       profiles: [cis]        # Optional: limit to specific profiles

Image Metadata

Images can declare metadata fields for container image labels:

summary

  • Type: String
  • Required: When adding image labels (currently caddy only, expanding to all)
  • Length: ~40-80 characters (one-liner)

Short phrase describing what the image is. Used in table/list views and catalog cards.

Do not start with the image name – the name is always visible from context (UI headings, name label, inspect output).

Example: "Web server with automatic HTTPS"

description

  • Type: String (use >- YAML scalar for multi-line readability)
  • Required: When adding image labels
  • Length: ~100-250 characters (1-2 sentences)

Short paragraph for card views, podman inspect, and Kubernetes UIs (io.k8s.description). Describes what the software is and its key distinguishing features.

Use >- (folded scalar) in YAML to keep the value readable across multiple lines – it folds to a single-line string. Do not use | (literal block) as embedded newlines break label syntax.

Avoid embedded double quotes and backslashes – values are emitted as-is in Containerfile LABEL instructions with no escaping.

The same description value is used when generating the image README: the readme_description() macro in README.md.j2 templates renders it as the introductory paragraph. Do not duplicate this text in the template; use {{ readme_description() }}.

Example:

description: >-
  Extensible server platform with automatic HTTPS by default.
  Provides HTTP/3, reverse proxying, load balancing, and static
  file serving with minimal configuration.

url

  • Type: String (URL)
  • Required: When adding image labels

URL for the upstream project homepage. Used in org.opencontainers.image.url and the Conforma url label.

Example: "https://caddyserver.com"

deprecated

  • Type: Boolean
  • Default: Omitted, which means non-deprecated
  • Description: Marks the image stream as deprecated. The generated image carries the io.hummingbird-project.deprecated: true label so the image catalog can display deprecation status for streams it includes.
  • Example: deprecated: true

The field applies to the stream represented by the image directory, including all variants. The catalog tracks deprecated streams within a repository, so active and deprecated streams can remain visible together.

Package updates, builds, tests, and releases continue, and published images remain available. Add deprecation notices and replacement guidance to the image README template separately.

The catalog currently covers Red Hat supported Hummingbird and Rawhide images. Community images carry the label but are not listed in those catalogs.

Image Variants

Images can have multiple variants (e.g., default and builder):

  • default: Minimal runtime environment
  • builder: Includes development tools and build dependencies
  • custom: Define custom variants in properties.yml

Each variant gets its own:

  • Containerfile in generated/images/<name>/<distro>/<variant>/Containerfile
  • RPM lockfiles in generated/images/<name>/<distro>/<variant>/rpms
  • Build pipeline and release tags (non-default variants get -<variant> suffix)

variants

  • Type: Array of strings
  • Default: [default, builder]
  • Description: List of image variants to generate. Completely overrides the default variants. Each variant gets its own Containerfile, lockfiles, build pipeline, and release tags. Non-default variants get a -<variant> suffix in their image tags.
  • Example: [default] (CI images that only need the default variant)
  • Note: Prefer additional_variants when extending defaults; use variants only when you need to exclude default variants.

additional_variants

  • Type: Array of strings or objects
  • Default: None
  • Description: Additional variants to add to the base variants. The base is variants if specified, otherwise the default variants. Use this when you want to extend without repeating.

Simple format (string array):

additional_variants: [fpm, fpm-builder] # Adds FPM variants to base variants for all distros

Object format with distro restrictions:

Each variant can be an object with name and optional distros fields to restrict which distros the variant is built for:

additional_variants:
  - name: fips
    distros: [hummingbird] # Only build fips variant for hummingbird distro
  - name: fpm # Simple string still works in array
  - name: fpm-builder
    distros: [hummingbird, rawhide] # Build for specific distros

The distros field supports glob patterns:

additional_variants:
  - name: fips
    distros: ["*bird"] # Matches hummingbird
  - name: special
    distros: ["raw*"] # Matches rawhide

When to use distro restrictions:

Use distro restrictions when a variant requires packages or features only available in specific distros. For example, FIPS variants may only be available for Hummingbird where FIPS-validated packages are present

variant_descriptions

  • Type: Object (string-to-string mapping)
  • Required: When image has description and defines additional_variants with non-default base specializations
  • Description: Maps base variant names to human-readable descriptions. These descriptions are emitted as the io.hummingbird-project.variant.description label on each container image. The global description for default is defined in images/variables.yml; image-specific entries add descriptions for bases like fpm, runtime, or openssl. Modifier display (builder, fips) is handled by catalog consumers using the boolean variant labels, not by these descriptions.

Writing guidelines:

  • Describe the variant holistically — what the image variant is, not just what packages it adds on top of default. Someone reading the description with no surrounding context (e.g., via podman inspect) should understand the variant’s identity.
  • Use a noun phrase (2-6 words), not a full sentence.
  • Do not start with the image name (the image context is already provided by the image name label).
  • Avoid the word “runtime” in the default description (the OpenJDK runtime variant is a separate base, and OpenJDK’s default includes the full JDK).
  • Avoid expanding abbreviations redundantly (e.g., “JRE runtime” is redundant because JRE already means “Java Runtime Environment”).
  • Prefer functional descriptions (what capability the variant provides) over repeating the variant name as a product name.

Example (PHP image with FPM base):

variant_descriptions:
  fpm: "PHP FastCGI process manager"

Example (OpenJDK image with runtime base):

variant_descriptions:
  runtime: "Headless Java runtime"

distros

  • Type: Array of strings
  • Default: [rawhide, hummingbird] (from images/variables.yml)
  • Description: List of distros to build for this image. Overrides the global default_distros. Use this to disable a distro for images where a required package is not available in that distro.
  • Example: [hummingbird] disables Rawhide builds for this image
  • Note: Each enabled distro creates a full set of variants, so the final combinations are distros × variants.

Container Configuration

user

  • Type: String, integer, or object (per-variant dict)
  • Required: No (defaults to default)
  • Description: Specifies which user the container runs as. The USER directive is rendered via the {{ set_user() }} macro at the end of Containerfile templates. The special (and default) value default maps to the default_user variable (UID 65532). For user: default, the {{ final_stage() }} macro sets HOME=/tmp and WORKDIR /tmp early in the image to ensure unprivileged users have a writable default environment. Images can override WORKDIR later in their Containerfile.j2. For builder variants with user: default, it additionally sets ENV CONTAINER_DEFAULT_USER=65532.

Same user for all variants:

user: default
user: root # Root user
user: postgres # Literal username

Per-variant configuration:

Use when different variants need different users:

user:
  default: root
  builder: root
  fpm: default
  fpm-builder: default

Package Management

Packages are defined in properties.yml under rpm_packages:

rpm_packages:
  build-deps: # Build-time dependencies (installed in builder layer, not in final
    # image). Included in lockfiles for hermetic builds.
    - golang # Example: Go compiler for building from source
    - rpm-build # Example: Tools for building RPMs during image construction

  all: # Included in all variants (Containerfiles and lockfiles)
    - coreutils-single
    - your-main-package
    - name: grub2-efi-x64 # Arch-specific: only on x86_64
      arches:
        only: x86_64
    - name: grub2-efi-aa64 # Arch-specific: only on aarch64
      arches:
        only: aarch64

  hummingbird: # Included in all Hummingbird variants (distro-level key)
    - versioned-package-1.2

  rawhide: # Included in all Rawhide variants (distro-level key)
    - unversioned-package

  builder: # Included only in "builder" variant
    - compiler-packages
    - debug-tools

  custom-variant: # Included only in "custom-variant" variant
    - variant-specific-packages

Package entry format

Each entry in an rpm_packages list can be either a string (installed on all architectures) or an object with architecture constraints:

String entry (all architectures):

- coreutils-single

Object entry (arch-specific):

- name: grub2-efi-x64
  arches:
    only: x86_64 # Install only on x86_64
- name: some-package
  arches:
    not: aarch64 # Install on all architectures except aarch64

The arches.only and arches.not fields accept either a single string or a list of strings. Package constraints use RPM architecture names: aarch64, x86_64, s390x, and ppc64le.

How arch-specific packages work:

  1. Lockfiles: Arch-specific entries are passed to rpm-lockfile-prototype using its native per-arch package format. The lockfile resolver only includes matching packages for each architecture.
  2. Containerfiles: Arch-specific packages are installed via a case statement on TARGETARCH, so the correct packages are installed during multi-arch builds.

rpm_packages.build-deps

  • Type: Array of strings or arch-specific objects
  • Description: Build-time dependencies needed during image construction. Automatically installed in the builder layer (not in the final image) and included in lockfiles for hermetic builds. Use for compilers, build tools, and other packages needed only during the build process.

rpm_packages.all

  • Type: Array of strings or arch-specific objects
  • Description: Packages included in all variants, in both Containerfiles and lockfiles

rpm_packages.<distro>

  • Type: Array of strings or arch-specific objects
  • Description: Packages included in all variants for the specified distro. Useful when different distros ship different package names (e.g. versioned vs unversioned) and the packages should apply to every variant within that distro.

rpm_packages.<variant>

  • Type: Array of strings or arch-specific objects
  • Description: Packages included only in the specified variant, regardless of distro

additional_repos

  • Type: Array of strings (repository filenames)
  • Default: None
  • Description: Additional yum repository files from yum-repos/ to include in the RPM lockfile generation. These repos are added to the variant-specific repos (see [Global Variables Reference
  • Example: [konflux-ci-rpm-lockfile-prototype-main-fedora-rawhide.repo]
  • Usage: Only needed for packages not available in standard Fedora repos or variant-specific repos

allow_fedora_repos

  • Type: Boolean
  • Default: false
  • Description: Allow Fedora repositories during lockfile generation for Hummingbird production images. By default, production Hummingbird images exclude Fedora repos to ensure packages come only from the Hummingbird repository. Set to true to temporarily allow Fedora repos when required packages are not yet available in the Hummingbird repository.
  • Example: true
  • Usage: Typically used temporarily for packages not yet built for Hummingbird (e.g., .NET runtime on x86_64, OpenJDK packages). Should be removed once packages are available in the Hummingbird repository.
  • Note: Toolchain and similar images under images/ (such as hummingbird-builder) use Fedora repositories for signature validation regardless of this setting.

Hermetic Builds

For hermetic builds (enabled by default), all packages from:

  • rpm_packages.build-deps - included in lockfiles and Containerfiles (builder layer only)
  • rpm_packages.all - included in lockfiles and Containerfiles (final image)
  • rpm_packages.<distro> - included in lockfiles and Containerfiles for all variants of a distro
  • rpm_packages.<variant> - included in lockfiles and Containerfiles for matching variants
  • default_rpm_packages.builder - automatically added for builder variants (see Global Variables Reference - default_rpm_packages)

are added to rpms.lock.yaml and prefetched using cachi2 for offline builds.

Build-time vs Runtime Packages:

  • rpm_packages.build-deps: Installed in the builder layer only (not in final image)
  • rpm_packages.all: Installed in ${NEWROOT} (the final image)
  • rpm_packages.<distro>: Installed in ${NEWROOT} for all variants of the specified distro
  • rpm_packages.<variant>: Installed in ${NEWROOT} for the specified variant

Build Configuration

architectures

  • Type: Mapping of distro or distro/variant to a non-empty list of RPM architecture names
  • Default: default_architectures[distro] in images/variables.yml

Lists replace defaults. A distro/variant entry takes precedence over a distro entry. Unknown names, duplicate entries, empty lists, and unknown selection keys are rejected. Package arches.only and arches.not constraints use the same architecture names. Exclusions apply to the effective architecture list for the selected variant.

architectures:
  hummingbird: [aarch64, x86_64, s390x]
  hummingbird/fips: [aarch64, x86_64]

Rawhide defaults to aarch64 and x86_64. Builds convert x86_64 to amd64 and aarch64 to arm64; s390x and ppc64le keep their names. The resolved lists drive RPM inputs and Konflux build platforms.

Before enabling another architecture, verify package repositories, builder manifests, native build workers, test workers, and test helper images. Generated files must be regenerated from their source configuration.

hermetic

  • Type: Boolean
  • Default: true
  • Description: Controls whether the Konflux build pipeline passes HERMETIC=true to the buildah task, enabling hermetic (offline, network-isolated) builds with prefetched dependencies.
  • Important: Images with hermetic: false are blocked from release by the Conforma hermetic_task policy. hermetic: false should not be used for any image in the containers repository.

build_from_source

  • Type: Boolean
  • Default: false
  • Description: Controls version extraction in the package_version() macro. When true, extracts version from .gitmodules for images built from git submodules. When false, extracts version from RPM package metadata. Does not control whether source code is compiled in the Containerfile.
  • Warning: Do not use for new images. Software built directly from source is not represented by RPM package metadata and cannot be scanned for CVEs by the project’s package-based scanner. This setting exists only for exceptional legacy images.

prefetch_gomod_path

  • Type: String (path relative to image directory)
  • Default: None
  • Description: Path to a Golang project directory (typically a git submodule) for prefetching Go modules via cachi2. Enables hermetic builds for Go projects without a vendor tree. The path is relative to the image directory.
  • Usage: Existing exceptional source-built images only. Do not use for new images because source-built software cannot be scanned for CVEs by the project’s package-based scanner.

Versioning

main_package

  • Type: String
  • Description: Specifies the main package for version labeling

For RPM-based images:

Set to the package name. Version is extracted from RPM package metadata.

main_package: nginx

For source-built images:

Existing exceptional source-built images set this to the submodule path. Version is extracted from the branch field in .gitmodules. Do not use this pattern for new images: source-built software cannot be scanned for CVEs by the project’s package-based scanner.

main_package: images/minio/minio-upstream
build_from_source: true

version_constraints

  • Type: String (glob pattern)
  • Default: None (no constraints)
  • Description: Defines a version constraint pattern to prevent unwanted major or minor version updates. The constraint applies to all distros for this image. Constraints are validated during make check, and builds fail if VERSION files violate the constraint. Primarily used for multi-version images (e.g., python-3-11, nodejs-20) to ensure they stay on their intended version family.

Constraint patterns:

Patterns use glob-style matching:

  • 3.11.* - Match any 3.11.X version (recommended)
  • 20.* - Match any 20.X version
  • 8.* - Match any 8.X version
  • 1.25.* - Match any 1.25.X version (for 3-part versioning like Go)

The pattern matches against the content of VERSION files generated during the build process.

Example:

main_package: python3.11
version_constraints: "3.11.*" # Ensure python-3-11 stays on 3.11.X across all distros
main_package: dotnet-sdk-8.0
version_constraints: "8.*" # Applies to rawhide, hummingbird, and any other distros

When to use:

  • Multi-version images where each image targets a specific version family
  • Preventing automatic major/minor version bumps during Renovate updates
  • Ensuring version tags remain accurate (e.g., python:3.11 doesn’t become python:3.12)

Violation handling:

When a constraint is violated, make check fails with a detailed error message showing:

  • The VERSION file path
  • The actual version found
  • The constraint that was violated
  • The properties.yml file where the constraint is defined

Options for resolution:

  1. Create a new image for the new version (recommended for major/minor bumps)
  2. Exclude the violating version via yum-repos/*.repo excludepkgs
  3. Update the constraint to allow the new version

See Version Constraints for detailed documentation.

version_package

  • Type: Object (string-to-string mapping)
  • Default: None
  • Description: Override the package name used for version extraction on a per-distro, per-variant, or per-distro/variant basis. When a variant or distro installs a different package that provides the same software (e.g., a FIPS-enabled build), this field tells the version/tag macros which package name to look up in the lockfile. The lookup order is: distro/variant, then variant, then distro, then main_package.

Per-distro override:

Use when different distros ship the same software under different package names:

main_package: ruby
version_package:
  hummingbird: ruby4.0 # hummingbird ships ruby4.0, rawhide ships ruby

Per-variant override:

Use when a variant installs a differently-named package:

main_package: ruby
version_package:
  minimal: ruby-minimal # minimal variant resolves version from ruby-minimal

Per-distro/variant override:

Use when both distro and variant affect the package name:

main_package: ruby
version_package:
  hummingbird/fips: ruby4.0-fips

Usage in templates:

The resolved package name is available as package_name_for_version in Jinja2 templates:

tags:
  - value: "{{ package_version(package_name_for_version) }}"
    label: org.opencontainers.image.version
ENV GOLANG_VERSION={{ package_version(package_name_for_version) }}

Testing Configuration

reverse_dependency_tests

  • Type: Boolean
  • Default: true
  • Description: Controls whether this image participates in reverse dependency workflows (both building and testing). When true, changes to this image trigger rebuilds and tests of all images that depend on it. Dependencies are detected by searching for TEST_IMAGES[...] references in test scripts. Set to false for images that should not trigger reverse dependency workflows when changed.
  • Example: Set to false for curl to avoid triggering unnecessary reverse dependency tests

How it works in CI:

When an image is tested, the CI pipeline performs two phases:

  1. Build Phase: Builds all dependencies needed for testing

    • Uses ci/build_images.sh --build-deps to build:
      • Forward dependencies (images the main image’s tests depend on)
      • Reverse dependencies (images that depend on the main image, filtered by reverse_dependency_tests: true)
      • Forward dependencies of those reverse dependencies
    • Automatically deduplicates to ensure each image is built exactly once
  2. Test Phase: Runs tests on the main image and its reverse dependencies

    • Uses ci/run_tests_container.sh and ci/run_tests_k8s.sh with --include-reverse-deps to test:
      • The main image
      • All reverse dependencies (filtered by reverse_dependency_tests: true)
    • Kubernetes runs exclude reverse dependencies from the same image group, since a single-component run cannot provide their sibling images; those run in the group pipelines. See run_tests_k8s.sh.

Why set to false?

Set reverse_dependency_tests: false for images like curl that are:

  • Used pervasively across many images (too many reverse dependencies)
  • Have a small, stable API that can be fully tested in their own tests
  • Would cause excessive CI load if every dependent image were tested on each change

Release Configuration

The repository and stream fields together define the release identity for an image. Both are required and validated during CI. The repository specifies the Quay.io repository name, and the stream specifies the version series within that repository.

repository

  • Type: String
  • Required: Yes
  • Description: The Quay.io repository name for this image. For images where the directory name matches the desired repository name (e.g., images/nginx/ → repository: nginx), this is redundant but still required for explicitness. For versioned image directories, this groups multiple versions under one repository (e.g., nodejs-20 and nodejs-24 both use repository: nodejs).
  • Example: nodejs (used by nodejs-20 and nodejs-24 directories)

stream

  • Type: String
  • Required: Yes
  • Description: The version series identity for this image within its repository. Emitted as the io.hummingbird-project.stream label on the container image, enabling the image catalog to provide consistent structured data about multi-stream repositories.

The stream value must reflect upstream’s actual branch structure at the granularity where parallel security-maintained branches exist. Use endoflife.date to determine the correct granularity.

Key rules:

  • The stream is never derived from the image directory name. The directory name is not evidence for stream granularity (e.g., a directory named foo/ for an upstream with branches 2.8, 3.0, 3.2 still requires a major.minor stream like "3.0").
  • The purpose of upstream branches is irrelevant to granularity. Whether upstream calls them “LTS”, “stable”, “mainline”, or “STS” does not matter. If they are parallel branches receiving security updates, the stream granularity must match.
  • Match the upstream project’s version naming convention. If the project identifies branches as 8.0, 9.0 (not 8, 9), use that format even if endoflife.date abbreviates it.
  • Sequential minor versions are not parallel branches. If endoflife.date lists minor versions that each immediately supersede the previous with no support overlap, the minor is a release counter. Use the major version as the stream.
  • Use "latest" only for images where no meaningful version series identity exists: rolling-release tools with date-based versioning (e.g., minio) or base images that track the distro rather than independent software (e.g., core-runtime).
  • For unversioned images (no version in directory name, no version constraints), the stream value reflects the version currently shipped and must be updated when the upstream version changes.

See the stream assignment guidelines for the full decision process and rationale.

Document the reasoning for the stream choice as a YAML comment above the stream field. This ensures future maintainers understand why a particular granularity was chosen.

Examples:

# endoflife.date: parallel at major (Docker Hub + Debian + Wolfi)
stream: "24"
# endoflife.date: parallel at major.minor (Docker Hub + Debian + Wolfi)
stream: "3.11"
# endoflife.date: branches are 10.1, 11.0, not 10, 11
stream: "10.1"
# rolling release with date-based versions, no version branches
stream: "latest"

application_category

  • Type: String
  • Required: Yes
  • Description: The Pyxis application category for the image’s delivery repository. Emitted as the io.hummingbird-project.application-category label on the container image and used in the generated Pyxis repo config. All images sharing the same repository must use the same value. Validated during make check against the list in ci/application-categories.txt.

Common values for Hummingbird images:

  • "Programming Languages & Runtimes" – language runtimes and SDKs (Go, Python, Node.js, .NET, Ruby, etc.)
  • "Web Services" – web servers, reverse proxies, and load balancers (Nginx, httpd, Caddy, HAProxy, Tomcat)
  • "Database & Data Management" – databases and caches (PostgreSQL, MariaDB, Valkey, Memcached)
  • "Developer Tools" – CLI utilities and build tools (git, curl, jq)
  • "Storage" – object storage (MinIO, MinIO Client)
  • "Operating System" – base runtime images (core-runtime)

Example:

application_category: "Web Services"

tags

  • Type: Array of objects
  • Description: Define image tags for Quay.io releases. Each variant gets these tags, with non-default variants receiving a -<variant> suffix.

Tag Object Fields:

  • value (required): The tag value. Can be a literal string (e.g., latest) or a Jinja2 template using helper functions.
  • label (optional): If specified, the tag value is written as a LABEL in the Containerfile, and the actual rendered value from the label is used as the image tag. This ensures version tags match the actual package versions in the image.

Tag Helper Functions:

  • package_version("<package-name>") - Full version (e.g., 1.2.3-4.fc42)
  • package_major_version("<package-name>") - Major version only (e.g., 1)
  • package_major_minor_version("<package-name>") - Major.minor version (e.g., 1.2)
  • rpm_lockfile.content_date - YYYYMMDD UTC date when the lockfile content last changed. Available for all images with an RPM lockfile. Only advances when the resolved RPM set changes, not on every lockfile regeneration.

Example:

tags:
  - value: latest # Literal tag, no label
  - value: '{{ package_major_version("nginx") }}' # Template tag with label
    label: io.hummingbird-project.major-version
  - value: '{{ package_major_minor_version("nginx") }}' # Tag becomes actual version from label
    label: io.hummingbird-project.major-minor-version
  - value: '{{ package_version("nginx") }}'
    label: org.opencontainers.image.version

Note: For images with multiple versions, only set latest on the latest version.

tag_suffix_aliases

  • Type: Mapping of variant names to arrays of suffixes
  • Description: Add aliases for every configured tag without creating another image variant. The suffix is appended directly to each base tag. Existing canonical tags remain unchanged.
  • Example:
tag_suffix_aliases:
  default:
    - jdk25
  builder:
    - jdk25-builder

support_level

  • Type: String

  • Default: Omitted (image is Red Hat supported)

  • Values: community, experimental

  • Description: Controls the support level, Quay organization, and Konflux application assignment for hummingbird-distro images. The mapping from support level to Quay org is defined in images/variables.yml under support_levels; all other names (Konflux app, service account, RPA suffix) are derived from the Quay org name. When omitted, the image is Red Hat supported and assigned to containers-hummingbird. Rawhide images are always assigned to containers-rawhide regardless of this property.

  • Example: support_level: community

  • Mapping:

    Value Quay org Konflux app CPE Pyxis/RPA
    (omitted) hummingbird containers-hummingbird Yes Included
    community hummingbird-community containers-community-hummingbird No Excluded
    experimental hummingbird-ci containers-ci-hummingbird No Excluded
  • Usage: Use community for images maintained by the community (e.g., minio, os-minimal). Use experimental for internal build infrastructure (e.g., hummingbird-builder). These images are built and tested normally but published to their designated Quay organization, not the official Red Hat registry.

How Labels Work:

  1. Template is rendered and written to Containerfile: LABEL org.opencontainers.image.version=1.27.3-1.fc42
  2. Build system extracts the actual value from the image label
  3. Image is tagged with the extracted value: registry.access.redhat.com/hi/nginx:1.27.3-1.fc42

This ensures tags always match the actual package versions built into the image.

Upstream Comparison Configuration

The compare section configures which upstream and third-party images to track for automated vulnerability comparison via the container catalog’s external image scanning pipeline. Place it at the end of properties.yml, after all other sections.

Repository and stream values are whatever the image itself uses. Variant names use Hummingbird names where an equivalent exists (e.g. builder for upstream dev images); upstream-only variants like slim or alpine keep their upstream names.

compare

  • Type: Object
  • Required: No (omit for images with no upstream or third-party equivalent)
  • Description: Configures which upstream and third-party images to track. When present, the aggregation script (ci/aggregate_compare.py) includes this image’s sources in the combined config uploaded to DynamoDB, where the external scanning pipeline picks it up.

compare.sources

  • Type: Array of source objects
  • Required: Yes (when compare is present)
  • Description: List of external image sources to compare against. Each source object documents one upstream registry.

source registry

  • Type: String
  • Required: Yes
  • Description: Full registry pull reference for the upstream image. Must include the full path — use docker.io/library/nginx, not docker.io/nginx.

Example: docker.io/library/nginx, cgr.dev/chainguard/python

source tags

  • Type: Array of tag objects
  • Required: Yes (non-empty)
  • Description: Tags to track on the upstream registry. Each tag object has two fields:
Field Required Description
tag Yes The registry tag to track. Must be a tag that exists on the upstream registry.
variant Yes The variant this tag represents (e.g. default, alpine, slim). Use Hummingbird variant names where equivalents exist (e.g. builder for upstream dev images).

source variants

  • Type: Array of variant description objects
  • Required: Yes
  • Description: Describes the variants referenced in tags. Each variant object has:
Field Required Description
name Yes Variant identifier matching the variant values used in tags.
description Yes Human-readable description of this variant.
base Yes Base variant name (use the variant name, e.g. default, alpine, slim).
builder Yes Whether this is a builder variant. Use false for upstream images.
fips Yes Whether this is a FIPS variant. Use false for upstream images.

Tag selection guidance

Use floating tags, not version-pinned tags. Floating tags (e.g. mainline, 3.14) track the latest patch release automatically. Version-pinned tags (e.g. 1.31.7, 3.14.10) go stale and require manual updates.

Match the upstream project’s branch or release structure. Check the upstream registry for available tags. Common patterns:

  • Branch-based tags (nginx): mainline, mainline-alpine — these float to the latest release in the mainline branch. Only track the branch that matches your image’s stream.
  • Minor-version tags (python, node): 3.14, 3.14-slim, 3.14-alpine — these float to the latest patch within the minor version.
  • Latest-only (Chainguard): latest — the only publicly available tag on the free tier.

Place source entries in the directory of the stream they track. The aggregated config derives every tag’s stream from its directory’s own top-level stream: value, so a source belongs in the directory whose stream matches what the upstream tag delivers:

  • Upstream has named branches (e.g. nginx mainline) → the source lives in the directory whose stream: is mainline
  • Upstream has 3.14.x and 3.15.x release series → the sources live in the stream: "3.14" and stream: "3.15" directories respectively
  • Rolling tags like latest map to the numbered stream they currently deliver — e.g. a Chainguard latest tag that is currently Python 3.15 belongs in the python-3-15 directory
  • Directories whose stream: is latest (rolling releases, date-based versions) emit stream: latest automatically

Chainguard images: Chainguard’s free tier only offers latest and latest-dev tags. Place the Chainguard source in the image directory whose stream matches the Chainguard image’s actual version. Check with podman run --rm cgr.dev/chainguard/<image>:latest --version (or equivalent). Chainguard python:latest is currently Python 3.15, so it belongs in python-3-15/properties.yml. When Chainguard moves to a newer version, move the source to the new stream’s directory. Use variant: "builder" for latest-dev (the dev image with a shell and package manager).

Variant naming: use Hummingbird variant names where upstream equivalents exist — default for plain runtime images, builder for upstream dev images that add a shell and package manager (e.g. Chainguard’s latest-dev). Upstream-only variants with no Hummingbird equivalent (e.g. Docker Hub slim, alpine) keep their upstream names. CVE data for all tracked variants is served the same way, so frontends can present them however fits.

Repository association: the aggregation script automatically attaches the image’s top-level repository: value to each aggregated tag. The catalog uses it to find the external sources belonging to an image detail page — no need to repeat it in the compare: section.

Multi-directory images: When multiple image directories compare against the same upstream registry (e.g. python-3-11/ through python-3-15/ all compare against docker.io/library/python), each directory’s compare.sources lists only its own stream’s tags. The aggregation script merges entries with the same registry — duplicate tags across directories are an error. Because the repository is attached per tag, different Hummingbird repositories may share one upstream registry (e.g. caddy and xcaddy comparing different tags of docker.io/library/caddy).

Examples

nginx — branch-based tags, two upstream branches, plus Chainguard:

compare:
  sources:
    - registry: docker.io/library/nginx
      tags:
        - { tag: "mainline", variant: "default" }
        - { tag: "mainline-alpine", variant: "alpine" }
      variants:
        - {
            name: "default",
            description: "Debian-based image",
            base: "default",
            builder: false,
            fips: false,
          }
        - {
            name: "alpine",
            description: "Alpine-based image",
            base: "alpine",
            builder: false,
            fips: false,
          }
    - registry: cgr.dev/chainguard/nginx
      tags:
        - { tag: "latest", variant: "default" }
      variants:
        - {
            name: "default",
            description: "Chainguard image",
            base: "default",
            builder: false,
            fips: false,
          }

python-3-14 — minor-version tags, one stream per directory (the aggregation script merges all python-3-XX directories into a single docker.io/library/python entry):

compare:
  sources:
    - registry: docker.io/library/python
      tags:
        - { tag: "3.14", variant: "default" }
        - { tag: "3.14-slim", variant: "slim" }
        - { tag: "3.14-alpine", variant: "alpine" }
      variants:
        - {
            name: "default",
            description: "Debian-based image",
            base: "default",
            builder: false,
            fips: false,
          }
        - {
            name: "slim",
            description: "Minimal Debian-based image",
            base: "slim",
            builder: false,
            fips: false,
          }
        - {
            name: "alpine",
            description: "Alpine-based image",
            base: "alpine",
            builder: false,
            fips: false,
          }

python-3-15 — adds a Chainguard source: rolling latest tags mapped to the current stream, with latest-dev using the builder variant:

compare:
  sources:
    - registry: docker.io/library/python
      tags:
        - { tag: "3.15", variant: "default" }
        - { tag: "3.15-slim", variant: "slim" }
        - { tag: "3.15-alpine", variant: "alpine" }
      variants:
        - {
            name: "default",
            description: "Debian-based image",
            base: "default",
            builder: false,
            fips: false,
          }
        - {
            name: "slim",
            description: "Minimal Debian-based image",
            base: "slim",
            builder: false,
            fips: false,
          }
        - {
            name: "alpine",
            description: "Alpine-based image",
            base: "alpine",
            builder: false,
            fips: false,
          }
    - registry: cgr.dev/chainguard/python
      tags:
        - { tag: "latest", variant: "default" }
        - { tag: "latest-dev", variant: "builder" }
      variants:
        - {
            name: "default",
            description: "Chainguard image",
            base: "default",
            builder: false,
            fips: false,
          }
        - {
            name: "builder",
            description: "Chainguard image with shell and package manager",
            base: "default",
            builder: true,
            fips: false,
          }

minio (hypothetical) — rolling release with only a latest tag and no version series on either side:

compare:
  sources:
    - registry: docker.io/minio/minio
      tags:
        - { tag: "latest", variant: "default" }
      variants:
        - {
            name: "default",
            description: "Official MinIO image",
            base: "default",
            builder: false,
            fips: false,
          }

Compliance Scanning

OpenSCAP compliance scanning verifies CIS and STIG compliance during the build. Scanning runs against the container rootfs using oscap-chroot and fails the build if any enabled rules are violated.

Scanning is enabled by default for all images. It only runs for the Hummingbird distro and is skipped for the builder base image.

oscap.enabled

  • Type: Boolean
  • Default: true (from images/variables.yml)
  • Description: Controls whether OpenSCAP compliance scanning runs for this image. When true, a verify-compliance step is added to the generated Containerfile for all Hummingbird variants. Set to false to opt out.
oscap:
  enabled: false

oscap.profiles

  • Type: Object mapping profile names to enablement rules
  • Default: {cis: true, stig: {variants: ["*fips*"]}} (from images/variables.yml)
  • Description: Controls which compliance profiles run for each variant. Each profile can be set to true (all variants), false (disabled), or an object with a variants list of glob patterns.

Default behavior (CIS for all variants, STIG only for FIPS variants):

oscap:
  profiles:
    cis: true
    stig:
      variants:
        - "*fips*"

Enable STIG for all variants:

oscap:
  profiles:
    stig: true

Disable CIS for a specific image:

oscap:
  profiles:
    cis: false

The variants field supports glob patterns using fnmatch syntax (e.g., *fips* matches fips, fips-builder, openssl-fips).

oscap.exclude_rules

  • Type: Array of rule exclusion objects
  • Default: Global rule exclusions from images/variables.yml
  • Description: Rules to exclude from compliance scanning. Image-level exclusions are concatenated with global exclusions (not replaced). Each exclusion object has the following fields:
Field Type Required Description
id String Yes XCCDF rule ID (e.g., xccdf_org.ssgproject.content_rule_configure_crypto_policy)
reason String Yes Explanation for excluding this rule
variants Array of strings No Glob patterns for variants this exclusion applies to. Omit for all variants.
profiles Array of strings No Profile names (cis, stig) this exclusion applies to. Omit for all profiles.

Exclude a rule for all variants and profiles:

oscap:
  exclude_rules:
    - id: xccdf_org.ssgproject.content_rule_configure_crypto_policy
      reason: "Caddy uses Go's built-in TLS stack, not system crypto-policies"

Exclude a rule only for specific variants:

oscap:
  exclude_rules:
    - id: xccdf_org.ssgproject.content_rule_configure_crypto_policy
      reason: "crypto-policies state files not generated in installroot"
      variants:
        - "*fips*"

Exclude a rule only from a specific profile:

oscap:
  exclude_rules:
    - id: xccdf_org.ssgproject.content_rule_some_rule
      reason: "Not applicable to CIS for this image"
      profiles:
        - stig

Combine variant and profile filters:

oscap:
  exclude_rules:
    - id: xccdf_org.ssgproject.content_rule_configure_crypto_policy
      reason: "crypto-policies state files not generated in installroot for FIPS variants"
      variants: ["*fips*"]
      profiles: [cis]

How compliance scanning works

  1. Profile resolution: generate_jinja2.py determines which profiles (CIS, STIG) are active for the current variant based on oscap.profiles.
  2. Rule filtering: Exclusion rules are filtered by variant (glob matching) and profile, producing per-profile exclusion lists.
  3. Tailoring file: If any active profile has exclusions, an XCCDF tailoring file (oscap-tailoring.xml) is generated in the variant directory with custom profiles extending the upstream CIS/STIG profiles.
  4. Containerfile: The verify-compliance command is added with explicit --cis and/or --stig flags based on active profiles, plus a --tailoring-file argument if exclusions exist.
  5. Build-time scan: oscap-chroot evaluates the rootfs against each active profile. The build fails if any non-excluded rule fails.

Next Steps