Introduction à GitHub Actions avec Docker

Table des matières

Ce guide fournit une introduction à la construction de pipelines CI en utilisant Docker et GitHub Actions. Vous apprendrez à utiliser les actions GitHub officielles de Docker pour construire votre application en tant qu'image Docker et la publier sur Docker Hub. À la fin du guide, vous aurez une configuration GitHub Actions simple et fonctionnelle pour les constructions Docker. Utilisez-la telle quelle, ou étendez-la pour l'adapter à vos besoins.

Prérequis

Si vous souhaitez suivre le guide, assurez-vous d'avoir les éléments suivants :

Un compte Docker.
Une familiarité avec les Dockerfiles.

Ce guide suppose une connaissance de base des concepts de Docker mais fournit des explications pour l'utilisation de Docker dans les flux de travail GitHub Actions.

Obtenir l'application d'exemple

Ce guide est indépendant du projet et suppose que vous avez une application avec un Dockerfile.

Si vous avez besoin d'un projet d'exemple pour suivre, vous pouvez utiliser cette application d'exemple, qui inclut un Dockerfile pour construire une version conteneurisée de l'application. Alternativement, utilisez votre propre projet GitHub ou créez un nouveau dépôt à partir du modèle.

#syntax=docker/dockerfile:1

# builder installs dependencies and builds the node app
FROM node:lts-alpine AS builder
WORKDIR /src
RUN --mount=src=package.json,target=package.json \
    --mount=src=package-lock.json,target=package-lock.json \
    --mount=type=cache,target=/root/.npm \
    npm ci
COPY . .
RUN --mount=type=cache,target=/root/.npm \
    npm run build

# release creates the runtime image
FROM node:lts-alpine AS release
WORKDIR /app
COPY --from=builder /src/build .
EXPOSE 3000
CMD ["node", "."]

Configurer votre dépôt GitHub

Le flux de travail de ce guide publie l'image que vous construisez sur Docker Hub. Pour ce faire, vous devez vous authentifier avec vos informations d'identification Docker (nom d'utilisateur et jeton d'accès) dans le cadre du flux de travail GitHub Actions.

Pour des instructions sur la création d'un jeton d'accès Docker, consultez Créer et gérer les jetons d'accès.

Une fois que vous avez vos informations d'identification Docker prêtes, ajoutez-les à votre dépôt GitHub afin de pouvoir les utiliser dans GitHub Actions :

Ouvrez les Paramètres de votre dépôt.
Sous Sécurité, allez à Secrets et variables > Actions.
Sous Secrets, créez un nouveau secret de dépôt nommé DOCKER_PASSWORD, contenant votre jeton d'accès Docker.
Ensuite, sous Variables, créez une variable de dépôt DOCKER_USERNAME contenant votre nom d'utilisateur Docker Hub.

Configurer votre flux de travail GitHub Actions

Les flux de travail GitHub Actions définissent une série d'étapes pour automatiser des tâches, telles que la construction et la publication d'images Docker, en réponse à des déclencheurs comme des commits ou des pull requests. Dans ce guide, le flux de travail se concentre sur l'automatisation des constructions et des tests Docker, garantissant que votre application conteneurisée fonctionne correctement avant de la publier.

Créez un fichier nommé docker-ci.yml dans le répertoire .github/workflows/ de votre dépôt. Commencez avec la configuration de base du flux de travail :

name: Construire et publier l'image Docker

on:
  push:
    branches:
      - main
  pull_request:

Cette configuration exécute le flux de travail sur les poussées vers la branche principale et sur les pull requests. En incluant les deux déclencheurs, vous pouvez vous assurer que l'image se construit correctement pour une pull request avant sa fusion.

Extraire les métadonnées pour les balises et les annotations

Pour la première étape de votre flux de travail, utilisez le docker/metadata-action pour générer des métadonnées pour votre image. Cette action extrait des informations sur votre dépôt Git, telles que les noms de branche et les SHA de commit, et génère des métadonnées d'image telles que des balises et des annotations.

Ajoutez le YAML suivant à votre fichier de flux de travail :

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Extraire les métadonnées de l'image Docker
        id: meta
        uses: docker/metadata-action@v5
        with:
          images: ${{ vars.DOCKER_USERNAME }}/my-image

