Utiliser Docker Build Cloud en CI

Table des matières

Utiliser Docker Build Cloud en CI peut accélérer vos pipelines de build, ce qui signifie moins de temps passé à attendre et à changer de contexte. Vous contrôlez vos workflows CI comme d'habitude, et déléguez l'exécution du build à Docker Build Cloud.

Construire avec Docker Build Cloud en CI implique les étapes suivantes :

Se connecter à un compte Docker.
Configurer Buildx et se connecter au constructeur.
Exécuter le build.

Lors de l'utilisation de Docker Build Cloud en CI, il est recommandé de pousser le résultat vers un registre directement, plutôt que de charger l'image puis de la pousser. Pousser directement accélère vos builds et évite les transferts de fichiers inutiles.

Si vous voulez juste construire et rejeter la sortie, exportez les résultats vers le cache de build ou construisez sans tagger l'image. Quand vous utilisez Docker Build Cloud, Buildx charge automatiquement le résultat du build si vous construisez une image taguée. Voir Chargement des résultats de build pour les détails.

Note

Les builds sur Docker Build Cloud ont une limite de timeout de 90 minutes. Les builds qui s'exécutent plus de 90 minutes sont automatiquement annulés.

Configuration des identifiants pour CI/CD

Pour permettre à votre système CI/CD de construire et pousser des images en utilisant Docker Build Cloud, fournissez à la fois un jeton d'accès et un nom d'utilisateur. Le type de jeton et le nom d'utilisateur que vous utilisez dépendent de votre type de compte et de vos permissions.

Si vous êtes un administrateur d'organisation ou avez la permission de créer des jetons d'accès d'organisation (OAT), utilisez un OAT et définissez DOCKER_USER sur le nom de votre organisation Docker Hub.
Si vous n'avez pas la permission de créer des OAT ou utilisez un compte personnel, utilisez un jeton d'accès personnel (PAT) et définissez DOCKER_USER sur votre nom d'utilisateur Docker Hub.

Création des jetons d'accès

Pour les comptes d'organisation

Si vous êtes un administrateur d'organisation :

Créez un jeton d'accès d'organisation (OAT) :
- Le jeton doit avoir ces permissions :
  - Portée cloud-connect
  - Permission Lire les dépôts publics
  - Accès au dépôt avec permission Pousser l'image pour le dépôt cible :
    - Développez le menu déroulant Dépôt.
    - Sélectionnez Ajouter un dépôt et choisissez votre dépôt cible.
    - Définissez la permission Pousser l'image pour le dépôt.

Si vous n'êtes pas un administrateur d'organisation :

Demandez à votre administrateur d'organisation un jeton d'accès avec les permissions listées ci-dessus, ou utilisez un jeton d'accès personnel.

Pour les comptes personnels

Créez un jeton d'accès personnel (PAT) :
- Créez un nouveau jeton avec l'accès Lecture et écriture.
  - Note : Construire avec Docker Build Cloud ne nécessite qu'un accès en lecture, mais vous avez besoin d'un accès en écriture pour pousser des images vers un dépôt Docker Hub.

Exemples de plateformes CI

Note

Dans votre configuration CI/CD, définissez les variables suivantes :

DOCKER_PAT — votre jeton d'accès (PAT ou OAT)

DOCKER_USER — votre nom d'utilisateur Docker Hub (pour PAT) ou nom d'organisation (pour OAT)

Cela garantit que vos builds s'authentifient correctement avec Docker Build Cloud.

GitHub Actions

name: ci

on:
  push:
    branches:
      - "main"

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - name: Login to Docker Hub
        uses: docker/login-action@v3
        with:
          username: ${{ vars.DOCKER_USER }}
          password: ${{ secrets.DOCKER_PAT }}
      
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3
        with:
          driver: cloud
          endpoint: "<ORG>/default"
          install: true
      
      - name: Build and push
        uses: docker/build-push-action@v6
        with:
          tags: "<IMAGE>"
          # Pour les pull requests, exporter les résultats vers le cache de build.
          # Sinon, pousser vers un registre.
          outputs: ${{ github.event_name == 'pull_request' && 'type=cacheonly' || 'type=registry' }}

GitLab

