sync

The sync section defines the list of upstream images to mirror.

Structure

sync:
  hooks:
    post_sync:
      - cmd: notify-team.sh
        timeout: 30s
        continue_on_error: true

  entries:
    - source: docker.io/library/alpine
      tag_regex: '^3\.\d+\.\d+$'
      keep_last: 3
      target: registry.example.com/mirrors/alpine
      lifecycle:
        product: alpine
        track: minor

Top-level fields

Field	Type	Required	Default	Description
hooks.post_sync	[]Hook	no	—	Commands to run after all sync entries complete
platforms	[]string	no	—	Default platforms to mirror for every entry (override per entry)

Entry fields

Field	Type	Required	Description
source	string	yes	Upstream image reference (e.g. docker.io/library/alpine)
target	string	yes	Destination image reference in your registry
tag	string	one of tag/tag_regex	Sync a single fixed tag
tag_regex	string	one of tag/tag_regex	Sync all tags matching this regex
keep_last	integer	no	Keep only the N most recent matching tags
os_normalize	bool	no	Rename OS-variant tags (e.g. alpine3.21 → 1.22-alpine3.21)
check_digest	bool	no	Re-sync even if the tag already exists (digest check)
platforms	[]string	no	Restrict the mirrored platforms (overrides sync.platforms)
lifecycle	Lifecycle	no	EOL tracking for this image
hooks	Hooks	no	Per-entry hooks

Note

tag and tag_regex are mutually exclusive. Use tag for a pinned single version; use tag_regex for a range.

Tag selection

Fixed tag

- source: docker.io/library/alpine
  tag: "3.21.3"
  target: registry.example.com/mirrors/alpine

Syncs exactly one tag. Useful when you want to pin to a known-good version.

Tag regex

- source: docker.io/library/alpine
  tag_regex: '^3\.\d+\.\d+$'
  keep_last: 3
  target: registry.example.com/mirrors/alpine

imglife queries Docker Hub for all tags matching the regex, sorts them by version (semantic or date fallback), and syncs the keep_last most recent. For Docker Hub images, dates are fetched in a single API call.

Common regex patterns

Pattern	Matches
^3\.\d+\.\d+$	3.21.3, 3.20.6 — Alpine 3.x
^1\.\d+\.\d+-alpine3\.\d+$	1.22.3-alpine3.21 — Go on Alpine
^\d+\.\d+$	22.04, 24.04 — Ubuntu LTS
^\d+\.\d+\.\d+$	Any semver

Lifecycle tracking

Add lifecycle tracking to connect EOL data to a sync entry:

- source: docker.io/library/alpine
  tag_regex: '^3\.\d+\.\d+$'
  target: registry.example.com/mirrors/alpine
  lifecycle:
    product: alpine # product slug on endoflife.date
    track: minor # how to derive the cycle from the tag

track value	Example tag	Resolved cycle
minor	3.21.3	3.21
major	22.04	22

Digest re-sync

By default imglife skips tags that already exist in the target registry. Enable check_digest: true to re-sync if the upstream digest has changed (e.g. a mutable tag like latest):

- source: docker.io/library/alpine
  tag: latest
  target: registry.example.com/mirrors/alpine
  check_digest: true

Platform selection

By default imglife copies the upstream image as-is, preserving multi-arch manifest lists (OCI image indexes). Set platforms to mirror only a subset. The list resolves per entry: the per-entry platforms overrides the global sync.platforms default; an empty list copies everything.

sync:
  platforms:
    - linux/amd64 # global default for every entry
  entries:
    - source: docker.io/library/alpine
      tag_regex: '^3\.\d+\.\d+$'
      target: registry.example.com/mirrors/alpine
    - source: docker.io/library/node
      tag: "22-alpine"
      target: registry.example.com/mirrors/node
      platforms: # per-entry override
        - linux/amd64
        - linux/arm64

Behaviour by list size:

Platforms	Result
empty	Full copy — preserves the source manifest list / image as-is
one platform	A single-platform image (no index)
several	An image index reduced to that subset

Tip

Some registry UIs (e.g. GitLab Container Registry) display a manifest-list tag as Invalid tag: missing manifest digest. 0 B — cosmetic, the image still pulls and builds fine. Mirroring a single platform produces a plain image with a proper digest and size, which renders cleanly.

Hooks

sync:
  entries:
    - source: docker.io/library/alpine
      tag_regex: '^3\.\d+\.\d+$'
      target: registry.example.com/mirrors/alpine
      hooks:
        post_sync:
          - cmd: curl -s https://hooks.slack.com/... -d '{"text":"alpine synced"}'
            timeout: 10s
            continue_on_error: true

Hooks are also available at the top level of sync: and run after all entries complete. See Hooks reference for injected environment variables.

Parallelism

Control how many sync entries run concurrently:

export IMGLIFE_SYNC_PARALLELISM=4   # default: 4

Private source registries

For sources that require authentication, provide credentials via environment variables using the normalised hostname:

quay.io/prometheus/prometheus

export IMGLIFE_QUAY_IO_TOKEN=mytoken

# Source: ghcr.io/owner/image
export IMGLIFE_GHCR_IO_USERNAME=myuser
export IMGLIFE_GHCR_IO_PASSWORD=mytoken

See Credentials for the full convention.