Configure your project

The hive.yml file is the project-level configuration file. It must be placed at the root of your ContainerHive project.

A JSON schema is published to SchemaNest and can be referenced directly at schema-nest.timo-reymann.de/api/schema/json-schema/containerhive-project/latest.

Example

buildkit:
  address: tcp://127.0.0.1:8372

platforms:
  - linux/amd64
  - linux/arm64

cache:
  type: s3
  endpoint: http://garage:3900
  bucket: buildkit-cache
  region: garage
  access_key_id: <your-access-key>
  secret_access_key: <your-secret-key>
  use_path_style: true

registry:
  address: localhost:8500

Fields

`buildkit`

Configuration for the BuildKit daemon.

Field	Type	Description
`address`	string	BuildKit daemon address (e.g. `tcp://127.0.0.1:8372`). Takes precedence over `$BUILDKIT_HOST` for `build`, `test` and `sbom`; leave it unset to use the environment variable. `ch wait` reads only `$BUILDKIT_HOST`

`platforms`

List of target platforms for multi-architecture builds.

platforms:
  - linux/amd64
  - linux/arm64

`cache`

Build cache configuration. Supports S3-compatible storage or registry-based caching.

S3 cache

Field	Type	Description
`type`	string	Must be `s3`
`endpoint`	string	S3 endpoint URL
`bucket`	string	Bucket name
`region`	string	S3 region
`access_key_id`	string	Access key
`secret_access_key`	string	Secret key
`use_path_style`	boolean	Use path-style addressing

Registry cache

Field	Type	Description
`type`	string	Must be `registry`
`ref`	string	Registry reference (e.g. `registry:5000/cache`)
`insecure`	boolean	Allow insecure connections

`cache_dir` / `version_cache_ttl`

Configuration for ContainerHive's own local cache of external version lookups made by tag_ranges. This is not the build cache configured by cache above.

Field	Type	Description
`cache_dir`	string	Directory for the version cache. Relative paths are resolved against the project root. Overridden by the `CONTAINER_HIVE_CACHE_DIR` environment variable, which always wins. Defaults to the XDG cache directory (e.g. `~/.cache/containerhive` on Linux).
`version_cache_ttl`	string	Default TTL for a cached lookup, as a Go duration (e.g. `6h`). Defaults to `1h`. A `tag_range`'s `source.ttl` overrides this per source.

cache_dir: .ch-cache
version_cache_ttl: 6h

`registry`

Local OCI registry used for inter-image dependencies and multi-arch manifest creation.

Field	Type	Description
`address`	string	Registry address (e.g. `localhost:8500`)

`labels`

Project-level OCI image labels applied to every built image. All fields are optional.

labels:
  vendor: Acme Corp
  authors: platform@acme.test
  url: https://github.com/acme/images/tree/main/%image%
  documentation: https://docs.acme.test/images/%image%/%tag%
  custom:
    com.acme.team: platform

Field	Type	Description
`vendor`	string	Sets `org.opencontainers.image.vendor`
`authors`	string	Sets `org.opencontainers.image.authors`
`url`	string	Sets `org.opencontainers.image.url`. Supports `%image%` and `%tag%` placeholders
`documentation`	string	Sets `org.opencontainers.image.documentation`. Supports `%image%` and `%tag%` placeholders
`custom`	map	Arbitrary labels merged into every image. Standard auto-derived OCI keys override colliding entries

Auto-derived labels

ContainerHive applies the following labels to every image without configuration:

Label	Value
`org.opencontainers.image.title`	Image name
`org.opencontainers.image.ref.name`	Image name
`org.opencontainers.image.version`	Tag name (including any variant suffix)
`org.opencontainers.image.created`	Build time in RFC3339
`org.opencontainers.image.description`	`description` field from `image.yml`, when set
`org.opencontainers.image.revision`	Current git commit, when the build runs in a git repo
`org.opencontainers.image.source`	`origin` remote URL, when available

Precedence

Custom labels can be declared at four scopes. They merge from least to most specific, so deeper scopes override shallower ones:

project labels < image labels < tag labels < variant labels

Standard auto-derived OCI keys (the table above plus the structured project fields like vendor) always win over a custom-map entry with the same key.

`template_options`

Custom key-value variables available in CI and custom templates via the option function.

template_options:
  ci_buildkit_image: registry.io/buildkit
  ci_buildkit_version: v1.4.0
  my_custom_var: some-value

All values must be strings. Keys prefixed with ci_ have built-in defaults:

