imglife register

Synopsis

imglife register [flags]

Publishes a JSON build record to the Package Registry linking an applicative image to the base image it was built on. This record is used by imglife status to track which applications are using which base image.

Flags

Flag	Required	Description
--image string	yes	Fully-qualified applicative image tag
--base string	no	Base image used for the build (auto-detected from OCI label if absent)
--revision string	yes	Git revision (SHA) of the applicative project
--project string	yes	Project path (e.g. myteam/myservice)
--platform string	no	Platforms (space-separated, e.g. linux/amd64 linux/arm64). Auto-detected from OCI label if absent
--field key=value	no	Custom fields to include in the record (repeatable)

Examples

# Basic usage
imglife register \
  --image    registry.example.com/apps/myservice:1.2.0 \
  --base     registry.example.com/bases/alpine:3.21.3-core1.0.0 \
  --revision "$CI_COMMIT_SHA" \
  --project  "myteam/myservice"

# With custom fields
imglife register \
  --image    registry.example.com/apps/myservice:1.2.0 \
  --revision "$CI_COMMIT_SHA" \
  --project  "myteam/myservice" \
  --field    ci_pipeline_id="$CI_PIPELINE_ID" \
  --field    ci_job_url="$CI_JOB_URL"

Auto-detection from OCI labels

imglife reads image metadata from two sources, in priority order:

1. OCI manifest annotations (manifest.Annotations) — set by docker buildx build --annotation or OCI-native tools.
2. Docker image config labels (config.Labels) — set by a LABEL instruction in the Dockerfile or docker build --label. Used as a fallback when manifest annotations are absent.

Images built with imglife build always have config.Labels. When a buildx builder is configured, they also have manifest annotations. Auto-detection works in both cases.

If --base is not provided, imglife reads org.opencontainers.image.base.name from the image metadata to determine the base image.

If --platform is not provided, imglife reads imglife.platforms from the image metadata.

In applicative CI (GitLab example)

register:
  stage: register
  image: registry.gitlab.com/imglife-project/imglife:latest
  script:
    - |
      imglife register \
        --image    "$CI_REGISTRY_IMAGE:$CI_COMMIT_TAG" \
        --base     "$BASE_IMAGE" \
        --revision "$CI_COMMIT_SHA" \
        --project  "$CI_PROJECT_PATH"
  rules:
    - if: $CI_COMMIT_TAG

Stored record

{
  "image": "registry.example.com/apps/myservice:1.2.0",
  "base": "registry.example.com/bases/alpine:3.21.3-core1.0.0",
  "revision": "a3f8b1c",
  "project": "myteam/myservice",
  "platforms": ["linux/amd64"],
  "built_at": "2026-04-01T10:00:00Z"
}

Note

Publishing a record for an existing tag overwrites the previous record. This is intentional — each new build of the same tag updates the record with fresh metadata.

Summary report

After a successful publish, imglife prints a summary to stdout:

  Register · 0.4s
  ───────────────────────────────────
  Project     myteam/myservice
  Revision    a3f8b1c
  Image       registry.example.com/apps/myservice:1.2.0

Set NO_COLOR=1 or TERM=dumb to disable ANSI colors. No summary is printed if publishing fails.

Exit codes

Code	Meaning
0	Record published successfully
1	Error publishing the record