Publication et installation d’un package avec GitHub Actions

À propos de GitHub Packages avec GitHub Actions

GitHub Actions vous aide à automatiser vos workflows de développement logiciel au même endroit où vous stockez le code et collaborez sur les demandes de tirage et les problèmes. Vous pouvez écrire des tâches individuelles, appelées actions, et les combiner pour créer un workflow personnalisé. Avec GitHub Actions, vous pouvez créer des fonctionnalités d’intégration continue (CI) et de déploiement continu (CD) de bout en bout directement dans votre dépôt. Pour plus d’informations, consultez « Découvrir GitHub Actions ».

Vous pouvez étendre les fonctionnalités CI et CD de votre dépôt en publiant ou en installant des packages dans le cadre de votre workflow.

Authentification auprès des registres de packages avec des autorisations granulaires

Certains registres GitHub Packages prennent en charge les autorisations granulaires. Cela signifie que vous pouvez choisir de permettre aux packages d’être délimités à un utilisateur ou à une organisation ou d’être liés à un dépôt. Pour obtenir la liste des registres prenant en charge les autorisations granulaires, consultez « À propos des autorisations pour les packages GitHub ».

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 « Publication et installation d’un package avec GitHub Actions ».

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 GITHUB_TOKEN, consultez « Authentification par jeton automatique ». Pour plus d’informations sur les bonnes pratiques lors de l’utilisation d’un registre dans des actions, consultez « Durcissement de la sécurité pour GitHub Actions ».

Authentification auprès des registres de packages avec des autorisations limitées au dépôt

Certains registres GitHub Packages prennent uniquement en charge les autorisations limitées au dépôt, ils ne prennent pas en charge les autorisations granulaires. Pour obtenir la liste de ces registres, consultez « À propos des autorisations pour les packages GitHub ».

Si vous voulez que votre workflow accède à un registre GitHub Packages qui ne prend pas en charge les autorisations granulaires, nous recommandons d’utiliser GITHUB_TOKEN que GitHub crée automatiquement pour votre dépôt quand vous activez GitHub Actions. Vous devez définir les autorisations de ce jeton d’accès dans le fichier de workflow afin d’octroyer l’accès en lecture pour l’étendue contents et l’accès en écriture pour l’étendue packages. Pour les duplications, GITHUB_TOKEN reçoit un accès en lecture pour le dépôt parent. Pour plus d’informations, consultez « Authentification par jeton automatique ».

Vous pouvez référencer le GITHUB_TOKEN de votre fichier de workflow à l’aide du contexte {{secrets.GITHUB_TOKEN}}. Pour plus d’informations, consultez « Authentification par jeton automatique ».

À propos des autorisations et de l’accès aux packages

Packages limités aux utilisateurs ou aux organisations

Les registres qui prennent en charge les autorisations granulaires autorisent les utilisateurs à créer et à administrer des packages en tant que ressources autonomes au niveau de l’organisation. Les packages peuvent être délimités à une organisation ou à un compte personnel, et vous pouvez personnaliser l’accès à chacun de vos packages séparément des autorisations de dépôt.

Tous les workflows accédant aux registres qui prennent en charge les autorisations granulaires doivent utiliser GITHUB_TOKEN au lieu d’un personal access token. Pour plus d’informations sur les bonnes pratiques de sécurité, consultez « Durcissement de la sécurité pour GitHub Actions ».

Packages limités aux dépôts

Lorsque vous activez GitHub Actions, GitHub installe une application GitHub sur votre dépôt. Le secret GITHUB_TOKEN est un jeton d’accès d’installation d’application GitHub. Vous pouvez utiliser le jeton d’accès d’installation pour vous authentifier au nom de l’application GitHub installée sur votre dépôt. Les autorisations du jeton sont limitées au dépôt qui contient votre workflow. Pour plus d’informations, consultez « Authentification par jeton automatique ».

GitHub Packages vous permet d’envoyer (push) et d’extraire des packages via le secret GITHUB_TOKEN disponible pour un workflow GitHub Actions.

Autorisations et paramètres d’accès par défaut pour les packages, modifiés via des workflows

Pour les packages dans des registres prenant en charge les autorisations granulaires, quand vous créez, installez, modifiez ou supprimez un package via un workflow, certains paramètres d’accès et autorisations par défaut sont utilisés pour garantir l’accès des administrateurs au workflow. Vous pouvez également ajuster ces paramètres d’accès. Pour obtenir la liste des registres prenant en charge les autorisations granulaires, consultez « À propos des autorisations pour les packages GitHub ».

Par exemple, par défaut, si un workflow crée un package en utilisant le secret GITHUB_TOKEN :

• Le package hérite du modèle de visibilité et d’autorisations du dépôt dans lequel le workflow est exécuté.
• Les administrateurs du dépôt dans lequel le workflow est exécuté deviennent administrateurs du package une fois celui-ci créé.

