imglife check

Synopsis

imglife check [flags]

Designed for applicative CI pipelines. Verifies that the base image used in a build is the latest available version and not approaching end-of-life. Can block the CI job with --strict if the base is outdated or at EOL.

Flags

Flag	Required	Description
--base string	yes	Fully-qualified base image tag to check (e.g. registry.example.com/bases/alpine:3.21.3-core1.0.0)
--config-url string	no	URL to fetch the base-images imglife.yaml (overrides auto-derive)
--eol-data-url string	no	URL to fetch the EOL data file (overrides auto-derive)
--strict	no	Exit non-zero if base is outdated, at EOL, or if the EOL data for its cycle is missing
--warn	no	Print warnings but always exit 0
--output string	no	Output format: text (default) or json

Examples

# Check a base image (informational, never fails)
imglife check --base registry.example.com/bases/alpine:3.21.3-core1.0.0

# Strict mode: fail if base is outdated or at EOL
imglife check \
  --base registry.example.com/bases/alpine:3.21.3-core1.0.0 \
  --strict

# JSON output for programmatic parsing
imglife check \
  --base registry.example.com/bases/alpine:3.21.3-core1.0.0 \
  --output json

# With explicit config and EOL data URLs
imglife check \
  --base "$BASE_IMAGE" \
  --config-url "https://gitlab.example.com/.../imglife.yaml/raw" \
  --eol-data-url "https://gitlab.example.com/.../eol-data.yaml/raw"

How it works

1. imglife resolves the imglife.yaml of the base-images project (from the Package Registry or --config-url).
2. It finds the entry in build.images matching the checked image and tag — with several blocks sharing a folder, the one whose version line accepts the tag wins.
3. It compares the current tag with the latest available tag of that line, so an app on JDK 8 is never told to upgrade to a JDK 25 tag of the same repository. Without a config file, candidates are filtered by tag variant instead.
4. It queries the EOL data (from the Package Registry or --eol-data-url) to check the lifecycle status of that line’s cycle.
5. Reports the result.

JSON output

{
  "base": "registry.example.com/bases/alpine:3.21.3-core1.0.0",
  "latest": "registry.example.com/bases/alpine:3.21.3-core1.2.0",
  "up_to_date": false,
  "eol_date": "2026-11-01",
  "eol_status": "ok",
  "warnings": ["base image is outdated: latest is 3.21.3-core1.2.0"]
}

In applicative CI (GitLab example)

check:
  stage: validate
  image: registry.gitlab.com/imglife-project/imglife:latest
  variables:
    IMGLIFE_CONFIG: imglife.apps.yaml
  script:
    - |
      imglife check \
        --base "$BASE_IMAGE" \
        --strict \
        --output text

Where imglife.apps.yaml contains only the registry: section pointing to the base-images Package Registry:

registry:
  url: https://gitlab.example.com
  project_id: 42 # base-images project ID

Note

imglife check uses the base-images project’s Package Registry to auto-derive the latest available version. It does not need a full imglife.yaml with sync: or build: sections — only registry: is required.

Graceful degradation

If the Package Registry is unavailable, imglife check logs a warning and exits 0 (unless --strict is set). This prevents EOL data outages from blocking all applicative builds.

Missing EOL data

When the cycle of the checked image cannot be resolved, the reason is reported in eol_skip_reason and eol_data_missing is set to true. This is not blocking by default — only --strict turns it into exit 1.

Reason	Meaning
no EOL data for cycle <product>/<cycle>	The cycle is absent from the cache — run imglife eol update
cycle <product>/<cycle> older than any available EOL data	The image is on a cycle predating everything the provider knows
eol data unavailable	The data source itself could not be read

When the cycle is newer than anything the provider knows, the status of the previous cycle is inherited instead (if that cycle is still supported) and eol_inferred_from names it.

Exit codes

Code	Meaning
0	Base image is OK (or --warn is set)
1	Base is at/past EOL — or outdated / missing EOL data with --strict
2	Configuration or network error