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: "{{.Version}}-core{{.CoreVersion}}"

  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	{{.Version}}-core{{.CoreVersion}}	Go template for the image tag
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 (appended to registry)
folder	string	yes	—	Relative path to the directory containing Dockerfile.tmpl
type	string	yes	—	core, spe, or spe-dev (affects EOL checking)
mirror_image	string	yes	—	Mirror image to use as FROM
mirror_tag	string	yes	—	Specific mirror tag to use
version	string	yes	—	Version encoded in the image tag
tmpl	string	no	Dockerfile.tmpl	Template filename inside folder
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	Mirror image reference (no tag)
{{.MirrorTag}}	3.21.3	Mirror tag
{{.FQMI}}	registry.example.com/mirrors/alpine:3.21.3	Fully-qualified mirror image
{{.Version}}	3.21.3	Image version
{{.CoreVersion}}	1.0.0	Organisation core version
{{.Name}}	alpine	Image name
{{.Tag}}	3.21.3-core1.0.0	Full computed tag

Example Dockerfile.tmpl:

ARG MIRROR_IMAGE={{.FQMI}}
FROM ${MIRROR_IMAGE}

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

The default tag format is {{.Version}}-core{{.CoreVersion}}. You can customise it:

build:
  tag_format: "{{.Version}}-org{{.CoreVersion}}"
  # Produces: alpine:3.21.3-org1.0.0

Available template variables: .Version, .CoreVersion, .Name.

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.

Tip

For rootless builds (GitLab CI without privileged runners), set builder to a rootless BuildKit builder. See Base Images — GitLab CI for a complete setup.

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}}
        env:
          COSIGN_EXPERIMENTAL: "1"
        timeout: 120s
        continue_on_error: false

In hook commands, {{.Image}} is replaced with the fully-qualified image reference including tag.

Available variables: {{.Image}}, {{.Name}}, {{.Tag}}, {{.Registry}}.