Docker GitHub Builder

Docker GitHub Builder es un conjunto de flujos de trabajo reutilizables en el repositorio docker/github-builder para compilar imágenes de contenedores y artefactos locales con BuildKit. Esta sección explica qué problemas resuelven los flujos de trabajo, en qué se diferencian de conectar acciones individuales de GitHub en cada repositorio, y cuándo utilizar build.yml o bake.yml.

Si compones un trabajo de compilación a partir de docker/login-action, docker/setup-buildx-action, docker/metadata-action y docker/build-push-action o docker/bake-action, tu repositorio es responsable de cada detalle de cómo se ejecuta la compilación. Ese enfoque funciona, pero también significa que cada repositorio debe mantener su propia selección de runners, configuración de caché, configuración de procedencia, comportamiento de firma y manejo de manifiestos multiplataforma. Docker GitHub Builder traslada esa implementación a flujos de trabajo reutilizables mantenidos por Docker, de modo que tu flujo de trabajo solo decide cuándo compilar y qué entradas pasar.

La diferencia es más fácil de ver en la definición del trabajo. Un flujo de trabajo convencional detalla cada paso de la acción:

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 QEMU
        uses: docker/setup-qemu-action@v4

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

      - name: Metadatos de Docker
        uses: docker/metadata-action@v6
        id: meta
        with:
          images: name/app

      - name: Compilar y enviar
        uses: docker/build-push-action@v7
        with:
          push: ${{ github.event_name != 'pull_request' }}
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
          cache-from: type=gha
          cache-to: type=gha

Con Docker GitHub Builder, la misma compilación se reduce a una llamada a un flujo de trabajo reutilizable:

jobs:
  build:
    uses: docker/github-builder/.github/workflows/build.yml@v1
    permissions:
      contents: read # para obtener el contenido del repositorio
      id-token: write # para firmar atestaciones con el token OIDC de GitHub
    with:
      output: image
      push: ${{ github.event_name != 'pull_request' }}
      meta-images: name/app
    secrets:
      registry-auths: |
        - registry: docker.io
          username: ${{ vars.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

Este modelo te proporciona un flujo de trabajo de compilación mantenido en la organización Docker, utiliza un entorno BuildKit fijo, distribuye compilaciones multiplataforma a través de runners cuando es de ayuda, y genera procedencia SLSA firmada que registra tanto la confirmación de origen como la identidad del constructor.

Esa compensación es intencionada. Mantienes el control de cuándo se ejecuta la compilación y qué entradas utiliza, pero la implementación de la compilación en sí vive en el flujo de trabajo mantenido por Docker en lugar de en los pasos de cada repositorio.

Utiliza build.yml cuando tu repositorio compile a partir de un Dockerfile y las entradas familiares de build-push-action se asignen limpiamente a tu flujo de trabajo. Utiliza bake.yml cuando tu repositorio ya describa compilaciones en una definición de Bake, o cuando desees que los targets, anulaciones y variables de Bake sigan siendo la fuente de verdad.

Ambos flujos de trabajo admiten la salida de imágenes, la salida local, la exportación de caché al backend de caché de GitHub Actions, generación de SBOM y la firma. El flujo de trabajo de Bake añade la validación de la definición de Bake y compila un target por llamada al flujo de trabajo.

¿En qué te puedo ayudar?

Docker GitHub Builder