⚠️ Traduction non officielle - Cette documentation est une traduction communautaire non officielle de Docker.

Configuring your GitHub Actions builder

Table des matières

Cette page contient des instructions sur la configuration de vos instances BuildKit lors de l'utilisation de notre Setup Buildx Action.

Épinglage de version

Par défaut, l'action tentera d'utiliser la dernière version de Buildx disponible sur le Runner GitHub (le client de construction) et la dernière version de BuildKit (le serveur de construction).

Pour épingler à une version spécifique de Buildx, utilisez l'entrée version. Par exemple, pour épingler à Buildx v0.10.0 :

- name: Set up Docker Buildx
  uses: docker/setup-buildx-action@v3
  with:
    version: v0.10.0

Pour épingler à une version spécifique de BuildKit, utilisez l'option image dans l'entrée driver-opts. Par exemple, pour épingler à BuildKit v0.11.0 :

- name: Set up Docker Buildx
  uses: docker/setup-buildx-action@v3
  with:
    driver-opts: image=moby/buildkit:v0.11.0

Journaux de conteneur BuildKit

Pour afficher les journaux de conteneur BuildKit lors de l'utilisation du pilote docker-container, vous devez soit activer la journalisation de débogage d'étape, ou définir le drapeau buildkitd --debug dans l'action Docker Setup Buildx :

name: ci

on:
  push:

jobs:
  buildx:
    runs-on: ubuntu-latest
    steps:
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3
        with:
          buildkitd-flags: --debug
      
      - name: Build
        uses: docker/build-push-action@v6

Les journaux seront disponibles à la fin d'une tâche :

Journaux de conteneur BuildKit

Configuration du démon BuildKit

Vous pouvez fournir une configuration BuildKit à votre constructeur si vous utilisez le pilote docker-container (par défaut) avec les entrées config ou buildkitd-config-inline :

Miroir de registre

Vous pouvez configurer un miroir de registre en utilisant un bloc inline directement dans votre workflow avec l'entrée buildkitd-config-inline :

name: ci

on:
  push:

jobs:
  buildx:
    runs-on: ubuntu-latest
    steps:
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3
        with:
          buildkitd-config-inline: |
            [registry."docker.io"]
              mirrors = ["mirror.gcr.io"]

Pour plus d'informations sur l'utilisation d'un miroir de registre, voir Miroir de registre.

Parallélisme maximum

Vous pouvez limiter le parallélisme du solveur BuildKit ce qui est particulièrement utile pour les machines peu puissantes.

Vous pouvez utiliser l'entrée buildkitd-config-inline comme l'exemple précédent, ou vous pouvez utiliser un fichier de configuration BuildKit dédié de votre dépôt si vous le souhaitez avec l'entrée config :

# .github/buildkitd.toml
[worker.oci]
  max-parallelism = 4
name: ci

on:
  push:

jobs:
  buildx:
    runs-on: ubuntu-latest
    steps:
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3
        with:
          config: .github/buildkitd.toml

Ajouter des nœuds supplémentaires au constructeur

Buildx supporte l'exécution de constructions sur plusieurs machines. Ceci est utile pour construire des images multi-plateformes sur des nœuds natifs pour des cas plus compliqués qui ne sont pas gérés par QEMU. Construire sur des nœuds natifs a généralement de meilleures performances, et vous permet de distribuer la construction sur plusieurs machines.

Vous pouvez ajouter des nœuds au constructeur que vous créez en utilisant l'option append. Elle prend une entrée sous forme de document chaîne YAML pour supprimer les limitations intrinsèquement liées à GitHub Actions : vous ne pouvez utiliser que des chaînes dans les champs d'entrée :

Nom Type Description
name String Nom du nœud. Si vide, c'est le nom du constructeur auquel il appartient, avec un suffixe de numéro d'index. Ceci est utile pour le définir si vous voulez modifier/supprimer un nœud dans une étape sous-jacente de votre workflow.
endpoint String Contexte Docker ou endpoint du nœud à ajouter au constructeur
driver-opts List Liste d' options spécifiques au pilote supplémentaires
buildkitd-flags String Drapeaux pour le démon buildkitd
platforms String Plateformes fixes pour le nœud. Si non vide, les valeurs prennent priorité sur celles détectées.

Voici un exemple utilisant des nœuds distants avec le pilote remote et l'authentification TLS :

name: ci

on:
  push:

