Saltar al contenido

Plantilla de workflow de GitHub Actions para compilar Docker

Última actualización

Este es un .github/workflows/ci.yml funcional que compila su imagen de Docker en cada pull request y la sube a GitHub Container Registry (GHCR) desde main. Usa Buildx con la caché de capas de GitHub Actions, de modo que las capas sin cambios no se vuelven a compilar.

El flujo de trabajo

name: CI

on:
  push:
    branches: [main]
  pull_request:

permissions:
  contents: read

concurrency:
  group: ci-${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
  cancel-in-progress: ${{ github.event_name == 'pull_request' }}

env:
  IMAGE: ghcr.io/${{ github.repository }}

jobs:
  build:
    runs-on: ubuntu-latest
    timeout-minutes: 30
    permissions:
      contents: read
      packages: write
    steps:
      - uses: actions/checkout@v4

      - uses: docker/setup-buildx-action@v3

      - uses: docker/login-action@v3
        if: github.event_name != 'pull_request'
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - id: meta
        uses: docker/metadata-action@v5
        with:
          images: ${{ env.IMAGE }}
          tags: |
            type=sha
            type=raw,value=latest,enable={{is_default_branch}}

      - uses: docker/build-push-action@v6
        with:
          context: .
          push: ${{ github.event_name != 'pull_request' }}
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
          cache-from: type=gha
          cache-to: type=gha,mode=max

Qué hacen las partes menos evidentes

  • Permisos. El valor predeterminado del flujo de trabajo es de solo lectura. El job añade packages: write porque es el único que sube imágenes. Las pull requests desde forks reciben de todos modos un token de solo lectura, por lo que no pueden subir nada.
  • setup-buildx-action crea un builder de Buildx. El driver de Docker predeterminado no puede exportar la caché de GitHub, por lo que este paso es obligatorio para cache-to: type=gha.
  • Iniciar sesión solo al subir. En las pull requests no hay nada que subir, así que el paso se omite.
  • docker/metadata-action genera las etiquetas y las etiquetas OCI. El ejemplo etiqueta cada compilación con el SHA del commit y añade latest en la rama predeterminada.
  • Expresión push:. Las pull requests solo compilan, como comprobación de que el Dockerfile sigue funcionando. Los envíos a main compilan y suben la imagen.
  • cache-from y cache-to: type=gha,mode=max leen y escriben en la caché de GitHub Actions. mode=max guarda en caché todas las capas de todas las etapas, lo que importa en compilaciones multietapa, aunque ocupa más espacio de caché. Consulte los límites de caché.
  • El orden en el Dockerfile importa más que cualquier ajuste. Copie los archivos de bloqueo e instale las dependencias antes de copiar el código fuente, de modo que los cambios en el código no invaliden las capas de dependencias. La lista completa de técnicas está en Caché de capas de Docker en CI.

Variantes

Imágenes multiplataforma

Añada docker/setup-qemu-action@v3 antes de Buildx y platforms: linux/amd64,linux/arm64 al paso de compilación. Las compilaciones arm64 emuladas son lentas; use un runner ARM nativo cuando la velocidad sea importante.

Analizar antes de subir

Añada un paso de análisis de vulnerabilidades sobre la imagen compilada antes de subirla, y haga que falle ante hallazgos de gravedad alta.

Ejecutar pruebas dentro de la imagen

Añada un primer paso de compilación con load: true, push: false y una etapa de pruebas, y luego ejecute docker run sobre el resultado. Comparta las capas a través de la misma caché.

Docker Hub o ECR

Cambie registry, el paso de inicio de sesión y images. Para AWS, use OIDC con aws-actions/amazon-ecr-login@v2 en lugar de claves almacenadas.

Job de despliegue

Añada un segundo job con needs: build que despliegue la etiqueta con el SHA subido.

macOS

Docker no está disponible en los runners de macOS. Mantenga las compilaciones de contenedores en Linux.

Ejecútelo en máquinas más rápidas

Las compilaciones de Docker consumen mucha CPU y disco, y las cachés de capas solo ayudan si están cerca de la compilación. Cambie una línea:

    runs-on: [self-hosted, Linux, compiler-ci]

El job se ejecuta en una máquina nueva de 8 vCPU de compiler.dev, que mantiene una caché de capas de Docker en la máquina, con reversión automática a su runner original. Para compilaciones de imágenes en concreto, los builders dedicados como Depot pueden ser más rápidos; compare las opciones en runners más rápidos para GitHub Actions. Los precios están en precios.

Preguntas frecuentes

¿Por qué mi compilación no usa la caché?

Compruebe que Buildx está configurado, que cache-from y cache-to coinciden, y que una capa temprana del Dockerfile no cambia en cada ejecución (por ejemplo, al copiar primero todo el repositorio).

¿Es lo bastante grande la caché de GitHub?

Los repositorios tienen un límite de tamaño compartido por todas las cachés, y las entradas antiguas se eliminan. Las imágenes grandes pueden llenarlo.

¿Las pull requests desde forks suben imágenes?

No. La expresión push es falsa para las pull requests, y los tokens de los forks son de solo lectura.

Entonces, ¿para qué sirven los artefactos?

Use un artefacto para pasar un tarball compilado entre jobs, no para la caché de capas.