imglife build

Synopsis

imglife build [flags]

For each image in build.images, imglife:

Renders Dockerfile.tmpl with the image variables.
Injects OCI labels (build date, git revision, base image reference).
Calls docker build (or docker buildx build for multi-arch).
Pushes the image to the configured registry.
Runs post_image_build hooks.

Flags

Flag	Default	Description
`--dry-run`	`false`	Render Dockerfiles without building or pushing
`--list`	`false`	Print what would be built and exit
`--output-dir string`	—	Write build contexts to a directory instead of building

Examples

# Build all configured images
imglife build

# Preview — show which images would be built
imglife build --list

# Dry-run — render Dockerfiles, skip docker build
imglife build --dry-run

# Write build contexts for external builder (Kaniko, Buildah)
imglife build --output-dir /tmp/build-contexts

Output-dir mode

When --output-dir is set, imglife writes one subdirectory per image instead of building:

/tmp/build-contexts/
  alpine/
    Dockerfile          # rendered from template
    build.json          # build manifest (tag, platforms, etc.)
  golang/
    Dockerfile
    build.json

The build.json manifest contains:

{
  "tag": "registry.example.com/bases/alpine:3.21.3-core1.0.0",
  "platforms": ["linux/amd64", "linux/arm64"],
  "labels": { "org.opencontainers.image.created": "..." }
}

This mode is designed for CI environments using rootless builders like Kaniko or Buildah that require the build context as files. See Base Images — GitLab CI for a complete example.

Multi-architecture builds

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

build:
  platforms: [linux/amd64, linux/arm64]
  builder: imglife-builder

Set up the builder:

docker buildx create \
  --name imglife-builder \
  --driver docker-container \
  --bootstrap

OCI labels injected

imglife passes these as --label flags to docker build, populating the image’s config.Labels. When a buildx builder is configured (build.builder), the same values are also set as OCI manifest annotations via --annotation, making them visible with docker buildx imagetools inspect. For multi-platform builds, annotations are additionally set at the image-index level.

Label / Annotation	Value	Condition
`org.opencontainers.image.version`	Produced image version	always
`org.opencontainers.image.base.name`	Full mirror image reference	always
`org.opencontainers.image.created`	Build timestamp (RFC 3339)	always
`imglife.type`	Image type (`core`, `spe`, …)	always
`imglife.core-version`	`build.core_version` value	always
`org.opencontainers.image.base.digest`	Mirror image SHA256 digest	if resolvable
`imglife.platforms`	Target platforms (`linux/amd64,…`)	if configured
`org.opencontainers.image.revision`	`$IMGLIFE_REVISION` env var	if env var set
`org.opencontainers.image.source`	`$IMGLIFE_SOURCE` env var	if env var set
`org.opencontainers.image.url`	`$IMGLIFE_URL` env var	if env var set

These labels are consumed by imglife register to auto-detect the base image and platforms.

Set the optional variables in your CI job to populate the traceability labels:

# GitLab CI — build-bases job
variables:
  IMGLIFE_REVISION: $CI_COMMIT_SHA          # → org.opencontainers.image.revision
  IMGLIFE_SOURCE: $CI_PROJECT_URL           # → org.opencontainers.image.source
  IMGLIFE_URL: $CI_PROJECT_URL/container_registry  # → org.opencontainers.image.url

Summary report

After each run (not in --list mode), imglife prints a summary to stdout:

  Build Summary · 12.1s
  ───────────────────────────────────
  Base images in config   4
  ├─ Built                2
  ├─ Already exists       2
  └─ Errors               0

In --dry-run mode the header is prefixed with [dry-run]. Set NO_COLOR=1 or TERM=dumb to disable ANSI colors.

Exit codes

Code	Meaning
`0`	All images built and pushed successfully
`1`	One or more builds failed