# Caché de GitHub Actions La caché de GitHub Actions utiliza la [caché de Actions proporcionada por GitHub](https://github.com/actions/cache) 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](https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows#usage-limits-and-eviction-policy). 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](/build/builders/drivers/) para obtener más información. ## Sinopsis ```console $ docker buildx build --push -t / \ --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`. | Nombre | Opción | Tipo | Predeterminado | Descripción | | -------------- | ----------------------- | ----------- | --------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | `url` | `cache-to`,`cache-from` | String | `$ACTIONS_CACHE_URL` o `$ACTIONS_RESULTS_URL` | URL del servidor de caché, consulta [autenticación][1]. Se ignora cuando `version=2`. | | `url_v2` | `cache-to`,`cache-from` | String | `$ACTIONS_RESULTS_URL` | URL del servidor de caché v2, consulta [autenticación][1]. | | `token` | `cache-to`,`cache-from` | String | `$ACTIONS_RUNTIME_TOKEN` | Token de acceso, consulta [autenticación][1]. | | `scope` | `cache-to`,`cache-from` | String | `buildkit` | A qué ámbito pertenece el objeto de caché, consulta [ámbito][2] | | `mode` | `cache-to` | `min`,`max` | `min` | Capas de caché a exportar, consulta [modo de caché][3]. | | `ignore-error` | `cache-to` | Boolean | `false` | Ignorar los errores causados por exportaciones de caché fallidas. | | `timeout` | `cache-to`,`cache-from` | String | `10m` | Duración máxima para importar o exportar caché antes de que se agote el tiempo de espera. | | `repository` | `cache-to` | String | | Repositorio de GitHub utilizado para el almacenamiento de caché. | | `ghtoken` | `cache-to` | String | | Token de GitHub requerido para acceder a la API de GitHub. | | `version` | `cache-to`,`cache-from` | String | `1` a menos que `$ACTIONS_CACHE_SERVICE_V2` esté establecido, en cuyo caso es `2` | Selecciona la versión de la caché de GitHub Actions, consulta [versión][4] | [1]: #autenticacion [2]: #ambito [3]: /build/cache/backends/#modo-de-cache [4]: #version ## 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`](https://github.com/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é: ```console $ docker buildx build --push -t / \ --cache-to type=gha,url=...,token=...,scope=image \ --cache-from type=gha,url=...,token=...,scope=image . $ docker buildx build --push -t / \ --cache-to type=gha,url=...,token=...,scope=image2 \ --cache-from type=gha,url=...,token=...,scope=image2 . ``` Las [restricciones de acceso a la caché](https://docs.github.com/en/actions/advanced-guides/caching-dependencies-to-speed-up-workflows#restrictions-for-accessing-a-cache) 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`](https://github.com/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: ```yaml - name: Build and push uses: docker/build-push-action@v7 with: context: . push: true tags: "/: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](https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows#usage-limits-and-eviction-policy) 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`. ```text #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: ```yaml - name: Build and push uses: docker/build-push-action@v7 with: context: . push: true tags: "/: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](/build/backends/). Para obtener más información sobre el backend de caché `gha`, consulta el [README de BuildKit](https://github.com/moby/buildkit#github-actions-cache-experimental). Para obtener más información sobre el uso de GitHub Actions con Docker, consulta [Introducción a GitHub Actions](/build/ci/github-actions/).