Voici d’autres exemples montrant comment les autorisations par défaut fonctionnent pour des workflows qui gèrent des packages.

Vous pouvez également ajuster l’accès aux packages d’une manière plus granulaire ou ajuster en partie le comportement des autorisations par défaut. Pour plus d’informations, consultez « Configuration du contrôle d’accès et de la visibilité d’un package ».

Publication d’un package à l’aide d’une action

Vous pouvez utiliser GitHub Actions pour publier automatiquement des packages dans le cadre de votre flux d’intégration continue (CI). Cette approche du déploiement continu (CD) vous permet d’automatiser la création de nouvelles versions de package si le code répond à vos normes de qualité. Par exemple, vous pourriez créer un workflow qui exécute des tests de CI chaque fois qu’un développeur envoie du code à une branche particulière. Si les tests réussissent, le workflow peut publier une nouvelle version de package sur GitHub Packages.

Les étapes de configuration varient selon le client de package. Pour des informations générales sur la configuration d’un workflow pour GitHub Actions, consultez « Utilisation de flux de travail ».

L’exemple suivant montre comment utiliser GitHub Actions pour générer votre application , puis créer automatiquement une image Docker et la publier sur GitHub Packages. Les paramètres pertinents sont expliqués dans le code. Pour avoir des détails complets sur chaque élément d’un workflow, consultez « Workflow syntax for GitHub Actions ».

Créez un fichier de workflow dans votre dépôt (par exemple .github/workflows/deploy-image.yml), puis ajoutez le YAML suivant.

#
name: Create and publish a Docker image

# Configures this workflow to run every time a change is pushed to the branch called `release`.
on:
  push:
    branches: ['release']

# Defines two custom environment variables for the workflow. These are used for the Container registry domain, and a name for the Docker image that this workflow builds.
env:
  REGISTRY: ghcr.io
  IMAGE_NAME: ${{ github.repository }}

# There is a single job in this workflow. It's configured to run on the latest available version of Ubuntu.
jobs:
  build-and-push-image:
    runs-on: ubuntu-latest
    # Sets the permissions granted to the `GITHUB_TOKEN` for the actions in this job.
    permissions:
      contents: read
      packages: write
      # 
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
      # Uses the `docker/login-action` action to log in to the Container registry registry using the account and password that will publish the packages. Once published, the packages are scoped to the account defined here.
      - name: Log in to the Container registry
        uses: docker/login-action@65b78e6e13532edd9afa3aa52ac7964289d1a9c1
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
      # This step uses [docker/metadata-action](https://github.com/docker/metadata-action#about) to extract tags and labels that will be applied to the specified image. The `id` "meta" allows the output of this step to be referenced in a subsequent step. The `images` value provides the base name for the tags and labels.
      - name: Extract metadata (tags, labels) for Docker
        id: meta
        uses: docker/metadata-action@9ec57ed1fcdbf14dcef7dfbe97b2010124a938b7
        with:
          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
      # This step uses the `docker/build-push-action` action to build the image, based on your repository's `Dockerfile`. If the build succeeds, it pushes the image to GitHub Packages.
      # It uses the `context` parameter to define the build's context as the set of files located in the specified path. For more information, see "[Usage](https://github.com/docker/build-push-action#usage)" in the README of the `docker/build-push-action` repository.
      # It uses the `tags` and `labels` parameters to tag and label the image with the output from the "meta" step.
      - name: Build and push Docker image
        uses: docker/build-push-action@f2a1d5e99d037542a71f64918e516c093c6f3fc4
        with:
          context: .
          push: true
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}

name: Create and publish a Docker image

on:
  push:
    branches: ['release']

env:
  REGISTRY: ghcr.io
  IMAGE_NAME: ${{ github.repository }}

jobs:
  build-and-push-image:
    runs-on: ubuntu-latest

    permissions:
      contents: read
      packages: write

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Log in to the Container registry
        uses: docker/login-action@65b78e6e13532edd9afa3aa52ac7964289d1a9c1
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Extract metadata (tags, labels) for Docker
        id: meta
        uses: docker/metadata-action@9ec57ed1fcdbf14dcef7dfbe97b2010124a938b7
        with:
          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}

      - name: Build and push Docker image
        uses: docker/build-push-action@f2a1d5e99d037542a71f64918e516c093c6f3fc4
        with:
          context: .
          push: true
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}

#
name: Create and publish a Docker image

# Configures this workflow to run every time a change is pushed to the branch called `release`.
on:
  push:
    branches: ['release']

# Defines two custom environment variables for the workflow. These are used for the Container registry domain, and a name for the Docker image that this workflow builds.
env:
  REGISTRY: ghcr.io
  IMAGE_NAME: ${{ github.repository }}

