Skip to main content

Utilisation du registre de conteneurs

Vous pouvez stocker et gérer des images Docker et OCI dans Container registry, qui utilise l’espace de noms du package https://containers.HOSTNAME.

Remarque : Container registry est actuellement en version bêta pour GitHub Enterprise Server et susceptible d’être modifié.

GitHub Packages et l’isolation de sous-domaine doivent être activés pour utiliser Container registry. Pour plus d’informations, consultez « Utilisation du registre de conteneurs ».

À propos du Container registry

Le Container registry stocke des images conteneur dans votre organisation ou compte personnel et vous permet d’associer une image à un dépôt. Vous pouvez choisir d’hériter des autorisations d’un dépôt ou de définir des autorisations granulaires indépendamment d’un dépôt. Vous pouvez également accéder aux images conteneur publiques de manière anonyme.

Pour utiliser le Container registry sur GitHub Enterprise Server, votre administrateur de site doit d’abord configurer GitHub Packages pour votre instance et activer l’isolation de sous-domaine. Pour plus d’informations, consultez « Bien démarrer avec GitHub Packages pour votre entreprise » et « Activation de l’isolation de sous-domaine ».

À propos de la prise en charge du Container registry

Le Container registry prend actuellement en charge les formats d’image conteneur suivants :

Lors de l’installation ou de la publication d’une image Docker, le Container registry prend en charge les couches étrangères, telles que les images Windows.

Authentification auprès du Container registry

Vous avez besoin d’un jeton d’accès pour publier, installer et supprimer des packages privés, internes et publics.

Vous pouvez utiliser un personal access token pour vous authentifier sur GitHub Packages ou l’API GitHub Enterprise Server. Quand vous créez un personal access token, vous pouvez l’attribuer à différentes étendues selon vos besoins. Pour plus d’informations sur les étendues liées aux packages pour un personal access token, consultez « À propos des autorisations pour les packages GitHub ».

Pour vous authentifier sur un registre GitHub Packages dans un workflow GitHub Actions, vous pouvez utiliser :

  • GITHUB_TOKEN pour publier des packages associés au dépôt du workflow.
  • un personal access token avec au moins l’étendue packages:read pour installer des packages associés à d’autres dépôts privés (auxquels GITHUB_TOKEN ne peut pas accéder).

Authentification dans un workflow GitHub Actions

Ce registre prend en charge les autorisations granulaires. Pour les registres prenant en charge les autorisations granulaires, si votre workflow utilise un personal access token pour s’authentifier auprès d’un registre, nous vous recommandons vivement de mettre à jour votre workflow pour utiliser GITHUB_TOKEN. Pour obtenir des conseils sur la mise à jour de vos workflows qui s’authentifient auprès d’un registre avec un personal access token, consultez « Mise à niveau d’un workflow qui accède à un registre à l’aide d’un personal access token ».

Pour plus d’informations sur le secret GITHUB_TOKEN, consultez « Authentification dans un workflow ». Pour plus d’informations sur les meilleures pratiques d’utilisation d’un registre dans des actions, consultez « Durcissement de la sécurité pour GitHub Actions ».

Vous pouvez également choisir d’accorder des autorisations d’accès aux packages indépendamment pour GitHub Codespaces et GitHub Actions. Pour plus d’informations, consultez « Garantie d’accès des codespaces à votre package » et « Garantie de l’accès du workflow à votre package ».

Authentification avec un personal access token

