Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

annotations

Annotations for the manifest, nested attribute sets are flattened to dotted keys. Most org.opencontainers.image annotations are set automatically if the GitHub or GitLab integration is enabled. The created and revision annotations are read from the git repository in the working directory if there is one.

Type: attribute set of anything

Default:

{ }

autoTags

Configuration for tags that are generated automatically.

Type: submodule

Default:

{ }

autoTags.branch

Whether to enable add a tag based on the branch name.

Type: boolean

Default:

true

Example:

false

autoTags.latest

Whether to enable add a ‘latest’ tag if branch == defaultBranch.

Type: boolean

Default:

true

Example:

false

autoTags.major

Whether to enable add a tag based on the major version (e.g., 1).

Type: boolean

Default:

true

Example:

false

autoTags.majorMinor

Whether to enable add a tag based on the major and minor version (e.g., 1.2).

Type: boolean

Default:

true

Example:

false

autoTags.version

Whether to enable add a tag based on the version (e.g., 1.2.3).

Type: boolean

Default:

true

Example:

false

branch

Name of the git branch (e.g., main).

Type: null or string

Default:

"`$GITHUB_REF_NAME` or `$CI_COMMIT_BRANCH` in branch pipelines if the GitHub or GitLab integration is enabled, else the checked out git branch"

compression

Compression of the image layers, null keeps them as they are in the images.

Type: null or one of “gzip”, “zstd”

Default:

"gzip"

cosign

Configuration for signing the manifest with cosign.

Type: submodule

Default:

{ }

cosign.enable

Whether to enable signing the pushed manifest with cosign.

Type: boolean

Default:

false

Example:

true

cosign.extraArgs

Extra arguments passed to cosign sign and cosign attest.

Type: list of string

Default:

[ ]

cosign.key

Path or KMS URI of a cosign key. Null means keyless OIDC signing.

Type: null or string

Default:

null

Example:

"cosign.key"

cosign.recursive

Whether to enable signing each per-platform image in the manifest list.

Type: boolean

Default:

true

Example:

false

defaultBranch

Name of the git branch that is used as default for the latest tag.

Type: null or string

Default:

"the repository's default branch if the GitHub or GitLab integration is enabled, else `main`"

format

The format of the manifest

Type: one of “oci”, “v2s2”

Default:

"oci"

github

GitHub integration configuration

Type: submodule

Default:

{ }

github.enable

Whether the GitHub integration is enabled. If set to true, the repository metadata is read from the GitHub Actions environment and event payload at runtime.

Type: boolean

Default:

false

Example:

true

github.actor

GitHub actor. Used as default value for registries."ghcr.io".username.

Type: string

Default:

"$GITHUB_ACTOR"

github.outputFile

File that the name and digest of the pushed index are appended to as step outputs, skipped if empty.

Type: string

Default:

"$GITHUB_OUTPUT"

github.registry

Name of the GitHub registry

Type: string

Default:

"ghcr.io"

github.repo

Full name of the GitHub repository (e.g., mirkolenz/flocken). Used as default value for registries."ghcr.io".repo.

Type: string

Default:

"$GITHUB_REPOSITORY"

github.token

GitHub access token. Used as default value for registries."ghcr.io".password.

Type: string

Default:

"$GITHUB_TOKEN"

gitlab

GitLab integration configuration

Type: submodule

Default:

{ }

gitlab.enable

Whether the GitLab integration is enabled. If set to true, the project metadata is read from the predefined variables of GitLab CI/CD at runtime.

Type: boolean

Default:

false

Example:

true

gitlab.outputFile

File that the DOCKER_MANIFEST_NAME and DOCKER_MANIFEST_DIGEST of the pushed index are appended to, skipped if empty. Its variables are passed to later jobs if it is declared as artifacts:reports:dotenv.

Type: string

Default:

"docker-manifest.env"

gitlab.password

Password for the GitLab container registry. Used as default value for registries."$CI_REGISTRY".password.

Type: string

Default:

"$CI_REGISTRY_PASSWORD"

gitlab.registry

Name of the GitLab container registry.

Type: string

Default:

"$CI_REGISTRY"

gitlab.repo

Full path of the GitLab project (e.g., mirkolenz/flocken). Used as default value for registries."$CI_REGISTRY".repo.

Type: string

Default:

"$CI_PROJECT_PATH"

gitlab.username

Username for the GitLab container registry. Used as default value for registries."$CI_REGISTRY".username.

Type: string

Default:

"$CI_REGISTRY_USER"

images

Images to be added to the manifest, given as packages or as attribute sets with an image and its sbom. Note: This should be a list of identical images for different architectures.

Type: non-empty (list of ((submodule) or package convertible to it))

Example:

with self.packages; [ x86_64-linux.image aarch64-linux.image ]

images.*.image

Nix-built image, either an archive (e.g., pkgs.dockerTools.buildLayeredImage) or a stream (e.g., pkgs.dockerTools.streamLayeredImage). Streams of pkgs.dockerTools are run with the Python interpreter of the host, so images of other platforms need no emulation.

Type: package

images.*.sbom

SBOM of the image as a CycloneDX, SPDX 2, or SPDX 3 JSON document, whose format is detected from its content. It is attested to the manifest of the image’s platform if cosign.enable is set.

Type: null or absolute path

Default:

image.passthru.sbom or null

Example:

"${self.packages.x86_64-linux.sbom}/sbom.cdx.json"

registries

Configuration for the Docker registries to be used. The key is the name of the registry (e.g., ghcr.io). The index is pushed untagged to all registries, signed and attested in the first one, and its signatures and attestations are copied to the others, before it is tagged.

Type: attribute set of (submodule)

Default:

{ }

registries.<name>.enable

Whether to enable pushing to the registry.

Type: boolean

Default:

true

Example:

false

registries.<name>.name

The name/domain of the registry

Type: string

Default:

"‹name›"

registries.<name>.password

Password for pushing to the registry.

Type: string

registries.<name>.repo

Fully qualified name of the Docker image in the registry (e.g., mirkolenz/flocken).

Type: string

registries.<name>.tls

Whether to use TLS, insecure skips the certificate verification and disabled uses plain HTTP.

Type: one of “enabled”, “insecure”, “disabled”

Default:

"enabled"

registries.<name>.username

Username for pushing to the registry.

Type: string

tags

List of custom/additional tags to be added to the manifest.

Type: list of string

Default:

[ ]

version

Semantic version of the image (e.g., v1.0.0 or 1.0.0).

Type: string

Default:

"$VERSION"