Skip to main content
Nous publions des mises à jour fréquentes de notre documentation, et la traduction de cette page peut encore être en cours. Pour obtenir les informations les plus actuelles, consultez la documentation anglaise.

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://ghcr.io.

GitHub Packages est disponible avec GitHub Free, GitHub Pro, GitHub Free pour les organisations, GitHub Team, GitHub Enterprise Cloud, GitHub Enterprise Server 3.0 ou version ultérieure et GitHub AE.
GitHub Packages n’est pas disponible pour les référentiels privés appartenant à des comptes qui utilisent des plans par référentiel hérités. En outre, les comptes qui utilisent des plans par référentiel hérités n’ont pas accès au Container registry puisque ces comptes sont facturés par référentiel. Pour plus d’informations, consultez « Produits de GitHub ».

À 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.

À 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

GitHub Packages prend uniquement en charge l’authentification à l’aide d’un personal access token (classic). Pour plus d’informations, consultez « Création d’un personal access token ».

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 (classic) pour vous authentifier sur GitHub Packages ou l’API GitHub. Quand vous créez un personal access token (classic), 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 (classic), 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 (classic) avec au moins l’étendue read:packages 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 GitHub Actions 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 ».

Remarque : la capacité des workflows GitHub Actions de supprimer et de restaurer des packages à l’aide de l’API REST est actuellement en version bêta publique et susceptible d’être modifiée.

Vous pouvez utiliser un GITHUB_TOKEN dans un workflow GitHub Actions pour supprimer ou restaurer un package via l’API REST si le jeton dispose de l’autorisation admin sur le package. Les référentiels qui publient des packages à l’aide d’un workflow et les référentiels que vous avez explicitement connectés à des packages se voient automatiquement accorder l’autorisation admin aux packages dans le référentiel.

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 (classic)

GitHub Packages prend uniquement en charge l’authentification à l’aide d’un personal access token (classic). Pour plus d’informations, consultez « Création d’un personal access token ».

  1. Créez un personal access token (classic) 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 (classic) 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 (classic) dans l’interface utilisateur avec cette URL : https://github.com/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 (classic). 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 ghcr.io.

    $ echo $CR_PAT | docker login ghcr.io -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 ghcr.io/OWNER/IMAGE_NAME:latest

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

$ docker push ghcr.io/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 ghcr.io/OWNER/IMAGE_NAME
  2. Supprimez l’image localement si nécessaire.

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

    $ docker pull ghcr.io/OWNER/IMAGE_NAME@sha256:82jf9a84u29hiasldj289498uhois8498hjs29hkuhs

Extraire par nom

$ docker pull ghcr.io/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 ghcr.io/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 ghcr.io/orgname/image-name/release:1.14.1
  > ghcr.io/orgname/image-name/release:1.14.1

Extraire par nom et dernière version

$ docker pull ghcr.io/OWNER/IMAGE_NAME:latest
  > latest: Pulling from user/image-name
  > Digest: sha256:b3d3e366b55f9a54599220198b3db5da8f53592acbbb7dc7e4e9878762fc5344
  > Status: Downloaded newer image for ghcr.io/user/image-name:latest
  > ghcr.io/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
    > ghcr.io/my-org/hello_docker         latest              38f737a91f39        47 hours ago        91.7MB
    > ghcr.io/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 ghcr.io/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://github.com/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://github.com/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