imglife register

Synopsis

imglife register [flags]

Publie un build record JSON dans le Package Registry reliant une image applicative à l’image de base utilisée lors de la construction. Ce record est utilisé par imglife status pour suivre quelles applications utilisent quelle image de base.

Flags

Flag	Requis	Description
--image string	oui	Tag complet de l’image applicative
--base string	non	Image de base utilisée (détectée automatiquement depuis le label OCI si absent)
--revision string	oui	Révision Git (SHA) du projet applicatif
--project string	oui	Chemin du projet (ex. myteam/myservice)
--platform string	non	Plateformes (séparées par un espace, ex. linux/amd64 linux/arm64). Détectées via label OCI si absent
--field key=value	non	Champs personnalisés à inclure dans le record (répétable)

Exemples

# Image unique
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"

# Avec champs personnalisés
imglife register \
  --image    registry.example.com/apps/myservice:1.2.0 \
  --revision "$CI_COMMIT_SHA" \
  --project  "myteam/myservice" \
  --field    ci_pipeline_id="$CI_PIPELINE_ID" \
  --field    ci_job_url="$CI_JOB_URL"

# Projet multi-images : appeler une fois par image, même --project et --revision
imglife register \
  --image    registry.example.com/apps/myservice-api:1.2.0 \
  --revision "$CI_COMMIT_SHA" \
  --project  "myteam/myservice"

imglife register \
  --image    registry.example.com/apps/myservice-worker:1.2.0 \
  --revision "$CI_COMMIT_SHA" \
  --project  "myteam/myservice"

Détection automatique depuis les labels OCI

imglife lit les métadonnées de l’image depuis deux sources, dans l’ordre de priorité :

1. Annotations OCI manifest (manifest.Annotations) — définies par docker buildx build --annotation ou des outils natifs OCI.
2. Labels Docker image config (config.Labels) — définis par une instruction LABEL dans le Dockerfile ou docker build --label. Utilisés en fallback si les annotations manifest sont absentes.

Les images construites avec imglife build ont toujours des config.Labels. Quand un builder buildx est configuré, elles ont aussi des annotations manifest. La détection automatique fonctionne dans les deux cas.

Si --base n’est pas fourni, imglife lit org.opencontainers.image.base.name depuis les métadonnées de l’image pour déterminer l’image de base.

Si --platform n’est pas fourni, imglife lit imglife.platforms depuis les métadonnées de l’image.

Dans un CI applicatif (exemple GitLab)

Projet à image unique :

register:
  stage: register
  image: registry.gitlab.com/imglife-project/imglife:latest
  script:
    - |
      imglife register \
        --image    "$CI_REGISTRY_IMAGE:$CI_COMMIT_TAG" \
        --base     "$BASE_IMAGE" \
        --revision "$CI_COMMIT_SHA" \
        --project  "$CI_PROJECT_PATH"
  rules:
    - if: $CI_COMMIT_TAG

Projet multi-images (ex. api + worker) :

register-api:
  stage: register
  image: registry.gitlab.com/imglife-project/imglife:latest
  script:
    - imglife register
        --image    "$CI_REGISTRY_IMAGE/api:$CI_COMMIT_TAG"
        --revision "$CI_COMMIT_SHA"
        --project  "$CI_PROJECT_PATH"
  needs: [build-api]
  rules:
    - if: $CI_COMMIT_TAG

register-worker:
  stage: register
  image: registry.gitlab.com/imglife-project/imglife:latest
  script:
    - imglife register
        --image    "$CI_REGISTRY_IMAGE/worker:$CI_COMMIT_TAG"
        --revision "$CI_COMMIT_SHA"
        --project  "$CI_PROJECT_PATH"
  needs: [build-worker, register-api]
  rules:
    - if: $CI_COMMIT_TAG

Record stocké

Chaque appel à register fusionne le record dans le tableau existant pour la paire (projet, révision). Un projet à deux images produit :

[
  {
    "applicative_image": "registry.example.com/apps/myservice-api:1.2.0",
    "base_image": "registry.example.com/bases/alpine:3.21.3-core1.0.0",
    "revision": "a3f8b1c",
    "project": "myteam/myservice",
    "platforms": ["linux/amd64"],
    "built_at": "2026-04-01T10:00:00Z"
  },
  {
    "applicative_image": "registry.example.com/apps/myservice-worker:1.2.0",
    "base_image": "registry.example.com/bases/alpine:3.21.3-core1.0.0",
    "revision": "a3f8b1c",
    "project": "myteam/myservice",
    "platforms": ["linux/amd64"],
    "built_at": "2026-04-01T10:01:00Z"
  }
]

Note

Appeler register pour une image qui a déjà un record pour le même (projet, révision) remplace cette entrée. Les autres images du même package sont préservées. Les anciens fichiers build.json au format objet unique sont lus et convertis automatiquement.

Attention

Pour éviter une race condition d’écriture, les jobs register d’un même projet et d’une même révision ne doivent pas s’exécuter strictement en parallèle. Utiliser needs: dans GitLab CI pour les séquencer, ou les chaîner dans un seul bloc script.

Rapport de fin d’exécution

Après une publication réussie, imglife affiche un résumé sur stdout :

  Register · 0.4s
  ───────────────────────────────────
  Project     myteam/myservice
  Revision    a3f8b1c
  Image       registry.example.com/apps/myservice:1.2.0

Définir NO_COLOR=1 ou TERM=dumb pour désactiver les couleurs ANSI. Aucun résumé n’est affiché en cas d’échec de publication.

Codes de sortie

Code	Signification
0	Record publié avec succès
1	Erreur lors de la publication