Veillez à remplacer HOSTNAME par le nom d’hôte ou l’adresse IP de your GitHub Enterprise Server instance dans les exemples ci-dessous.

  1. Créez un personal access token avec les étendues appropriées pour les tâches que vous souhaitez accomplir. Si votre organisation exige l’authentification unique, vous devez l’activer pour votre nouveau jeton.

    Remarque : Par défaut, lorsque vous sélectionnez l’étendue write:packages pour votre personal access token dans l’interface utilisateur, l’étendue repo est également sélectionnée. L’étendue repo offre un accès inutile et vaste à la fois, que nous vous recommandons d’éviter d’utiliser pour les workflows GitHub Actions en particulier. Pour plus d’informations, consultez « Renforcement de la sécurité pour GitHub Actions ». En guise de solution de contournement, vous pouvez juste sélectionner l’étendue write:packages pour votre personal access token dans l’interface utilisateur avec cette URL : https://HOSTNAME/settings/tokens/new?scopes=write:packages.

    • Sélectionnez l’étendue read:packages pour télécharger des images conteneur et lire leurs métadonnées.
    • Sélectionnez l’étendue write:packages pour télécharger et charger des images conteneur et lire et écrire leurs métadonnées.
    • Sélectionnez l’étendue delete:packages pour supprimer des images conteneur.

    Pour plus d’informations, consultez « Création d’un personal access token pour la ligne de commande ».

  2. Enregistrez votre personal access token. Nous vous recommandons d’enregistrer votre jeton en tant que variable d’environnement.

    $ export CR_PAT=YOUR_TOKEN
  3. À l’aide de l’interface CLI de votre type de conteneur, connectez-vous au service du Container registry sur containers.HOSTNAME.

    $ echo $CR_PAT | docker login containers.HOSTNAME -u USERNAME --password-stdin
    > Login Succeeded

Envoi (push) d’images de conteneur

Cet exemple envoie (push) la dernière version de IMAGE_NAME.

$ docker push containers.HOSTNAME/OWNER/IMAGE_NAME:latest

Cet exemple envoie (push) la version 2.5 de l’image.

$ docker push containers.HOSTNAME/OWNER/IMAGE_NAME:2.5

Lorsque vous publiez un package pour la première fois, la visibilité par défaut est privée. Quand un package est lié à un dépôt, sa visibilité dépend de celle du dépôt. Pour modifier la visibilité ou définir les autorisations d’accès, consultez « Configuration du contrôle d’accès et de la visibilité d’un package ». Vous pouvez lier un package publié à un dépôt en utilisant l’interface utilisateur ou la ligne de commande. Pour plus d’informations, consultez « Connexion d’un dépôt à un package ».

Extraction d’images de conteneur

Extraire par synthèse

Pour vous assurer de toujours utiliser la même image, vous pouvez spécifier la version exacte de l’image conteneur que vous souhaitez extraire par la valeur SHA de digest.

  1. Pour trouver la valeur SHA de synthèse, utilisez docker inspect ou docker pull, et copiez la valeur SHA après Digest:

    $ docker inspect containers.HOSTNAME/OWNER/IMAGE_NAME
  2. Supprimez l’image localement si nécessaire.

    $ docker rmi  containers.HOSTNAME/OWNER/IMAGE_NAME:latest
  3. Extrayez l’image conteneur avec @YOUR_SHA_VALUE après le nom de l’image.

    $ docker pull containers.HOSTNAME/OWNER/IMAGE_NAME@sha256:82jf9a84u29hiasldj289498uhois8498hjs29hkuhs

Extraire par nom

$ docker pull containers.HOSTNAME/OWNER/IMAGE_NAME

Extraire par nom et version

Exemple de CLI Docker montrant une image extraite par son nom et l’étiquette de version 1.14.1 :

$ docker pull containers.HOSTNAME/OWNER/IMAGE_NAME:1.14.1
  > 5e35bd43cf78: Pull complete
  > 0c48c2209aab: Pull complete
  > fd45dd1aad5a: Pull complete
  > db6eb50c2d36: Pull complete
  > Digest: sha256:ae3b135f133155b3824d8b1f62959ff8a72e9cf9e884d88db7895d8544010d8e
  > Status: Downloaded newer image for containers.HOSTNAME/orgname/image-name/release:1.14.1
  > containers.HOSTNAME/orgname/image-name/release:1.14.1

Extraire par nom et dernière version

$ docker pull containers.HOSTNAME/OWNER/IMAGE_NAME:latest
  > latest: Pulling from user/image-name
  > Digest: sha256:b3d3e366b55f9a54599220198b3db5da8f53592acbbb7dc7e4e9878762fc5344
  > Status: Downloaded newer image for containers.HOSTNAME/user/image-name:latest
  > containers.HOSTNAME/user/image-name:latest

Génération d’images conteneur

Cet exemple génère l’image hello_docker :

$ docker build -t hello_docker .