# There is a single job in this workflow. It's configured to run on the latest available version of Ubuntu.
jobs:
  build-and-push-image:
    runs-on: ubuntu-latest
    # Sets the permissions granted to the `GITHUB_TOKEN` for the actions in this job.
    permissions:
      contents: read
      packages: write
      # 
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
      # Uses the `docker/login-action` action to log in to the Container registry registry using the account and password that will publish the packages. Once published, the packages are scoped to the account defined here.
      - name: Log in to the Container registry
        uses: docker/login-action@65b78e6e13532edd9afa3aa52ac7964289d1a9c1
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
      # This step uses [docker/metadata-action](https://github.com/docker/metadata-action#about) to extract tags and labels that will be applied to the specified image. The `id` "meta" allows the output of this step to be referenced in a subsequent step. The `images` value provides the base name for the tags and labels.
      - name: Extract metadata (tags, labels) for Docker
        id: meta
        uses: docker/metadata-action@9ec57ed1fcdbf14dcef7dfbe97b2010124a938b7
        with:
          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
      # This step uses the `docker/build-push-action` action to build the image, based on your repository's `Dockerfile`. If the build succeeds, it pushes the image to GitHub Packages.
      # It uses the `context` parameter to define the build's context as the set of files located in the specified path. For more information, see "[Usage](https://github.com/docker/build-push-action#usage)" in the README of the `docker/build-push-action` repository.
      # It uses the `tags` and `labels` parameters to tag and label the image with the output from the "meta" step.
      - name: Build and push Docker image
        uses: docker/build-push-action@f2a1d5e99d037542a71f64918e516c093c6f3fc4
        with:
          context: .
          push: true
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}

Ce nouveau workflow s’exécute automatiquement chaque fois que vous envoyez une modification à une branche nommée release dans le dépôt. Vous pouvez visualiser la progression sous l’onglet Actions.

Quelques minutes après la fin du workflow, le nouveau package sera visible dans votre dépôt. Pour trouver vos packages disponibles, consultez « Affichage de packages ».

Installation d’un package à l’aide d’une action

Vous pouvez installer des packages dans le cadre de votre flux de CI en utilisant GitHub Actions. Par exemple, vous pourriez configurer un workflow de façon à ce que, chaque fois qu’un développeur envoie (push) du code à une demande de tirage, le workflow résolve les dépendances en téléchargeant et en installant des packages hébergés par GitHub Packages. Ensuite, le workflow peut exécuter des tests de CI qui nécessitent les dépendances.

L’installation de packages hébergés par GitHub Packages via GitHub Actions nécessite une configuration minimale ou une authentification supplémentaire lorsque vous utilisez le secret GITHUB_TOKEN. Le transfert de données est également gratuit quand une action installe un package. Pour plus d’informations, consultez « À propos de la facturation pour GitHub Packages ».

Les étapes de configuration varient selon le client de package. Pour des informations générales sur la configuration d’un workflow pour GitHub Actions, consultez « Utilisation de flux de travail ».

Mise à niveau d’un workflow qui accède à un registre avec un personal access token

GitHub Packages prend en charge GITHUB_TOKEN pour faciliter et sécuriser l’authentification dans vos workflows. Si vous utilisez un registre qui prend en charge les autorisations granulaires et que 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 plus d’informations sur GITHUB_TOKEN, consultez « Authentification par jeton automatique ».

L’utilisation de GITHUB_TOKEN au lieu d’un personal access token (classic) avec l’étendue repo renforce la sécurité de votre dépôt, car vous n’avez pas besoin d’utiliser un personal access token longue durée qui offre un accès inutile au dépôt où votre workflow est exécuté. Pour plus d’informations sur les bonnes pratiques de sécurité, consultez « Durcissement de la sécurité pour GitHub Actions ».

1. Accédez à la page de destination de votre package.

2. Pour vous assurer que votre package a accès à votre workflow, vous devez ajouter le dépôt dans lequel le workflow est stocké à votre package. Sous « Gérer l’accès à Actions », cliquez sur Ajouter un dépôt et recherchez le dépôt que vous souhaitez ajouter.

Par exemple, ce workflow publie une image Docker dans le Container registry et utilise ${{ secrets.GITHUB_TOKEN }} pour l’authentification. Pour plus d’informations, consultez « Set up Automated Builds » dans la documentation de Docker.

#
name: Demo Push

# This workflow runs when any of the following occur:
# - A push is made to a branch called `main` or `seed`
# - A tag starting with "v" is created
# - A pull request is created or updated
on:
  push:
    branches:
      - main
      - seed
    tags:
      - v*
  pull_request:
  # This creates an environment variable called `IMAGE_NAME ` with the value `ghtoken_product_demo`.
env:
  IMAGE_NAME: ghtoken_product_demo
