Cache GitHub Actions

Le cache GitHub Actions utilise le cache fourni par GitHub Actions ou d'autres services de cache prenant en charge le protocole de cache GitHub Actions. C'est le cache recommandé à utiliser dans vos workflows GitHub Actions, tant que votre cas d'utilisation respecte les limites de taille et d'utilisation définies par GitHub.

Ce backend de stockage de cache n'est pas pris en charge avec le pilote docker par défaut. Pour utiliser cette fonctionnalité, créez un nouveau constructeur en utilisant un pilote différent. Voir Pilotes de construction pour plus d'informations.

Synopsis

$ docker buildx build --push -t <registry>/<image> \
  --cache-to type=gha[,parameters...] \
  --cache-from type=gha[,parameters...] .

Le tableau suivant décrit les paramètres CSV disponibles que vous pouvez passer à --cache-to et --cache-from.

Authentification

Si les paramètres url, url_v2 ou token ne sont pas spécifiés, le backend de cache gha utilisera les variables d'environnement par défaut. Si vous invoquez la commande docker buildx manuellement à partir d'une étape en ligne, alors les variables doivent être exposées manuellement. Envisagez d'utiliser l'action GitHub crazy-max/ghaction-github-runtime, comme aide pour exposer les variables.

Portée

La portée est une clé utilisée pour identifier l'objet de cache. Par défaut, elle est définie à buildkit. Si vous construisez plusieurs images, chaque construction écrasera le cache de la précédente, ne laissant que le cache final.

Pour préserver le cache pour plusieurs constructions, vous pouvez spécifier cet attribut de portée avec un nom spécifique. Dans l'exemple suivant, le cache est défini sur le nom de l'image, pour s'assurer que chaque image obtient son propre cache :

$ docker buildx build --push -t <registry>/<image> \
  --cache-to type=gha,url=...,token=...,scope=image \
  --cache-from type=gha,url=...,token=...,scope=image .
$ docker buildx build --push -t <registry>/<image2> \
  --cache-to type=gha,url=...,token=...,scope=image2 \
  --cache-from type=gha,url=...,token=...,scope=image2 .

Les restrictions d'accès au cache de GitHub s'appliquent toujours. Seul le cache de la branche actuelle, de la branche de base et de la branche par défaut est accessible par un workflow.

Utilisation de docker/build-push-action

Lorsque vous utilisez docker/build-push-action, les paramètres url et token sont automatiquement renseignés. Pas besoin de les spécifier manuellement, ou d'inclure des solutions de contournement supplémentaires.

Par exemple :

- name: Build and push
  uses: docker/build-push-action@v6
  with:
    context: .
    push: true
    tags: "<registry>/<image>:latest"
    cache-from: type=gha
    cache-to: type=gha,mode=max

Éviter la limitation de l'API de cache GitHub Actions

Les limites d'utilisation et la politique d'expulsion de GitHub font que les entrées de cache obsolètes sont supprimées après un certain temps. Par défaut, le backend de cache gha utilise l'API de cache GitHub Actions pour vérifier l'état des entrées de cache.

L'API de cache GitHub Actions est soumise à une limitation de débit si vous faites trop de requêtes en peu de temps, ce qui peut se produire à la suite de recherches de cache pendant une construction utilisant le backend de cache gha.

#31 exporting to GitHub Actions Cache
#31 preparing build cache for export
#31 preparing build cache for export 600.3s done
#31 ERROR: maximum timeout reached
------
 > exporting to GitHub Actions Cache:
------
ERROR: failed to solve: maximum timeout reached
make: *** [Makefile:35: release] Error 1
Error: Process completed with exit code 2.

Pour atténuer ce problème, vous pouvez fournir un jeton GitHub à BuildKit. Cela permet à BuildKit d'utiliser l'API GitHub standard pour vérifier les clés de cache, réduisant ainsi le nombre de requêtes faites à l'API de cache.

Pour fournir un jeton GitHub, vous pouvez utiliser le paramètre ghtoken, et un paramètre repository pour spécifier le dépôt à utiliser pour le stockage du cache. Le paramètre ghtoken est un jeton GitHub avec la portée repo, qui est nécessaire pour accéder à l'API de cache GitHub Actions.

Le paramètre ghtoken est automatiquement défini à la valeur de secrets.GITHUB_TOKEN lorsque vous construisez avec l'action docker/build-push-action. Vous pouvez également définir le paramètre ghtoken manuellement en utilisant l'entrée github-token, comme montré dans l'exemple suivant :

- name: Build and push
  uses: docker/build-push-action@v6
  with:
    context: .
    push: true
    tags: "<registry>/<image>:latest"
    cache-from: type=gha
    cache-to: type=gha,mode=max
    github-token: ${{ secrets.MY_CUSTOM_TOKEN }}

Pour aller plus loin

Pour une introduction à la mise en cache, voir Cache de construction Docker.

Pour plus d'informations sur le backend de cache gha, voir le README de BuildKit.

Pour plus d'informations sur l'utilisation de GitHub Actions avec Docker, voir Introduction à GitHub Actions