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
        extract: minor

Top-level fields

Field	Type	Required	Default	Description
`hooks.post_sync`	[]Hook	no	—	Commands to run after all sync entries complete

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)
`lifecycle`	Lifecycle	no	EOL tracking for this image
`hooks`	Hooks	no	Per-entry hooks

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
    extract: minor # how to derive the cycle from the tag

`extract` value	Example tag	Resolved cycle
`minor`	`3.21.3`	`3.21`
`major`	`22.04`	`22`
`patch`	`1.22.1`	`1.22.1`
(none)	`lts`	`lts`

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

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:

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.