#
jobs:
  # This pushes the image to GitHub Packages.
  push:
    runs-on: ubuntu-latest
    permissions:
      packages: write
      contents: read
      #
    steps:
      - uses: actions/checkout@v4

      - name: Build image
        run: docker build . --file Dockerfile --tag $IMAGE_NAME --label "runnumber=${GITHUB_RUN_ID}"

      - name: Log in to registry
        run: echo "${{ secrets.GITHUB_TOKEN }}" | docker login ghcr.io -u $ --password-stdin
        #
      - name: Push image
        run: |
          IMAGE_ID=ghcr.io/${{ github.repository_owner }}/$IMAGE_NAME

          # This changes all uppercase characters to lowercase.
          IMAGE_ID=$(echo $IMAGE_ID | tr '[A-Z]' '[a-z]')
          # This strips the git ref prefix from the version.
          VERSION=$(echo "${{ github.ref }}" | sed -e 's,.*/\(.*\),\1,')
          # This strips the "v" prefix from the tag name.
          [[ "${{ github.ref }}" == "refs/tags/"* ]] && VERSION=$(echo $VERSION | sed -e 's/^v//')
          # This uses the Docker `latest` tag convention.
          [ "$VERSION" == "main" ] && VERSION=latest
          echo IMAGE_ID=$IMAGE_ID
          echo VERSION=$VERSION
          docker tag $IMAGE_NAME $IMAGE_ID:$VERSION
          docker push $IMAGE_ID:$VERSION

name: Demo Push

on:
  push:
    branches:
      - main
      - seed
    tags:
      - v*
  pull_request:

env:
  IMAGE_NAME: ghtoken_product_demo

jobs:

  push:
    runs-on: ubuntu-latest
    permissions:
      packages: write
      contents: read

    steps:
      - uses: actions/checkout@v4
      - name: Build image
        run: docker build . --file Dockerfile --tag $IMAGE_NAME --label "runnumber=${GITHUB_RUN_ID}"
      - name: Log in to registry
        run: echo "${{ secrets.GITHUB_TOKEN }}" | docker login ghcr.io -u $ --password-stdin

      - name: Push image
        run: |
          IMAGE_ID=ghcr.io/${{ github.repository_owner }}/$IMAGE_NAME

          IMAGE_ID=$(echo $IMAGE_ID | tr '[A-Z]' '[a-z]')

          VERSION=$(echo "${{ github.ref }}" | sed -e 's,.*/\(.*\),\1,')

          [[ "${{ github.ref }}" == "refs/tags/"* ]] && VERSION=$(echo $VERSION | sed -e 's/^v//')

          [ "$VERSION" == "main" ] && VERSION=latest
          echo IMAGE_ID=$IMAGE_ID
          echo VERSION=$VERSION
          docker tag $IMAGE_NAME $IMAGE_ID:$VERSION
          docker push $IMAGE_ID:$VERSION

#
name: Demo Push

# This workflow runs when any of the following occur:
# - A push is made to a branch called `main` or `seed`
# - A tag starting with "v" is created
# - A pull request is created or updated
on:
  push:
    branches:
      - main
      - seed
    tags:
      - v*
  pull_request:
  # This creates an environment variable called `IMAGE_NAME ` with the value `ghtoken_product_demo`.
env:
  IMAGE_NAME: ghtoken_product_demo
#
jobs:
  # This pushes the image to GitHub Packages.
  push:
    runs-on: ubuntu-latest
    permissions:
      packages: write
      contents: read
      #
    steps:
      - uses: actions/checkout@v4

      - name: Build image
        run: docker build . --file Dockerfile --tag $IMAGE_NAME --label "runnumber=${GITHUB_RUN_ID}"

      - name: Log in to registry
        run: echo "${{ secrets.GITHUB_TOKEN }}" | docker login ghcr.io -u $ --password-stdin
        #
      - name: Push image
        run: |
          IMAGE_ID=ghcr.io/${{ github.repository_owner }}/$IMAGE_NAME

          # This changes all uppercase characters to lowercase.
          IMAGE_ID=$(echo $IMAGE_ID | tr '[A-Z]' '[a-z]')
          # This strips the git ref prefix from the version.
          VERSION=$(echo "${{ github.ref }}" | sed -e 's,.*/\(.*\),\1,')
          # This strips the "v" prefix from the tag name.
          [[ "${{ github.ref }}" == "refs/tags/"* ]] && VERSION=$(echo $VERSION | sed -e 's/^v//')
          # This uses the Docker `latest` tag convention.
          [ "$VERSION" == "main" ] && VERSION=latest
          echo IMAGE_ID=$IMAGE_ID
          echo VERSION=$VERSION
          docker tag $IMAGE_NAME $IMAGE_ID:$VERSION
          docker push $IMAGE_ID:$VERSION