Cómo configurar un pipeline de CI/CD con GitHub Actions – Guía

Pipeline CI/CD con GitHub Actions: Guía Completa de Configuración

Pipeline CI/CD con GitHub Actions: Guía Completa de Configuración

En el desarrollo de software moderno, probar el código manualmente y ejecutar scripts de despliegue después de cada cambio es un cuello de botella que ralentiza la entrega e introduce errores humanos. Un pipeline CI/CD automatiza todo este proceso, desde las pruebas del código hasta su despliegue en producción. Esta guía te enseñará cómo configurar un pipeline CI/CD con GitHub Actions, una potente plataforma de automatización integrada, utilizando ejemplos prácticos de YAML del mundo real para que puedas enviar código más rápido y de forma más fiable.

Lo que Aprenderás

Al finalizar esta guía, comprenderás los conceptos fundamentales de Integración Continua y Despliegue Continuo (CI/CD) y podrás implementar un pipeline de múltiples etapas usando GitHub Actions. Aprenderás a escribir flujos de trabajo para pruebas automatizadas, construcción de imágenes Docker y despliegue de aplicaciones. Te llevarás código YAML funcional para probar, construir y desplegar tus propios proyectos, ya sean aplicaciones Python, Node.js o contenedorizadas.

Comprendiendo los Fundamentos de GitHub Actions

GitHub Actions es una plataforma de automatización basada en eventos integrada directamente en los repositorios de GitHub. Permite ejecutar flujos de trabajo automatizados activados por eventos como push, pull_request o release. En esencia, un flujo de trabajo se define en un archivo YAML ubicado en el directorio .github/workflows/ y consta de uno o más trabajos que se ejecutan en paralelo por defecto, cada uno con una serie de pasos.

Componentes Clave

• Evento (on): El desencadenante que inicia el flujo de trabajo, como push a una rama específica o un pull_request.
• Ejecutor (runs-on): La máquina donde se ejecuta el trabajo. ubuntu-latest es la opción más común y recomendada por su rendimiento y amplia disponibilidad de software.
• Pasos: Tareas individuales dentro de un trabajo. Pueden ser scripts de shell (run) o Acciones predefinidas (uses) del Marketplace de GitHub.
• Acciones: Unidades de código reutilizables, como actions/checkout@v4 para clonar tu repositorio o actions/setup-node@v4 para instalar Node.js.

Un Flujo de Trabajo Básico para Empezar

El flujo de trabajo más simple puede activarse con cada push. Crea un archivo en .github/workflows/main.yml para ejecutar un comando básico "Hola Mundo".

name: ejemplo
on: push
jobs:
  saludo:
    runs-on: ubuntu-latest
    steps:
      - run: echo "¡Hola, mundo CI/CD!"

Después de confirmar y enviar este archivo a tu repositorio, puedes ver la salida del trabajo en la pestaña "Actions" de tu repositorio de GitHub.

Construyendo un Pipeline CI Completo

La parte "CI" de un pipeline garantiza que los cambios en el código se prueben y verifiquen automáticamente antes de fusionarse. Esto generalmente incluye linting, verificación de tipos y ejecución de pruebas unitarias.

El Archivo de Flujo de Trabajo CI

Crea .github/workflows/ci.yml. Este flujo de trabajo se activa en cada push y pull_request a la rama main. El ejemplo siguiente muestra un pipeline completo para un proyecto Node.js, pero el patrón se aplica a otros lenguajes, como Python con actions/setup-python.

name: Pipeline CI

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      - run: npm ci
      - run: npm run lint

  test:
    runs-on: ubuntu-latest
    needs: lint
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      - run: npm ci
      - run: npm test

  build:
    runs-on: ubuntu-latest
    needs: [lint, test]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      - run: npm ci
      - run: npm run build

Características Clave Explicadas

1. Caché de Dependencias: La opción cache: 'npm' en actions/setup-node acelera significativamente el flujo de trabajo al reutilizar dependencias de ejecuciones anteriores.
2. Dependencias entre Trabajos: La palabra clave needs define el orden de ejecución. Por ejemplo, el trabajo build solo se ejecuta si los trabajos lint y test tienen éxito. Esto evita perder tiempo construyendo código defectuoso.
3. Variables de Entorno: Para servicios como bases de datos, puedes definir variables de entorno. Por ejemplo, un trabajo test puede iniciar un contenedor de servicio PostgreSQL y usar env para conectarse a él.

Escenarios Avanzados: Despliegues Contenedorizados y Multi-Entorno

Para aplicaciones modernas, el pipeline a menudo implica construir imágenes de contenedores y desplegarlas. La siguiente tabla describe estrategias comunes de despliegue y sus desencadenantes.

Comparación de Desencadenantes de Despliegue

Estrategia	Desencadenantes de Despliegue	Mejor para
Basada en Rama	push a main	Despliegue continuo del código de desarrollo más reciente.
Basada en Etiqueta	push de una nueva etiqueta (ej., v1.0.0)	Lanzar software estable y versionado a producción.
Basada en Lanzamiento	release publicado en GitHub	Lanzamientos oficiales de productos que también generan notas de versión.

Ejemplo: Desplegando un Contenedor Docker con un Flujo de Trabajo CI/CD

Este ejemplo completo muestra un pipeline que prueba una aplicación Python, construye una imagen Docker y la envía a un registro. Utiliza una serie de Acciones Docker oficiales para una construcción segura y de alto rendimiento.

Crea .github/workflows/deploy.yml:

name: Pipeline CI/CD Completo

on:
  push:
    branches: [ main ]
  release:
    types: [published]

