Caché de GitHub Actions

La caché de GitHub Actions utiliza la caché de Actions proporcionada por GitHub u otros servicios de caché que admitan el protocolo de caché de GitHub Actions. Esta es la caché recomendada para usar dentro de tus flujos de trabajo de GitHub Actions, siempre que tu caso de uso se encuentre dentro de los límites de tamaño y uso establecidos por GitHub.

Este backend de almacenamiento de caché no es compatible con el controlador docker predeterminado. Para usar esta función, crea un nuevo constructor (builder) usando un controlador diferente. Consulta Controladores de compilación para obtener más información.

Sinopsis

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

La siguiente tabla describe los parámetros CSV disponibles que puedes pasar a --cache-to y --cache-from.

Autenticación

Si los parámetros url, url_v2 o token se dejan sin especificar, el backend de caché gha recurrirá al uso de variables de entorno. Si invocas el comando docker buildx manualmente desde un paso inline, entonces las variables deben exponerse manualmente. Considera usar la GitHub Action crazy-max/ghaction-github-runtime como ayuda para exponer las variables.

Ámbito

El ámbito (scope) es una clave utilizada para identificar el objeto de caché. De forma predeterminada, está establecido en buildkit. Si compilas múltiples imágenes, cada compilación sobrescribirá la caché de la anterior, dejando solo la caché final.

Para preservar la caché para múltiples compilaciones, puedes especificar este atributo de ámbito con un nombre específico. En el siguiente ejemplo, la caché se establece con el nombre de la imagen para asegurar que cada imagen obtenga su propia caché:

$ 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 .

Las restricciones de acceso a la caché de GitHub siguen aplicándose. Solo la caché de la rama actual, la rama base y la rama predeterminada es accesible por un flujo de trabajo.

Versión

Si no estableces version explícitamente, el valor predeterminado es v1. Sin embargo, si la variable de entorno $ACTIONS_CACHE_SERVICE_V2 está establecida en un valor que se interprete como true (1, true, yes), entonces v2 se utiliza automáticamente.

Solo una URL es relevante a la vez:

• Con v1, usa url (el valor predeterminado es $ACTIONS_CACHE_URL).
• Con v2, usa url_v2 (el valor predeterminado es $ACTIONS_RESULTS_URL).

Uso de docker/build-push-action

Al usar la acción docker/build-push-action, los parámetros url y token se completan automáticamente. No es necesario especificarlos manualmente ni incluir soluciones adicionales.

Por ejemplo:

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

Evitar la limitación de velocidad (throttling) de la API de caché de GitHub Actions

Los límites de uso y política de desalojo de GitHub provocan que las entradas de caché obsoletas se eliminen después de un determinado período de tiempo. De forma predeterminada, el backend de caché gha utiliza la API de caché de GitHub Actions para verificar el estado de las entradas de caché.

La API de caché de GitHub Actions está sujeta a límites de velocidad si realizas demasiadas solicitudes en un período corto de tiempo, lo que puede ocurrir como resultado de las búsquedas de caché durante una compilación usando el backend de caché 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.

Para mitigar este problema, puedes proporcionar un token de GitHub a BuildKit. Esto permite que BuildKit utilice la API estándar de GitHub para verificar las claves de caché, reduciendo así la cantidad de solicitudes realizadas a la API de caché.

Para proporcionar un token de GitHub, puedes usar el parámetro ghtoken y un parámetro repository para especificar el repositorio que se utilizará para el almacenamiento de caché. El parámetro ghtoken es un token de GitHub con el ámbito repo, el cual es necesario para acceder a la API de caché de GitHub Actions.

El parámetro ghtoken se establece automáticamente con el valor de secrets.GITHUB_TOKEN cuando compilas con la acción docker/build-push-action. También puedes establecer el parámetro ghtoken manualmente usando la entrada github-token, como se muestra en el siguiente ejemplo:

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

Lecturas adicionales

Para una introducción al almacenamiento en caché, consulta Caché de compilación de Docker.

Para obtener más información sobre el backend de caché gha, consulta el README de BuildKit.

Para obtener más información sobre el uso de GitHub Actions con Docker, consulta Introducción a GitHub Actions.