Package Registry

What is the Package Registry?

imglife uses a Package Registry as a lightweight database for build records. Each time an applicative image is built and registered, a JSON metadata file is stored in the package registry. imglife can then query this data to generate status reports and answer questions like:

Which applications are currently using bases/alpine:3.19?
Has myservice been rebuilt since the last base image update?
Are there any orphaned build records for images that no longer exist?

Supported backends

imglife supports three backends, all accessed through the same interface:

Provider	Implementation	Use case
GitLab	GitLab Generic Package Registry	Default; works with self-hosted and GitLab.com
Gitea	Gitea Generic Package Registry	Gitea self-hosted instances
S3	AWS S3 or any S3-compatible storage	Air-gapped, MinIO, Garage, Cloudflare R2, etc.

Configure the provider in the registry: section of your imglife.yaml.

What a build record contains

A build record is a small JSON file:

{
  "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", "linux/arm64"],
  "built_at": "2026-04-01T10:00:00Z",
  "custom_fields": {}
}

Records are stored using the image tag as the key. Publishing a new record for the same tag overwrites the previous one.

Publishing a build record

In your applicative CI pipeline, after building and pushing your 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"

imglife reads the BASE_IMAGE_REF OCI label from the pushed image to auto-detect the base if --base is omitted and the label is present.

See imglife register for the full reference.

Querying build records

imglife app list

imglife app list --project myteam/myservice

imglife app list --detailed

imglife app list --output json

Purging stale records

Build records accumulate over time. imglife app purge removes old records according to a retention policy:

imglife app purge --keep 3 --dry-run   # preview: keep 3 most recent revisions per project
imglife app purge --keep 3             # apply

Relationship with imglife cleanup: cleanup reads all surviving build records to determine which base images are still referenced — those base images are protected from deletion even if they are old. Running app purge before cleanup in the same pipeline lets cleanup immediately free base images that were only referenced by the now-deleted records.

See imglife app for details.

How `imglife status` uses the registry

When you run imglife status, imglife:

Lists all images declared in the build: section.
Queries the Package Registry for all build records.
Cross-references which applicative images are built on which base.
Renders the three-tier status Markdown table.

The result is a comprehensive snapshot of your entire image inventory, including which applicative projects are up-to-date.

Provider configuration

registry:
  url: https://gitlab.example.com
  project_id: 42 #
  api_url: https://gitlab.com # only needed for gitlab.com

Credentials: GITLAB_TOKEN with read_packages, write_packages scopes.

registry:
  provider: gitea
  url: https://gitea.example.com
  owner: myorg
  repo: base-images

Credentials: GITEA_TOKEN with package scope.

registry:
  provider: s3
  bucket: imglife-builds
  region: eu-west-1

Credentials: AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY.

registry:
  provider: s3
  url: http://garage.internal:3900 # endpoint override
  bucket: imglife
  region: garage
  prefix: builds

Same credentials: AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY.