build

The build section defines how imglife generates Dockerfiles from templates and pushes base images to your registry.

Structure

build:
  core_version: "1.0.0"
  registry: registry.example.com/bases
  builder: imglife-builder # optional buildx builder name
  platforms: [linux/amd64, linux/arm64]
  sbom: true
  tag_format: "{registry}/{folder}:{mirror-tag}-{build_name}"

  hooks:
    post_image_build:
      - cmd: cosign sign --yes {image}
        timeout: 120s

  images:
    - name: alpine
      folder: images/alpine
      type: core
      mirror_image: registry.example.com/mirrors/alpine
      mirror_tag: "3.21.3"
      version: "3.21.3"

Top-level fields

Field	Type	Required	Default	Description
`core_version`	string	yes	—	Organisation build version; bumped when your templates/config change
`registry`	string	yes	—	Base path where built images are pushed
`builder`	string	no	—	`docker buildx` builder instance name; omit to use the default
`platforms`	[]string	no	`[linux/amd64]`	Default target platforms
`sbom`	bool	no	`false`	Attach SBOM attestation (requires buildx)
`tag_format`	string	no	`{registry}/{folder}:{mirror-tag}-{build_name}`	Token template for the full image reference (see Tag format)
`hooks.post_image_build`	[]Hook	no	—	Commands to run after each image is built and pushed

Image fields

Field	Type	Required	Default	Description
`name`	string	yes	—	Image name (used in logs and the `{build_name}` token)
`folder`	string	yes	—	Registry sub-path for the built image (the `{folder}` token), e.g. `images/alpine`
`type`	string	yes	—	`core`, `spe`, or `spe-dev` (affects EOL checking)
`mirror_image`	string	yes	—	Mirror image used as `FROM` (must not include a tag)
`mirror_tag`	string	no	latest resolved	Pin a specific mirror tag; omit to auto-resolve the latest
`version`	string	conditional	—	Required for `spe`/`spe-dev`; forbidden for `core` (which uses `core_version`)
`tmpl`	string	conditional	`templates/core.tmpl`	Template path; required for `spe`/`spe-dev`, forbidden for `core`
`args`	map[string]string	no	—	Additional `--build-arg` values
`platforms`	[]string	no	inherits top-level	Per-image platform override
`sbom`	bool	no	inherits top-level	Per-image SBOM override
`hooks`	Hooks	no	—	Per-image hooks

Image types

Type	Description	EOL checked	Appears in status
`core`	Production base image	Yes	Yes
`spe`	Special-purpose variant	Yes	Yes
`spe-dev`	Development variant	No	No

Dockerfile templates

imglife renders Dockerfile.tmpl using Go’s text/template engine. The following variables are available:

Variable	Example	Description
`{{.MirrorImage}}`	`registry.example.com/mirrors/alpine:3.21.3`	Fully-resolved mirror image reference (tag already appended)
`{{.CoreVersion}}`	`1.0.0`	Organisation core version (`build.core_version`)
`{{.Version}}`	`3.21.3`	`core_version` for `core` images, or the image `version`
`{{.Name}}`	`alpine`	Image name
`{{.Type}}`	`core`	Image type (`core`, `spe`, `spe-dev`)
`{{.OSFamily}}`	`alpine`	OS family auto-detected from the mirror image
`{{.Args}}`	`{KEY: value}`	Map of the image’s `args`

Example Dockerfile.tmpl:

FROM {{ .MirrorImage }}

RUN apk add --no-cache \
    ca-certificates \
    tzdata \
    curl

# OCI labels are injected automatically by imglife

imglife injects these OCI labels on every build:

org.opencontainers.image.created   = <build timestamp>
org.opencontainers.image.revision  = <git SHA>
org.opencontainers.image.source    = <project URL>
org.opencontainers.image.base.name = <mirror image>
org.opencontainers.image.base.digest = <mirror digest>

Tag format

tag_format is rendered with single-brace tokens (not Go templates). The default is {registry}/{folder}:{mirror-tag}-{build_name}, which produces the full destination reference. You can customise it:

build:
  tag_format: "{registry}/{folder}:{mirror-tag}-org{version}"
  # Produces: registry.example.com/bases/images/alpine:3.21.3-org1.0.0

Available tokens:

Token	Expands to	Example
`{registry}`	`build.registry`	`registry.example.com/bases`
`{folder}`	the image `folder`	`images/alpine`
`{type}`	the image `type`	`core`
`{version}`	`core_version` for `core`, otherwise the image `version`	`1.0.0`
`{build_name}`	`{type}{version}`	`core1.0.0`
`{mirror-tag}`	the resolved mirror tag	`3.21.3`

Validation rules: unknown tokens are rejected, {registry} is required, and at least one of {build_name}, {type}, or {version} must be present.

Multi-architecture builds

build:
  platforms: [linux/amd64, linux/arm64]
  builder: imglife-builder # buildx builder must support multi-arch

When platforms has more than one entry, imglife uses docker buildx build with --push to publish a multi-arch manifest. A builder with docker-container driver is required.

Output-dir mode

Instead of building and pushing, imglife can write Docker build contexts to a local directory for consumption by external builders (Kaniko, Buildah):

imglife build --output-dir /tmp/imglife-contexts

Each context directory contains a Dockerfile, a build.json manifest, and any required files. See imglife build for the full reference.

Hooks

build:
  hooks:
    post_image_build:
      - cmd: cosign sign --yes {image}
        timeout: 120s
        continue_on_error: false

In hook commands, the literal placeholder {image} is replaced with the fully-qualified image reference including tag. It is the only substitution available; the command is run via sh -c.

Each hook entry accepts cmd (required), timeout (optional Go duration, e.g. 120s), and continue_on_error (optional bool).