Key	Default	Description
`ci_buildkit_image`	`ghcr.io/containerhive/helper-images/buildkit`	BuildKit container image
`ci_buildkit_version`	(release series of the go.mod dependency, e.g. `v0.34`)	BuildKit image tag. With a custom `ci_buildkit_image` and no version, the exact go.mod version (e.g. `v0.34.0`) is used
`ci_dind_image`	`ghcr.io/containerhive/helper-images/dind:29.9`	Docker-in-Docker image for the test jobs. The default runs privileged. On Kubernetes runners without privileged pods, use the rootless `ghcr.io/containerhive/helper-images/dind-rootless:29.9`, see Docker-in-Docker for test jobs. Set `docker:dind` to use the upstream image
`ci_lint`	`true`	Run hadolint linting in CI pipeline before builds
`ci_build_shards`	`1`	Upper bound on parallel build instances per image (capped to shard unit count)
`ci_test_shards`	`1`	Upper bound on parallel test instances per image (capped to shard unit count)
`ci_cancel_outdated`	`true`	Cancel in-progress pipelines when a newer pipeline starts on the same ref
`ci_report`	`true`	Generate and publish HTML/JSON report to GitHub Pages / GitLab Pages
`ci_sbom_generate_cpes`	`true`	Generate CPEs in SBOMs (set to `false` to stay under GitLab artifact limits)
`ci_version_cache`	`true`	Cache `tag_ranges` version lookups across CI runs (only emitted when a project uses `tag_ranges`)
`ci_version_cache_dir`	`.ch-cache`	Cache directory for `tag_ranges` version lookups, relative to the project root — add it to `.gitignore`
`actions_checkout_version`	`v6`	Version of `actions/checkout`
`actions_upload_artifact_version`	`v7`	Version of `actions/upload-artifact`
`actions_download_artifact_version`	`v7`	Version of `actions/download-artifact`
`actions_upload_pages_artifact_version`	`v3`	Version of `actions/upload-pages-artifact`
`actions_deploy_pages_version`	`v4`	Version of `actions/deploy-pages`
`actions_junit_report_version`	`v6`	Version of `mikepenz/action-junit-report`
`actions_cache_version`	`v4`	Version of `actions/cache`, used for the `tag_ranges` version cache

User-provided values override built-in defaults.

`lint`

Configuration for ch lint, which runs hadolint against plain Dockerfiles in the project. Templated Dockerfiles (e.g. Dockerfile.gotpl) are skipped — hadolint cannot parse Go template syntax.

lint:
  failure_threshold: warning
  ignored:
    - DL3008
  trusted_registries:
    - my-company.com:5000
  label_schema:
    com.acme.team: text
  strict_labels: true

Field	Type	Description
`failure_threshold`	string	Lowest severity that causes a non-zero exit: `error`, `warning`, `info`, `style`, `ignore`. Default: `error`
`ignored`	string list	Rule IDs to ignore (e.g. `DL3000`)
`trusted_registries`	string list	Registries hadolint treats as trusted (suppresses `DL3026`)
`label_schema`	map	Expected LABEL keys and their validation types (see hadolint docs)
`strict_labels`	bool	Fail on labels missing from `label_schema`

`report`

Report generation settings.

report:
  styleSheet: styles/custom.css

Field	Type	Description
`styleSheet`	string	Path to a CSS file to embed in the generated HTML report for custom styling

To restyle the report, see Report theme.

`change_detection`

Decides which changed files affect which images, see Build only changed images. Patterns are doublestar globs relative to the project root, such as docs/** or *.md.

change_detection:
  exclude:
    - README.md
    - docs/**
  treat_as_global:
    - .pre-commit-config.yaml
    - hive.yml
    - scripts/**

Field	Type	Description
`exclude`	string list	Files that never trigger a build
`treat_as_global`	string list	Files that rebuild every image. Wins over `exclude`

A list you set replaces its default; set [] to turn a default off.

Field	Default
`exclude`	`renovate.json`, `renovate.json5`, `.renovaterc`, `.renovaterc.json`, `.github/renovate.json`, `.github/renovate.json5`, `README.md`, `CONTRIBUTING.md`, `mkdocs.yml`, `styles/**`, `.gitignore`, `.gitattributes`
`treat_as_global`	`.pre-commit-config.yaml`, `hive.yml`, `hive.yaml`, `container-hive.yml`, `container-hive.yaml`

Configure your project

Example

Fields

buildkit

platforms

cache

S3 cache

Registry cache

cache_dir / version_cache_ttl

registry

labels