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

# Single image
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"

# Multi-image project: call once per image, same --project and --revision
imglife register \
  --image    registry.example.com/apps/myservice-api:1.2.0 \
  --revision "$CI_COMMIT_SHA" \
  --project  "myteam/myservice"

imglife register \
  --image    registry.example.com/apps/myservice-worker:1.2.0 \
  --revision "$CI_COMMIT_SHA" \
  --project  "myteam/myservice"

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)

Single-image project:

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

Multi-image project (e.g. api + worker):

register-api:
  stage: register
  image: registry.gitlab.com/imglife-project/imglife:latest
  script:
    - imglife register
        --image    "$CI_REGISTRY_IMAGE/api:$CI_COMMIT_TAG"
        --revision "$CI_COMMIT_SHA"
        --project  "$CI_PROJECT_PATH"
  needs: [build-api]
  rules:
    - if: $CI_COMMIT_TAG

register-worker:
  stage: register
  image: registry.gitlab.com/imglife-project/imglife:latest
  script:
    - imglife register
        --image    "$CI_REGISTRY_IMAGE/worker:$CI_COMMIT_TAG"
        --revision "$CI_COMMIT_SHA"
        --project  "$CI_PROJECT_PATH"
  needs: [build-worker, register-api]
  rules:
    - if: $CI_COMMIT_TAG

Stored record

Each register call merges into the existing array for the (project, revision) pair. A project with two images produces:

[
  {
    "applicative_image": "registry.example.com/apps/myservice-api:1.2.0",
    "base_image": "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"
  },
  {
    "applicative_image": "registry.example.com/apps/myservice-worker:1.2.0",
    "base_image": "registry.example.com/bases/alpine:3.21.3-core1.0.0",
    "revision": "a3f8b1c",
    "project": "myteam/myservice",
    "platforms": ["linux/amd64"],
    "built_at": "2026-04-01T10:01:00Z"
  }
]

Note

Calling register for an image that already has a record for the same (project, revision) replaces that entry in-place. Other images in the same package are preserved. Old single-object build.json files are read and converted automatically.

Caution

To avoid a write race condition, register jobs for the same project and revision must not run strictly in parallel. Use needs: in GitLab CI to sequence them, or chain them in a single script block.

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