Étiquetage d’images conteneur

  1. Recherchez l’ID de l’image Docker que vous souhaitez étiqueter.

    $ docker images
    > REPOSITORY                                            TAG                 IMAGE ID            CREATED             SIZE
    > containers.HOSTNAME/my-org/hello_docker         latest              38f737a91f39        47 hours ago        91.7MB
    > containers.HOSTNAME/my-username/hello_docker    latest              38f737a91f39        47 hours ago        91.7MB
    > hello-world                                           latest              fce289e99eb9        16 months ago       1.84kB
  2. Étiquetez votre image Docker avec l’ID d’image, ainsi le nom et la destination d’hébergement de l’image souhaitée.

    $ docker tag 38f737a91f39 containers.HOSTNAME/OWNER/NEW_IMAGE_NAME:latest

Étiquetage des images conteneur

Vous pouvez utiliser des clés d’annotation prédéfinies pour ajouter des métadonnées, notamment une description, une licence et un dépôt source, à votre image conteneur. Les valeurs des clés prises en charge s’affichent dans la page du package pour l’image.

Pour la plupart des images, vous pouvez utiliser des étiquettes Docker pour ajouter les clés d’annotation à une image. Pour plus d’informations, consultez LABEL dans la documentation officielle de Docker et Clés d’annotation prédéfinies dans le dépôt opencontainers/image-spec.

Pour les images multi-arch, vous pouvez ajouter une description à l’image en ajoutant la clé d’annotation appropriée au champ annotations dans le manifeste de l’image. Pour plus d’informations, consultez « Ajout d’une description à des images multi-arch ».

Les clés d’annotation suivantes sont prises en charge dans le Container registry.

CléDescription
org.opencontainers.image.sourceURL du dépôt associé au package. Pour plus d’informations, consultez « Connexion d’un dépôt à un package ».
org.opencontainers.image.descriptionDescription en texte uniquement limitée à 512 caractères. Cette description s’affiche sur la page du package, sous le nom du package.
org.opencontainers.image.licensesUn identificateur de licence SPDX tel que « MIT », limité à 256 caractères. La licence apparaît dans la page du package, dans la barre latérale « Détails ». Pour plus d’informations, consultez Liste des licences SPDX.

Pour ajouter une clé en tant qu’étiquette Docker, nous recommandons d’utiliser l’instruction LABEL dans votre Dockerfile. Par exemple, si vous êtes l’utilisateur monalisa, que vous possédez my-repo et que votre image est distribuée selon les termes de la licence MIT, vous devez ajouter les lignes suivantes à votre Dockerfile :

LABEL org.opencontainers.image.source=https://HOSTNAME/monalisa/my-repo
LABEL org.opencontainers.image.description="My container image"
LABEL org.opencontainers.image.licenses=MIT

Vous pouvez également ajouter des étiquettes à une image au moment de la génération avec la commande docker build.

$ docker build \
 --label "org.opencontainers.image.source=https://HOSTNAME/monalisa/my-repo" \
 --label "org.opencontainers.image.description=My container image" \
 --label "org.opencontainers.image.licenses=MIT"

Ajout d’une description à des images multi-arch

Une image multi-arch est une image qui prend en charge plusieurs architectures. Elle fonctionne en référençant une liste d’images, chacune prenant en charge une architecture différente, au sein d’un même manifeste.

La description qui apparaît dans la page du package d’une image multi-arch s’obtient à partir du champ annotations dans le manifeste de l’image. Comme les étiquettes Docker, les annotations offrent un moyen d’associer des métadonnées à une image et prennent en charge les clés d’annotation prédéfinies. Pour plus d’informations, consultez Annotations dans le dépôt opencontainers/image-spec.

Pour fournir une description d’une image multi-arch, définissez une valeur pour la clé org.opencontainers.image.description dans le champ annotations du manifeste, comme suit.

"annotations": {
  "org.opencontainers.image.description": "My multi-arch image"
}

Par exemple, l’étape du workflow GitHub Actions suivante génère et pousse une image multi-arch. Le paramètre outputs définit la description de l’image.

# Ce workflow utilise des actions qui ne sont pas certifiées par GitHub.
# Elles sont fournies par un tiers et régies par
# des conditions d’utilisation du service, une politique de confidentialité et un support distincts.
# documentation en ligne.

- name: Build and push Docker image
  uses: docker/build-push-action@ad44023a93711e3deb337508980b4b5e9bcdc5dc
  with:
    context: .
    file: ./Dockerfile
    platforms: ${{ matrix.platforms }}
    push: true
    outputs: type=image,name=target,annotation-index.org.opencontainers.image.description=My multi-arch image