Ces étapes préparent les métadonnées pour baliser et annoter vos images pendant le processus de construction et de publication.

L'étape Checkout clone le dépôt Git.
L'étape Extraire les métadonnées de l'image Docker extrait les métadonnées Git et génère des balises et des annotations d'image pour la construction Docker.

S'authentifier auprès de votre registre

Avant de construire l'image, authentifiez-vous auprès de votre registre pour vous assurer que vous pouvez publier votre image construite sur le registre.

Pour vous authentifier avec Docker Hub, ajoutez l'étape suivante à votre flux de travail :

      - name: Se connecter à Docker Hub
        uses: docker/login-action@v3
        with:
          username: ${{ vars.DOCKER_USERNAME }}
          password: ${{ secrets.DOCKER_PASSWORD }}

Cette étape utilise les informations d'identification Docker configurées dans les paramètres du dépôt.

Construire et publier l'image

Enfin, construisez l'image de production finale et publiez-la sur votre registre. La configuration suivante construit l'image et la publie directement sur un registre.

      - name: Construire et publier l'image Docker
        uses: docker/build-push-action@v6
        with:
          push: ${{ github.event_name != 'pull_request' }}
          tags: ${{ steps.meta.outputs.tags }}
          annotations: ${{ steps.meta.outputs.annotations }}

Dans cette configuration :

push: ${{ github.event_name != 'pull_request' }} garantit que les images ne sont publiées que lorsque l'événement n'est pas une pull request. De cette façon, le flux de travail construit et teste les images pour les pull requests mais ne publie les images que pour les commits vers la branche principale.
tags et annotations utilisent les sorties de l'action de métadonnées pour appliquer automatiquement des balises et des annotations cohérentes à l'image.

Attestations

Les attestations SBOM (Nomenclature logicielle) et de provenance améliorent la sécurité et la traçabilité, garantissant que vos images répondent aux exigences modernes de la chaîne d'approvisionnement logicielle.

Avec un peu de configuration supplémentaire, vous pouvez configurer docker/build-push-action pour générer des attestations de nomenclature logicielle (SBOM) et de provenance pour l'image, au moment de la construction.

Pour générer ces métadonnées supplémentaires, vous devez apporter deux modifications à votre flux de travail :

Avant l'étape de construction, ajoutez une étape qui utilise docker/setup-buildx-action. Cette action configure votre client de construction Docker avec des capacités supplémentaires que le client par défaut ne prend pas en charge.
Ensuite, mettez à jour l'étape Construire et publier l'image Docker pour activer également les attestations SBOM et de provenance.

Voici l'extrait mis à jour :

      - name: Configurer Docker Buildx
        uses: docker/setup-buildx-action@v3
      
      - name: Construire et publier l'image Docker
        uses: docker/build-push-action@v6
        with:
          push: ${{ github.event_name != 'pull_request' }}
          tags: ${{ steps.meta.outputs.tags }}
          annotations: ${{ steps.meta.outputs.annotations }}
          provenance: true
          sbom: true

Pour plus de détails sur les attestations, consultez la documentation.

Conclusion

With all the steps outlined in the previous section, here's the full workflow configuration:

name: Build and Push Docker Image

on:
  push:
    branches:
      - main
  pull_request:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Extract Docker image metadata
        id: meta
        uses: docker/metadata-action@v5
        with:
          images: ${{ vars.DOCKER_USERNAME }}/my-image

      - name: Log in to Docker Hub
        uses: docker/login-action@v3
        with:
          username: ${{ vars.DOCKER_USERNAME }}
          password: ${{ secrets.DOCKER_PASSWORD }}

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3
      
      - name: Build and push Docker image
        uses: docker/build-push-action@v6
        with:
          push: ${{ github.event_name != 'pull_request' }}
          tags: ${{ steps.meta.outputs.tags }}
          annotations: ${{ steps.meta.outputs.annotations }}
          provenance: true
          sbom: true

This workflow implements best practices for building and pushing Docker images using GitHub Actions. This configuration can be used as-is or extended with additional features based on your project's needs, such as multi-platform.