default:
  image: docker:24-dind
  services:
    - docker:24-dind
  before_script:
    - docker info
    - echo "$DOCKER_PAT" | docker login --username "$DOCKER_USER" --password-stdin
    - |
      apk add curl jq
      ARCH=${CI_RUNNER_EXECUTABLE_ARCH#*/}
      BUILDX_URL=$(curl -s https://raw.githubusercontent.com/docker/actions-toolkit/main/.github/buildx-lab-releases.json | jq -r ".latest.assets[] | select(endswith(\"linux-$ARCH\"))")
      mkdir -vp ~/.docker/cli-plugins/
      curl --silent -L --output ~/.docker/cli-plugins/docker-buildx $BUILDX_URL
      chmod a+x ~/.docker/cli-plugins/docker-buildx
    - docker buildx create --use --driver cloud ${DOCKER_ORG}/default

variables:
  IMAGE_NAME: <IMAGE>
  DOCKER_ORG: <ORG>

# Construire une image multi-plateforme et pousser vers un registre
build_push:
  stage: build
  script:
    - |
      docker buildx build \
        --platform linux/amd64,linux/arm64 \
        --tag "${IMAGE_NAME}:${CI_COMMIT_SHORT_SHA}" \
        --push .

# Construire une image et rejeter le résultat
build_cache:
  stage: build
  script:
    - |
      docker buildx build \
        --platform linux/amd64,linux/arm64 \
        --tag "${IMAGE_NAME}:${CI_COMMIT_SHORT_SHA}" \
        --output type=cacheonly \
        .

Circle CI

version: 2.1

jobs:
  # Construire une image multi-plateforme et pousser vers un registre
  build_push:
    machine:
      image: ubuntu-2204:current
    steps:
      - checkout

      - run: |
          mkdir -vp ~/.docker/cli-plugins/
          ARCH=amd64
          BUILDX_URL=$(curl -s https://raw.githubusercontent.com/docker/actions-toolkit/main/.github/buildx-lab-releases.json | jq -r ".latest.assets[] | select(endswith(\"linux-$ARCH\"))")
          curl --silent -L --output ~/.docker/cli-plugins/docker-buildx $BUILDX_URL
          chmod a+x ~/.docker/cli-plugins/docker-buildx

      - run: echo "$DOCKER_PAT" | docker login --username $DOCKER_USER --password-stdin
      - run: docker buildx create --use --driver cloud "<ORG>/default"

      - run: |
          docker buildx build \
          --platform linux/amd64,linux/arm64 \
          --push \
          --tag "<IMAGE>" .

  # Construire une image et rejeter le résultat
  build_cache:
    machine:
      image: ubuntu-2204:current
    steps:
      - checkout

      - run: |
          mkdir -vp ~/.docker/cli-plugins/
          ARCH=amd64
          BUILDX_URL=$(curl -s https://raw.githubusercontent.com/docker/actions-toolkit/main/.github/buildx-lab-releases.json | jq -r ".latest.assets[] | select(endswith(\"linux-$ARCH\"))")
          curl --silent -L --output ~/.docker/cli-plugins/docker-buildx $BUILDX_URL
          chmod a+x ~/.docker/cli-plugins/docker-buildx

      - run: echo "$DOCKER_PAT" | docker login --username $DOCKER_USER --password-stdin
      - run: docker buildx create --use --driver cloud "<ORG>/default"

      - run: |
          docker buildx build \
          --tag temp \
          --output type=cacheonly \
          .

workflows:
  pull_request:
    jobs:
      - build_cache
  release:
    jobs:
      - build_push

Buildkite

L'exemple suivant configure un pipeline Buildkite utilisant Docker Build Cloud. L' exemple suppose que le nom du pipeline est build-push-docker et que vous gérez le jeton d'accès Docker en utilisant des hooks d'environnement, mais n'hésitez pas à adapter cela à vos besoins.

Ajoutez le hook environment suivant au répertoire de hooks de l'agent :

#!/bin/bash
set -euo pipefail

if [[ "$BUILDKITE_PIPELINE_NAME" == "build-push-docker" ]]; then
 export DOCKER_PAT="<DOCKER_PERSONAL_ACCESS_TOKEN>"
fi

Créez un pipeline.yml qui utilise le plugin docker-login :

env:
  DOCKER_ORG: <ORG>
  IMAGE_NAME: <IMAGE>

steps:
  - command: ./build.sh
    key: build-push
    plugins:
      - docker-login#v2.1.0:
          username: <DOCKER_USER>
          password-env: DOCKER_PAT # le nom de la variable dans le hook d'environnement

Créez le script build.sh :

DOCKER_DIR=/usr/libexec/docker

# Obtenir le lien de téléchargement pour le dernier binaire buildx.
# Définir $ARCH sur l'architecture CPU (ex. amd64, arm64)
UNAME_ARCH=`uname -m`
case $UNAME_ARCH in
  aarch64)
    ARCH="arm64";
    ;;
  amd64)
    ARCH="amd64";
    ;;
  *)
    ARCH="amd64";
    ;;
esac
BUILDX_URL=$(curl -s https://raw.githubusercontent.com/docker/actions-toolkit/main/.github/buildx-lab-releases.json | jq -r ".latest.assets[] | select(endswith(\"linux-$ARCH\"))")

# Télécharger docker buildx avec le support Build Cloud
curl --silent -L --output $DOCKER_DIR/cli-plugins/docker-buildx $BUILDX_URL
chmod a+x ~/.docker/cli-plugins/docker-buildx

# Se connecter à votre constructeur et le définir comme constructeur par défaut
docker buildx create --use --driver cloud "$DOCKER_ORG/default"

# Build d'image cache seulement
docker buildx build \
    --platform linux/amd64,linux/arm64 \
    --tag "$IMAGE_NAME:$BUILDKITE_COMMIT" \
    --output type=cacheonly \
    .

# Construire, tagger et pousser une image docker multi-arch
docker buildx build \
    --platform linux/amd64,linux/arm64 \
    --push \
    --tag "$IMAGE_NAME:$BUILDKITE_COMMIT" \
    .

Jenkins

pipeline {
  agent any

  environment {
    ARCH = 'amd64'
    DOCKER_PAT = credentials('docker-personal-access-token')
    DOCKER_USER = credentials('docker-username')
    DOCKER_ORG = '<ORG>'
    IMAGE_NAME = '<IMAGE>'
  }

  stages {
    stage('Build') {
      environment {
        BUILDX_URL = sh (returnStdout: true, script: 'curl -s https://raw.githubusercontent.com/docker/actions-toolkit/main/.github/buildx-lab-releases.json | jq -r ".latest.assets[] | select(endswith(\\"linux-$ARCH\\"))"').trim()
      }
      steps {
        sh 'mkdir -vp ~/.docker/cli-plugins/'
        sh 'curl --silent -L --output ~/.docker/cli-plugins/docker-buildx $BUILDX_URL'
        sh 'chmod a+x ~/.docker/cli-plugins/docker-buildx'
        sh 'echo "$DOCKER_PAT" | docker login --username $DOCKER_USER --password-stdin'
        sh 'docker buildx create --use --driver cloud "$DOCKER_ORG/default"'
        // Build cache seulement
        sh 'docker buildx build --platform linux/amd64,linux/arm64 --tag "$IMAGE_NAME" --output type=cacheonly .'
        // Construire et pousser une image multi-plateforme
        sh 'docker buildx build --platform linux/amd64,linux/arm64 --push --tag "$IMAGE_NAME" .'
      }
    }
  }
}

Travis CI

language: minimal 
dist: jammy 

services:
  - docker

env:
  global:
    - IMAGE_NAME=username/repo

before_install: |
  echo "$DOCKER_PAT" | docker login --username "$DOCKER_USER" --password-stdin

install: |
  set -e 
  BUILDX_URL=$(curl -s https://raw.githubusercontent.com/docker/actions-toolkit/main/.github/buildx-lab-releases.json | jq -r ".latest.assets[] | select(endswith(\"linux-$TRAVIS_CPU_ARCH\"))")
  mkdir -vp ~/.docker/cli-plugins/
  curl --silent -L --output ~/.docker/cli-plugins/docker-buildx $BUILDX_URL
  chmod a+x ~/.docker/cli-plugins/docker-buildx
  docker buildx create --use --driver cloud "<ORG>/default"

script: |
  docker buildx build \
  --platform linux/amd64,linux/arm64 \
  --push \
  --tag "$IMAGE_NAME" .

BitBucket Pipelines

# Prérequis : $DOCKER_USER, $DOCKER_PAT configurés comme variables de déploiement
# Ce pipeline suppose $BITBUCKET_REPO_SLUG comme nom d'image
# Remplacez <ORG> dans la commande `docker buildx create` par votre org Docker

image: atlassian/default-image:3

pipelines:
  default:
    - step:
        name: Build multi-platform image
        script:
          - mkdir -vp ~/.docker/cli-plugins/
          - ARCH=amd64
          - BUILDX_URL=$(curl -s https://raw.githubusercontent.com/docker/actions-toolkit/main/.github/buildx-lab-releases.json | jq -r ".latest.assets[] | select(endswith(\"linux-$ARCH\"))")
          - curl --silent -L --output ~/.docker/cli-plugins/docker-buildx $BUILDX_URL
          - chmod a+x ~/.docker/cli-plugins/docker-buildx
          - echo "$DOCKER_PAT" | docker login --username $DOCKER_USER --password-stdin
          - docker buildx create --use --driver cloud "<ORG>/default"
          - IMAGE_NAME=$BITBUCKET_REPO_SLUG
          - docker buildx build
            --platform linux/amd64,linux/arm64
            --push
            --tag "$IMAGE_NAME" .
        services:
          - docker

Script shell

#!/bin/bash

# Obtenir le lien de téléchargement pour le dernier binaire buildx. Définir $ARCH sur l'architecture CPU (ex. amd64, arm64)
ARCH=amd64
BUILDX_URL=$(curl -s https://raw.githubusercontent.com/docker/actions-toolkit/main/.github/buildx-lab-releases.json | jq -r ".latest.assets[] | select(endswith(\"linux-$ARCH\"))")

# Télécharger docker buildx avec le support Build Cloud
mkdir -vp ~/.docker/cli-plugins/
curl --silent -L --output ~/.docker/cli-plugins/docker-buildx $BUILDX_URL
chmod a+x ~/.docker/cli-plugins/docker-buildx

# Se connecter à Docker Hub. Pour des raisons de sécurité $DOCKER_PAT devrait être un Jeton d'Accès Personnel. Voir https://docs.docker.com/build-cloud/ci/#creating-access-tokens
echo "$DOCKER_PAT" | docker login --username $DOCKER_USER --password-stdin

# Se connecter à votre constructeur et le définir comme constructeur par défaut
docker buildx create --use --driver cloud "<ORG>/default"

# Build d'image cache seulement
docker buildx build \
    --tag temp \
    --output type=cacheonly \
    .

# Construire, tagger et pousser une image docker multi-arch
docker buildx build \
    --platform linux/amd64,linux/arm64 \
    --push \
    --tag "<IMAGE>" \
    .

Docker Compose

Utilisez cette implémentation si vous voulez utiliser docker compose build avec Docker Build Cloud en CI.

#!/bin/bash

# Obtenir le lien de téléchargement pour le dernier binaire buildx. Définir $ARCH sur l'architecture CPU (ex. amd64, arm64)
ARCH=amd64
BUILDX_URL=$(curl -s https://raw.githubusercontent.com/docker/actions-toolkit/main/.github/buildx-lab-releases.json | jq -r ".latest.assets[] | select(endswith(\"linux-$ARCH\"))")
COMPOSE_URL=$(curl -sL \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <GITHUB_TOKEN>" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/repos/docker/compose-desktop/releases \
  | jq "[ .[] | select(.prerelease==false and .draft==false) ] | .[0].assets.[] | select(.name | endswith(\"linux-${ARCH}\")) | .browser_download_url")

# Télécharger docker buildx avec le support Build Cloud
mkdir -vp ~/.docker/cli-plugins/
curl --silent -L --output ~/.docker/cli-plugins/docker-buildx $BUILDX_URL
curl --silent -L --output ~/.docker/cli-plugins/docker-compose $COMPOSE_URL
chmod a+x ~/.docker/cli-plugins/docker-buildx
chmod a+x ~/.docker/cli-plugins/docker-compose

# Se connecter à Docker Hub. Pour des raisons de sécurité $DOCKER_PAT devrait être un Jeton d'Accès Personnel. Voir https://docs.docker.com/build-cloud/ci/#creating-access-tokens
echo "$DOCKER_PAT" | docker login --username $DOCKER_USER --password-stdin

# Se connecter à votre constructeur et le définir comme constructeur par défaut
docker buildx create --use --driver cloud "<ORG>/default"

# Construire l'image
docker compose build