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

Introducción a GitHub Actions con Docker

Tabla de contenidos

Esta guía ofrece una introducción a la creación de tuberías (pipelines) de CI utilizando Docker y GitHub Actions. Aprenderás a usar las GitHub Actions oficiales de Docker para construir tu aplicación como una imagen de Docker y publicarla en Docker Hub. Al final de la guía, tendrás una configuración simple y funcional de GitHub Actions para las construcciones de Docker. Utilízala tal como está o amplíala según tus necesidades.

Requisitos previos

Si deseas seguir la guía paso a paso, asegúrate de tener lo siguiente:

  • Una cuenta de Docker verificada.
  • Familiaridad con los Dockerfiles.

Esta guía asume conocimientos básicos sobre los conceptos de Docker, pero proporciona explicaciones para utilizar Docker en los flujos de trabajo de GitHub Actions.

Obtener la aplicación de ejemplo

Esta guía es independiente del proyecto y asume que tienes una aplicación con un Dockerfile.

Si necesitas un proyecto de ejemplo para seguir los pasos, puedes usar esta aplicación de ejemplo, que incluye un Dockerfile para construir una versión contenerizada de la aplicación. Alternativamente, utiliza tu propio proyecto de GitHub o crea un nuevo repositorio a partir de la plantilla.

#syntax=docker/dockerfile:1

# builder installs dependencies and builds the node app
FROM node:lts-alpine AS builder
WORKDIR /src
RUN --mount=src=package.json,target=package.json \
    --mount=src=package-lock.json,target=package-lock.json \
    --mount=type=cache,target=/root/.npm \
    npm ci
COPY . .
RUN --mount=type=cache,target=/root/.npm \
    npm run build

# release creates the runtime image
FROM node:lts-alpine AS release
WORKDIR /app
COPY --from=builder /src/build .
EXPOSE 3000
CMD ["node", "."]

Configurar tu repositorio de GitHub

El flujo de trabajo de esta guía publica la imagen que construyes en Docker Hub. Para hacer eso, debes autenticarte con tus credenciales de Docker (nombre de usuario y token de acceso) como parte del flujo de trabajo de GitHub Actions.

Para obtener instrucciones sobre cómo crear un token de acceso de Docker, consulta Crear y gestionar tokens de acceso.

Una vez que tengas listas tus credenciales de Docker, agrégalas a tu repositorio de GitHub para poder usarlas en GitHub Actions:

  1. Abre la Configuración (Settings) de tu repositorio.
  2. En Seguridad (Security), ve a Secrets and variables > Actions.
  3. En Secrets, crea un nuevo secreto de repositorio llamado DOCKER_PASSWORD que contenga tu token de acceso de Docker.
  4. A continuación, en Variables, crea una variable de repositorio DOCKER_USERNAME que contenga tu nombre de usuario de Docker Hub.

Configurar tu flujo de trabajo de GitHub Actions

Los flujos de trabajo de GitHub Actions definen una serie de pasos para automatizar tareas, como construir y publicar imágenes de Docker, en respuesta a desencadenadores (triggers) como confirmaciones (commits) o solicitudes de extracción (pull requests). En esta guía, el flujo de trabajo se centra en automatizar las construcciones y pruebas de Docker, asegurando que tu aplicación contenerizada funcione correctamente antes de publicarla.

Crea un archivo llamado docker-ci.yml en el directorio .github/workflows/ de tu repositorio. Comienza con la configuración básica del flujo de trabajo:

name: Build and Push Docker Image

on:
  push:
    branches:
      - main
  pull_request:

Esta configuración ejecuta el flujo de trabajo al realizar confirmaciones en la rama main y en las solicitudes de extracción. Al incluir ambos desencadenadores, puedes asegurarte de que la imagen se construya correctamente para una solicitud de extracción antes de que se fusione.

Extraer metadatos para etiquetas y anotaciones

Para el primer paso de tu flujo de trabajo, utiliza docker/metadata-action para generar metadatos para tu imagen. Esta acción extrae información sobre tu repositorio de Git, como los nombres de las ramas y los SHAs de las confirmaciones, y genera metadatos de la imagen, como etiquetas y anotaciones.

Agrega el siguiente YAML a tu archivo de flujo de trabajo:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v6
      - name: Extract Docker image metadata
        id: meta
        uses: docker/metadata-action@v6
        with:
          images: ${{ vars.DOCKER_USERNAME }}/my-image