jobs:
  buildx:
    runs-on: ubuntu-latest
    steps:
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3
        with:
          driver: remote
          endpoint: tcp://oneprovider:1234
          append: |
            - endpoint: tcp://graviton2:1234
              platforms: linux/arm64
            - endpoint: tcp://linuxone:1234
              platforms: linux/s390x
        env:
          BUILDER_NODE_0_AUTH_TLS_CACERT: ${{ secrets.ONEPROVIDER_CA }}
          BUILDER_NODE_0_AUTH_TLS_CERT: ${{ secrets.ONEPROVIDER_CERT }}
          BUILDER_NODE_0_AUTH_TLS_KEY: ${{ secrets.ONEPROVIDER_KEY }}
          BUILDER_NODE_1_AUTH_TLS_CACERT: ${{ secrets.GRAVITON2_CA }}
          BUILDER_NODE_1_AUTH_TLS_CERT: ${{ secrets.GRAVITON2_CERT }}
          BUILDER_NODE_1_AUTH_TLS_KEY: ${{ secrets.GRAVITON2_KEY }}
          BUILDER_NODE_2_AUTH_TLS_CACERT: ${{ secrets.LINUXONE_CA }}
          BUILDER_NODE_2_AUTH_TLS_CERT: ${{ secrets.LINUXONE_CERT }}
          BUILDER_NODE_2_AUTH_TLS_KEY: ${{ secrets.LINUXONE_KEY }}

Authentification pour les constructeurs distants

Les exemples suivants montrent comment gérer l'authentification pour les constructeurs distants, en utilisant SSH ou TLS.

Authentification SSH

Pour pouvoir se connecter à un endpoint SSH en utilisant le pilote docker-container, vous devez configurer la clé privée SSH et la configuration sur le Runner GitHub :

name: ci

on:
  push:

jobs:
  buildx:
    runs-on: ubuntu-latest
    steps:
      - name: Set up SSH
        uses: MrSquaare/ssh-setup-action@2d028b70b5e397cf8314c6eaea229a6c3e34977a # v3.1.0
        with:
          host: graviton2
          private-key: ${{ secrets.SSH_PRIVATE_KEY }}
          private-key-name: aws_graviton2
      
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3
        with:
          endpoint: ssh://me@graviton2

Authentification TLS

Vous pouvez également configurer une instance BuildKit distante en utilisant le pilote distant. Pour faciliter l'intégration dans votre workflow, vous pouvez utiliser des variables d'environnement qui configurent l'authentification en utilisant les certificats client BuildKit pour le tcp://:

  • BUILDER_NODE_<idx>_AUTH_TLS_CACERT
  • BUILDER_NODE_<idx>_AUTH_TLS_CERT
  • BUILDER_NODE_<idx>_AUTH_TLS_KEY

Le placeholder <idx> est la position du nœud dans la liste des nœuds.

name: ci

on:
  push:

jobs:
  buildx:
    runs-on: ubuntu-latest
    steps:
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3
        with:
          driver: remote
          endpoint: tcp://graviton2:1234
        env:
          BUILDER_NODE_0_AUTH_TLS_CACERT: ${{ secrets.GRAVITON2_CA }}
          BUILDER_NODE_0_AUTH_TLS_CERT: ${{ secrets.GRAVITON2_CERT }}
          BUILDER_NODE_0_AUTH_TLS_KEY: ${{ secrets.GRAVITON2_KEY }}

Mode autonome

Si vous n'avez pas le CLI Docker installé sur le Runner GitHub, le binaire Buildx est invoqué directement, au lieu de l'appeler comme un plugin Docker CLI. Ceci peut être utile si vous voulez utiliser le pilote kubernetes dans votre runner auto-hébergé :

name: ci

on:
  push:

jobs:
  buildx:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3
        with:
          driver: kubernetes
      
      - name: Build
        run: |
          buildx build .

Constructeurs isolés

L'exemple suivant montre comment vous pouvez sélectionner différents constructeurs pour différentes tâches.

Un exemple de scénario où ceci pourrait être utile est quand vous utilisez un monorepo, et vous voulez diriger différents packages vers des constructeurs spécifiques. Par exemple, certains packages peuvent être particulièrement gourmands en ressources à construire et nécessiter plus de calcul. Ou ils nécessitent un constructeur équipé d'une capacité ou d'un matériel particulier.

Pour plus d'informations sur le constructeur distant, voir pilote remote et l'exemple d'ajout de nœuds de constructeur.

name: ci

on:
  push:

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - name: Set up builder1
        uses: docker/setup-buildx-action@v3
        id: builder1
      
      - name: Set up builder2
        uses: docker/setup-buildx-action@v3
        id: builder2
      
      - name: Build against builder1
        uses: docker/build-push-action@v6
        with:
          builder: ${{ steps.builder1.outputs.name }}
          target: mytarget1
      
      - name: Build against builder2
        uses: docker/build-push-action@v6
        with:
          builder: ${{ steps.builder2.outputs.name }}
          target: mytarget2