env:
  DOCKER_HUB_USERNAME: ${{ secrets.DOCKER_HUB_USERNAME }}
  DOCKER_HUB_TOKEN: ${{ secrets.DOCKER_HUB_TOKEN }}
  IMAGE_NAME: mi-app

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v4
        with:
          python-version: '3.9'
      - run: pip install -r requirements.txt
      - run: pytest

  build-and-push:
    runs-on: ubuntu-latest
    needs: test
    if: github.event_name == 'push' || github.event_name == 'release'
    steps:
      - uses: actions/checkout@v4
      - name: Configurar Docker Buildx
        uses: docker/setup-buildx-action@v3
      - name: Iniciar sesión en Docker Hub
        uses: docker/login-action@v3
        with:
          username: ${{ env.DOCKER_HUB_USERNAME }}
          password: ${{ env.DOCKER_HUB_TOKEN }}
      - name: Extraer metadatos
        id: meta
        uses: docker/metadata-action@v5
        with:
          images: ${{ env.DOCKER_HUB_USERNAME }}/${{ env.IMAGE_NAME }}
          tags: |
            type=ref,event=branch
            type=semver,pattern={{version}}
            type=raw,value=latest,enable={{is_default_branch}}
      - name: Construir y enviar
        uses: docker/build-push-action@v5
        with:
          context: .
          push: true
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
          cache-from: type=gha
          cache-to: type=gha,mode=max

  deploy:
    runs-on: ubuntu-latest
    needs: build-and-push
    if: github.event_name == 'release'
    steps:
      - name: Ejecutar Script de Despliegue
        run: |
          echo "Desplegando imagen ${{ env.DOCKER_HUB_USERNAME }}/${{ env.IMAGE_NAME }}:${{ github.event.release.tag_name }}"

Importante: Gestión de Secretos

Para que el flujo de trabajo anterior funcione, debes almacenar tus credenciales de forma segura en tu repositorio de GitHub. Navega a Settings > Secrets and variables > Actions y añade los siguientes secretos:

1. DOCKER_HUB_USERNAME: Tu nombre de usuario de Docker Hub.
2. DOCKER_HUB_TOKEN: Un Token de Acceso Personal de Docker Hub con permisos de lectura/escritura.

⚠️ Advertencia de Seguridad: Nunca codifiques contraseñas, tokens u otros datos sensibles directamente en tus archivos YAML. Utiliza siempre los secretos de GitHub, que están cifrados y solo son accesibles durante las ejecuciones del flujo de trabajo.

Preguntas Frecuentes

¿Cuáles son los primeros pasos para configurar un pipeline CI/CD con GitHub Actions?

Para empezar, crea un directorio .github/workflows en tu repositorio. Dentro, crea un archivo YAML (ej., ci.yml) y define tu name, on (eventos desencadenantes como push) y jobs (las tareas a ejecutar). Confirma y envía este archivo para iniciar tu primer flujo de trabajo automatizado.

¿Puedo usar GitHub Actions para ejecutar pruebas en pull requests?

Sí, probar en pull requests es un caso de uso fundamental. Al configurar el desencadenante on como pull_request para la rama main, el flujo de trabajo se ejecutará automáticamente en cada nuevo pull request, garantizando la calidad del código antes de fusionar.

¿Cómo construyo y envío una imagen Docker con un flujo de trabajo de GitHub Actions?

Puedes usar acciones compuestas oficiales como docker/login-action, docker/setup-buildx-action y docker/build-push-action. Esto simplifica el proceso, maneja automáticamente la autenticación y habilita funciones como el almacenamiento en caché de construcción y las construcciones multi-plataforma.

¿Es posible desplegar en GitHub Pages usando GitHub Actions?

Sí. Puedes usar la acción comunitaria JamesIves/github-pages-deploy-action. La configuras con la carpeta que contiene tu sitio construido, y ella maneja las operaciones git para confirmar y enviar los cambios a la rama gh-pages.

¿Cuál es la diferencia entre un evento desencadenante push y release?

Un evento push activa el flujo de trabajo cada vez que se envía código a una rama especificada. Un evento release se activa cuando se publica un Lanzamiento de GitHub. push se usa típicamente para CI y despliegues de staging, mientras que release se usa a menudo para desplegar en producción.

Fuentes

• Set up GitHub Actions CI/CD pipeline · Issue #176 (Ejemplos prácticos de YAML para CI, E2E y despliegue)
• DevOps: Set up GitHub Actions CI/CD pipeline · Issue #19 (Muestra linting, verificación de tipos y verificación de construcción)
• GitHub - kamrun111/GitHubActionTest (Un ejemplo simple y amigable para principiantes de CI/CD en Python)
• @jamesives/github-pages-deploy-action (Documentación para desplegar en GitHub Pages)
• GitHub - CarlosQuintero8/cicdsimulation (Muestra un pipeline de múltiples etapas con pruebas, construcción y despliegue en GitHub Pages)
• GitHub - anuragstark/Py-app-CI-CD-Pipeline- (Guía completa que incluye despliegue con Docker y Minikube)
• Automated CI/CD with GitHub Actions, starting from scratch (Un tutorial sobre cómo construir flujos de trabajo CI/CD de forma incremental)
• Extend App with GitHub Actions · AccelByte Documentation (Ejemplo de despliegue activado por un evento de lanzamiento)
• Configure CI/CD for your C++ application · Docker Docs (Muestra cómo configurar GitHub Actions con Docker Hub)
• Hello CI World · HSF Training (Un tutorial básico para crear y ejecutar un primer flujo de trabajo)

— Editorial Team