Estos pasos preparan los metadatos para etiquetar y anotar tus imágenes durante el proceso de construcción y publicación.

  • El paso Checkout clona el repositorio de Git.
  • El paso Extract Docker image metadata extrae los metadatos de Git y genera etiquetas y anotaciones de imagen para la construcción de Docker.

Autenticarse en tu registro

Antes de construir la imagen, autentícate en tu registro para asegurarte de que puedes publicar la imagen construida en él.

Para autenticarte con Docker Hub, agrega el siguiente paso a tu flujo de trabajo:

      - name: Log in to Docker Hub
        uses: docker/login-action@v4
        with:
          username: ${{ vars.DOCKER_USERNAME }}
          password: ${{ secrets.DOCKER_PASSWORD }}

Este paso utiliza las credenciales de Docker configuradas en la configuración del repositorio.

Construir y publicar la imagen

Finalmente, construye la imagen de producción final y publícala en tu registro. La siguiente configuración construye la imagen y la publica directamente en un registro.

      - name: Build and push Docker image
        uses: docker/build-push-action@v7
        with:
          push: ${{ github.event_name != 'pull_request' }}
          tags: ${{ steps.meta.outputs.tags }}
          annotations: ${{ steps.meta.outputs.annotations }}

En esta configuración:

  • push: ${{ github.event_name != 'pull_request' }} asegura que las imágenes solo se publiquen cuando el evento no sea una solicitud de extracción. De esta manera, el flujo de trabajo construye y prueba las imágenes para las solicitudes de extracción, pero solo las publica para las confirmaciones en la rama main.
  • tags y annotations utilizan las salidas de la acción de metadatos para aplicar automáticamente etiquetas y anotaciones coherentes a la imagen.

Atestaciones

El SBOM (Software Bill of Materials) y las atestaciones de procedencia mejoran la seguridad y la trazabilidad, asegurando que tus imágenes cumplan con los requisitos modernos de la cadena de suministro de software.

Con una pequeña cantidad de configuración adicional, puedes configurar docker/build-push-action para generar la lista de materiales de software (SBOM) y las atestaciones de procedencia para la imagen, en el momento de la construcción.

Para generar estos metadatos adicionales, debes realizar dos cambios en tu flujo de trabajo:

  • Antes del paso de construcción, agrega un paso que use docker/setup-buildx-action. Esta acción configura tu cliente de construcción de Docker con capacidades adicionales que el cliente predeterminado no admite.
  • Luego, actualiza el paso Build and push Docker image para habilitar también el SBOM y las atestaciones de procedencia.

Aquí está el fragmento actualizado:

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v4
      
      - name: Build and push Docker image
        uses: docker/build-push-action@v7
        with:
          push: ${{ github.event_name != 'pull_request' }}
          tags: ${{ steps.meta.outputs.tags }}
          annotations: ${{ steps.meta.outputs.annotations }}
          provenance: true
          sbom: true

Para más detalles sobre las atestaciones, consulta la documentación.

Conclusión

Con todos los pasos descritos en la sección anterior, aquí está la configuración completa del flujo de trabajo:

name: Build and Push Docker Image

on:
  push:
    branches:
      - main
  pull_request:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v6

      - name: Extract Docker image metadata
        id: meta
        uses: docker/metadata-action@v6
        with:
          images: ${{ vars.DOCKER_USERNAME }}/my-image

      - name: Log in to Docker Hub
        uses: docker/login-action@v4
        with:
          username: ${{ vars.DOCKER_USERNAME }}
          password: ${{ secrets.DOCKER_PASSWORD }}

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v4
      
      - name: Build and push Docker image
        uses: docker/build-push-action@v7
        with:
          push: ${{ github.event_name != 'pull_request' }}
          tags: ${{ steps.meta.outputs.tags }}
          annotations: ${{ steps.meta.outputs.annotations }}
          provenance: true
          sbom: true

Este flujo de trabajo implementa las mejores prácticas para construir y publicar imágenes de Docker usando GitHub Actions. Esta configuración se puede utilizar tal como está o ampliarse con características adicionales basadas en las necesidades de tu proyecto, como multiplataforma.

Lectura adicional

  • Obtén más información sobre configuraciones avanzadas y ejemplos en la sección GitHub Actions de Docker Build.
  • Para configuraciones de construcción más complejas, es posible que desees considerar Bake. (Consulta también la guía Dominar Buildx Bake).
  • Para conocer el servicio de construcción gestionado de Docker, diseñado para construcciones multiplataforma más rápidas, consulta Docker Build Cloud.