Compartir comentarios
Las respuestas se generan en base a la documentación.

Gestión de caché con GitHub Actions

Tabla de contenidos

Esta página contiene ejemplos sobre el uso de los backends de almacenamiento de caché con GitHub Actions.

Note

Consulta Backends de almacenamiento de caché para más detalles sobre los backends de almacenamiento de caché.

Caché inline

En la mayoría de los casos, querrás usar el exportador de caché inline. Sin embargo, ten en cuenta que el exportador de caché inline solo admite el modo de caché min. Para usar el modo de caché max, envía la imagen y la caché por separado utilizando el exportador de caché de registro (registry) con la opción cache-to, como se muestra en el ejemplo de caché de registro.

name: ci

on:
  push:

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - name: Iniciar sesión en Docker Hub
        uses: docker/login-action@v4
        with:
          username: ${{ vars.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - name: Configurar Docker Buildx
        uses: docker/setup-buildx-action@v4

      - name: Compilar y enviar
        uses: docker/build-push-action@v7
        with:
          push: true
          tags: user/app:latest
          cache-from: type=registry,ref=user/app:latest
          cache-to: type=inline

Caché de registro (registry)

Puedes importar y exportar caché desde un manifiesto de caché o una configuración de imagen (especial) en el registro con el exportador de caché de registro (registry).

name: ci

on:
  push:

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - name: Iniciar sesión en Docker Hub
        uses: docker/login-action@v4
        with:
          username: ${{ vars.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - name: Configurar Docker Buildx
        uses: docker/setup-buildx-action@v4

      - name: Compilar y enviar
        uses: docker/build-push-action@v7
        with:
          push: true
          tags: user/app:latest
          cache-from: type=registry,ref=user/app:buildcache
          cache-to: type=registry,ref=user/app:buildcache,mode=max

Caché de GitHub

API del backend de caché

Disponibilidad: Experimental

El backend del exportador de caché de GitHub Actions utiliza la API del servicio de caché de GitHub para recuperar y cargar blobs de caché. Por eso, solo deberías utilizar este backend de caché en un flujo de trabajo de GitHub Actions, ya que los atributos url ($ACTIONS_RESULTS_URL) y token ($ACTIONS_RUNTIME_TOKEN) solo se rellenan en el contexto de un flujo de trabajo.

name: ci

on:
  push:

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - name: Iniciar sesión en Docker Hub
        uses: docker/login-action@v4
        with:
          username: ${{ vars.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - name: Configurar Docker Buildx
        uses: docker/setup-buildx-action@v4

      - name: Compilar y enviar
        uses: docker/build-push-action@v7
        with:
          push: true
          tags: user/app:latest
          cache-from: type=gha
          cache-to: type=gha,mode=max
Important

A partir del 15 de abril de 2025, solo se admite la API v2 del servicio de caché de GitHub.. La API v1 heredada se ha desactivado.

Si encuentras el siguiente error durante tu compilación:

ERROR: failed to solve: This legacy service is shutting down, effective April 15, 2025. Migrate to the new service ASAP. For more information: https://gh.io/gha-cache-sunset

Es probable que estés utilizando herramientas obsoletas que solo admiten la API v1 heredada del servicio de caché de GitHub. Aquí tienes las versiones mínimas a las que debes actualizar según tu caso de uso:

  • Docker Buildx >= v0.21.0
  • BuildKit >= v0.20.0
  • Docker Compose >= v2.33.1
  • Docker Engine >= v28.0.0 (si estás compilando con el controlador Docker y tienes habilitado el almacén de imágenes de containerd)

Si estás compilando con las acciones docker/build-push-action o docker/bake-action en runners alojados por GitHub, Docker Buildx y BuildKit ya están actualizados, pero en runners autohospedados (self-hosted), es posible que debas actualizarlos tú mismo. Alternativamente, puedes usar la acción docker/setup-buildx-action para instalar la versión más reciente de Docker Buildx:

- name: Set up Docker Buildx
  uses: docker/setup-buildx-action@v4
  with:
    version: latest

Si estás compilando con Docker Compose, puedes usar la acción docker/setup-compose-action:

- name: Set up Docker Compose
  uses: docker/setup-compose-action@v2
  with:
    version: latest

Si estás compilando con Docker Engine y tienes habilitado el almacén de imágenes de containerd, puedes usar la acción docker/setup-docker-action:

- name: Set up Docker
  uses: docker/setup-docker-action@v5
  with:
    version: latest
    daemon-config: |
      {
        "features": {
          "containerd-snapshotter": true
        }
      }

Montajes de caché (cache mounts)

BuildKit no conserva los montajes de caché (cache mounts) en la caché de GitHub Actions de forma predeterminada. Para colocar tus montajes de caché en la caché de GitHub Actions y reutilizarlos entre compilaciones, puedes utilizar una solución alternativa proporcionada por reproducible-containers/buildkit-cache-dance.

Esta GitHub Action crea contenedores temporales para extraer e inyectar los datos del montaje de caché con tus pasos de compilación de Docker.

El siguiente ejemplo muestra cómo utilizar esta solución con un proyecto en Go.

Ejemplo de Dockerfile en build/package/Dockerfile

FROM golang:1.21.1-alpine as base-build

WORKDIR /build

RUN --mount=type=cache,target=/go/pkg/mod \
    --mount=type=bind,source=go.mod,target=go.mod \
    --mount=type=bind,source=go.sum,target=go.sum \
    go mod download

RUN --mount=type=cache,target=/go/pkg/mod \
    --mount=type=cache,target=/root/.cache/go-build \
    --mount=type=bind,target=. \
    go build -o /bin/app ./src
...

Ejemplo de acción de CI

name: ci

on:
  push:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Iniciar sesión en Docker Hub
        uses: docker/login-action@v4
        with:
          username: ${{ vars.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - name: Configurar QEMU
        uses: docker/setup-qemu-action@v4

      - name: Configurar Docker Buildx
        uses: docker/setup-buildx-action@v4

      - name: Docker meta
        id: meta
        uses: docker/metadata-action@v6
        with:
          images: user/app
          tags: |
            type=ref,event=branch
            type=ref,event=pr
            type=semver,pattern={{version}}
            type=semver,pattern={{major}}.{{minor}}

      - name: Caché de compilación de Go para Docker
        uses: actions/cache@v5
        with:
          path: go-build-cache
          key: ${{ runner.os }}-go-build-cache-${{ hashFiles('**/go.sum') }}

      - name: Inyectar go-build-cache
        uses: reproducible-containers/buildkit-cache-dance@4b2444fec0c0fb9dbf175a96c094720a692ef810 # v2.1.4
        with:
          cache-source: go-build-cache

      - name: Compilar y enviar
        uses: docker/build-push-action@v7
        with:
          cache-from: type=gha
          cache-to: type=gha,mode=max
          file: build/package/Dockerfile
          push: ${{ github.event_name != 'pull_request' }}
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
          platforms: linux/amd64,linux/arm64

Para obtener más información sobre esta solución alternativa, consulta el repositorio de GitHub.

Caché local

Warning

En este momento, las entradas de caché antiguas no se eliminan, por lo que el tamaño de la caché sigue creciendo. El siguiente ejemplo utiliza el paso Move cache como solución alternativa (consulta moby/buildkit#1896 para obtener más información).

También puedes aprovechar la caché de GitHub utilizando actions/cache y el exportador de caché local con esta acción:

name: ci

on:
  push:

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - name: Iniciar sesión en Docker Hub
        uses: docker/login-action@v4
        with:
          username: ${{ vars.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - name: Configurar Docker Buildx
        uses: docker/setup-buildx-action@v4

      - name: Almacenar en caché las capas de Docker
        uses: actions/cache@v5
        with:
          path: ${{ runner.temp }}/.buildx-cache
          key: ${{ runner.os }}-buildx-${{ github.sha }}
          restore-keys: |
            ${{ runner.os }}-buildx-

      - name: Compilar y enviar
        uses: docker/build-push-action@v7
        with:
          push: true
          tags: user/app:latest
          cache-from: type=local,src=${{ runner.temp }}/.buildx-cache
          cache-to: type=local,dest=${{ runner.temp }}/.buildx-cache-new,mode=max

      - # Solución temporal
        # https://github.com/docker/build-push-action/issues/252
        # https://github.com/moby/buildkit/issues/1896
        name: Mover caché
        run: |
          rm -rf ${{ runner.temp }}/.buildx-cache
          mv ${{ runner.temp }}/.buildx-cache-new ${{ runner.temp }}/.buildx-cache