registry

The registry section configures where imglife stores and retrieves build records. This is not the OCI registry where Docker images are stored — that’s configured via environment variables.

GitLab (default)

registry:
  url: https://gitlab.example.com
  project_id: 42

For GitLab.com, the OCI registry URL differs from the API URL:

registry:
  url: https://registry.gitlab.com # OCI registry (images)
  api_url: https://gitlab.com # API (Package Registry, config fetch)
  project_id: 42

Gitea

registry:
  provider: gitea
  url: https://gitea.example.com
  owner: myorg
  repo: base-images # required for imglife check auto-derive

S3 / S3-compatible

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

# Self-hosted (Garage, MinIO, Cloudflare R2, GCS)
registry:
  provider: s3
  url: http://garage.internal:3900   # endpoint override
  bucket: imglife
  region: garage
  prefix: builds

Field reference

Field	Type	Required	Default	Description
`provider`	string	no	`gitlab`	Backend: `gitlab`, `gitea`, or `s3`
`url`	string	gitlab/gitea	—	Instance URL or S3 endpoint override
`api_url`	string	no	same as `url`	Separate API URL (GitLab.com only)
`project_id`	integer	gitlab	—	GitLab project numeric ID
`owner`	string	gitea	—	Gitea user or organisation
`repo`	string	gitea	—	Gitea repository name
`bucket`	string	s3	—	S3 bucket name
`region`	string	no (s3)	`us-east-1`	AWS region or custom string
`prefix`	string	no (s3)	—	Key prefix inside the bucket
`insecure_registries`	[]string	no	—	OCI registries to contact over plain HTTP
`config_ref`	string	no	`main`	Git ref for `imglife.yaml` auto-fetch by `check`

Credentials

Provider	Environment variable	Required scopes
`gitlab`	`GITLAB_TOKEN`	`api`, `read_packages`, `write_packages`, `read_registry`, `write_registry`
`gitea`	`GITEA_TOKEN`	`package` scope
`s3`	`AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY`	`s3:GetObject`, `s3:PutObject`, `s3:DeleteObject`, `s3:ListBucket`

Insecure registries

For local development with a plain-HTTP registry:

registry:
  url: http://registry.local:5000
  project_id: 1
  insecure_registries:
    - registry.local:5000

imglife automatically treats hosts with an http:// URL as insecure. The insecure_registries list is for additional hosts beyond the main URL.

Auto-derive for `imglife check`

When applicative projects run imglife check, imglife can automatically fetch the base-images imglife.yaml from the registry to compare versions. The config_ref field controls which git ref to use:

registry:
  url: https://gitlab.example.com
  project_id: 42
  config_ref: main # default

For Gitea, repo is also required:

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