StackPractices
intermediate Por Mathias Paulenko

Guía completa de CI/CD con GitHub Actions

Construye pipelines CI/CD desde cero con GitHub Actions. Cubre workflows, runners, builds en matriz, caché, secretos, entornos, estrategias de despliegue y workflows reutilizables.

Introducción

GitHub Actions es la plataforma CI/CD integrada en GitHub: compila, prueba y despliega el código directamente desde tu repositorio, sin levantar un servidor de CI externo. Esta guía recorre un pipeline real de principio a fin: lint y tests en cada pull request, builds en matriz sobre varias versiones de Node, caché de dependencias, un despliegue a staging y una liberación a producción con aprobación.

Al terminar tendrás un ci.yml completo listo para soltar en un repositorio, además del criterio para adaptarlo: qué runner elegir, cuándo una matriz justifica los minutos, cómo mantener los secretos fuera de los logs y cómo evitar que dos despliegues pisen un mismo entorno.

El alcance aquí es el camino a producción. Para ejemplos de workflows listos para copiar — matrices, secrets, environments, composite actions — consulta la receta de GitHub Actions. Para la teoría de pipelines (trunk-based, quality gates, promoción), la guía de pipelines CI/CD cubre el panorama completo.

flowchart diagram: push / PR

Cómo funciona un workflow

Un workflow es un archivo YAML en .github/workflows/. Tres conceptos lo gobiernan todo: los eventos que lo disparan (push, pull_request, schedule, workflow_dispatch), los jobs que corren en paralelo por defecto en runners separados, y los steps dentro de cada job que se ejecutan en secuencia — un run de shell o una action publicada vía uses.

Workflow de CI simple

# .github/workflows/ci.yml
name: CI

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

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm

      - name: Install dependencies
        run: npm ci

      - name: Lint
        run: npm run lint

      - name: Test
        run: npm test -- --coverage

      - name: Build
        run: npm run build

      - name: Upload coverage
        uses: actions/upload-artifact@v4
        with:
          name: coverage
          path: coverage/

Cada pieza justifica su lugar: npm ci instala desde el lockfile para builds reproducibles, cache: npm en setup-node ahorra entre 30 y 60 segundos por ejecución, y upload-artifact deja el reporte de cobertura descargable desde el resumen de la ejecución — útil cuando un test pasa en local pero falla en CI.

Triggers

on:
  push:
    branches: [main]
    paths:
      - "src/**"
      - "tests/**"
      - ".github/workflows/**"
  pull_request:
    types: [opened, synchronize, reopened]
  schedule:
    - cron: "0 2 * * *"  # Diario a las 2 AM UTC
  workflow_dispatch:       # Disparo manual
    inputs:
      environment:
        description: "Entorno de destino"
        required: true
        default: staging
        type: choice
        options:
          - staging
          - production
  release:
    types: [published]

El filtro paths es la optimización de CI más barata que existe: un commit que solo toca documentación no debería quemar diez minutos de tests. pull_request.types ya vale opened, synchronize, reopened por defecto, así que solo hace falta declararlo para otros tipos como ready_for_review. Dos detalles que conviene conocer: los workflows programados dejan de ejecutarse tras 60 días de inactividad del repositorio, y los inputs de workflow_dispatch permiten construir un botón manual de “deploy a staging” directamente en la pestaña Actions.

Runners

Un runner es la máquina donde corre tu job. Los runners hospedados por GitHub son VMs efímeras: recibes una máquina limpia, ejecuta tu job y se destruye. El ubuntu-latest estándar ofrece 4 vCPUs, 16 GB de RAM y 14 GB de SSD, suficiente para la mayoría de builds.

jobs:
  test:
    runs-on: ubuntu-latest    # 4 CPU, 16GB RAM, 14GB SSD
  build:
    runs-on: ubuntu-22.04     # Fijar a una versión concreta
  macos:
    runs-on: macos-latest     # macOS para builds de iOS
  windows:
    runs-on: windows-latest   # Windows para builds .NET

Dos factores mandan en la elección. Coste: en repositorios privados, los minutos de Actions se facturan distinto según el SO — Linux es el más barato, mientras Windows y macOS consumen la cuota varias veces más rápido. Úsalos solo cuando la carga lo exija. Tooling: fija ubuntu-22.04 si tu build se rompe en una imagen más nueva en lugar de confiar en que el alias -latest no se mueva.

Runners grandes (GitHub Enterprise)

jobs:
  build:
    runs-on: ubuntu-latest-large  # 16 CPU, 64GB RAM

Runners auto-hospedados

jobs:
  deploy:
    runs-on: self-hosted
    steps:
      - uses: actions/checkout@v4
      - name: Deploy
        run: ./deploy.sh

El auto-hospedaje tiene sentido para acceso a redes privadas, hardware especial (GPUs, ARM) o cargas que superan las especificaciones hospedadas. La contrapartida la cargas tú: la máquina no es efímera, así que el estado se filtra entre ejecuciones, y correr código de pull requests no confiables en tu propia infraestructura es un riesgo real — el propio GitHub recomienda no usar runners auto-hospedados con forks públicos.

Builds en matriz

Una matriz expande la definición de un job en N jobs paralelos, uno por cada combinación que declares. Esto corre los tests sobre tres versiones de Node y tres sistemas operativos, menos una exclusión, más una combinación experimental extra:

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node-version: [18, 20, 22]
        os: [ubuntu-latest, macos-latest, windows-latest]
        exclude:
          - os: macos-latest
            node-version: 18
        include:
          - node-version: 20
            os: ubuntu-latest
            experimental: true
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
      - run: npm ci
      - run: npm test

Cada combinación es un job completo con su propio runner y sus propios minutos — una matriz 3×3 son nueve jobs. Ese paralelismo es justamente la idea, pero cuesta: una suite de 10 minutos se convierte en 90 minutos facturados a través de la matriz. El tope es de 256 jobs por ejecución.

Fail-fast frente a continue-on-error

strategy:
  fail-fast: false          # No cancelar el resto de la matriz si falla un job
  max-parallel: 4           # Limitar los jobs concurrentes

fail-fast: true (el valor por defecto) cancela toda la matriz en cuanto una pata falla — feedback rápido, pero pierdes la señal de si el fallo es específico de una plataforma. Ponlo en false durante una migración de compatibilidad, cuando precisamente quieres ver todos los fallos de una vez. No metas los despliegues en la matriz: desplegar es un asunto secuencial y ligado a un entorno, no una permutación de tests.

Caché

La caché restaura archivos entre ejecuciones para que los jobs no vuelvan a descargar el mundo entero. setup-node (y sus equivalentes para Python, Go, Java) puede cachear el directorio del gestor de paquetes con una sola línea:

- uses: actions/setup-node@v4
  with:
    node-version: 20
    cache: npm              # Cachea ~/.npm automáticamente

Para cualquier otra cosa, actions/cache da control explícito:

- name: Cache build output
  uses: actions/cache@v4
  with:
    path: |
      dist/
      .cache/
    key: ${{ runner.os }}-build-${{ hashFiles('**/package-lock.json') }}
    restore-keys: |
      ${{ runner.os }}-build-

La key es la identidad de la caché: aquí cambia cada vez que lo hace package-lock.json. Cuando la clave exacta falla, restore-keys recurre a una coincidencia por prefijo — recuperas la caché de la semana pasada en lugar de nada. Dos límites a recordar: un repositorio guarda como máximo 10 GB de cachés (las entradas menos recientemente usadas se expulsan), y una caché sin acceso durante 7 días se borra.

Caché de capas de Docker

- name: Set up Docker Buildx
  uses: docker/setup-buildx-action@v3

- name: Build and cache
  uses: docker/build-push-action@v5
  with:
    context: .
    push: false
    tags: myapp:latest
    cache-from: type=gha
    cache-to: type=gha,mode=max

type=gha guarda las capas de Docker en el mismo backend de caché — reconstruir una imagen tras un cambio de una línea tarda segundos en lugar de un build completo. Usa mode=max para cachear todas las capas, no solo las de la imagen final.

Secretos, variables y permisos

Los secretos son valores cifrados que se inyectan en tiempo de ejecución — tokens, claves, credenciales. Los secretos de repositorio son visibles para todos los workflows del repo; los de entorno se limitan a un entorno de despliegue y pueden quedar detrás de una aprobación. Las variables (vars) son el mismo mecanismo para configuración no sensible, como URLs.

steps:
  - name: Deploy to production
    env:
      API_KEY: ${{ secrets.API_KEY }}
      DB_PASSWORD: ${{ secrets.DB_PASSWORD }}
    run: ./deploy.sh
jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: production    # Requiere aprobación
    steps:
      - name: Deploy
        env:
          PROD_TOKEN: ${{ secrets.PROD_TOKEN }}
        run: ./deploy.sh
steps:
  - name: Use variable
    env:
      API_URL: ${{ vars.API_URL }}
    run: echo "Deploying to $API_URL"

GitHub enmascara automáticamente en los logs los valores de secretos registrados, pero el enmascarado solo funciona sobre la cadena exacta — si la transformas (base64, concatenación, imprimirla por líneas), la máscara falla. Genera y enmascara los valores dinámicos de forma explícita:

- name: Generate token
  id: token
  run: echo "value=$(openssl rand -hex 32)" >> $GITHUB_OUTPUT

- name: Use token
  env:
    TOKEN: ${{ steps.token.outputs.value }}
  run: |
    echo "::add-mask::$TOKEN"
    curl -H "Authorization: Bearer $TOKEN" https://api.example.com

Restringir GITHUB_TOKEN

Cada workflow recibe un GITHUB_TOKEN que, por defecto en muchos repositorios, tiene un alcance amplio de lectura y escritura. Redúcelo a lo que el job necesita:

permissions:
  contents: read      # solo checkout
  packages: write     # solo para el job de docker push
  id-token: write     # solo al usar OIDC para autenticación cloud

Define permissions a nivel de workflow como valor restrictivo por defecto, y amplíalo por job. Si despliegas a AWS o GCP, prefiere la federación OIDC frente a un secreto cloud de larga duración: id-token: write permite al job emitir una credencial temporal contra un rol en la nube — nada estático que filtrar ni rotar.

Entornos y aprobaciones de despliegue

Los entornos son destinos de despliegue con nombre, con sus propios secretos, URLs y reglas de protección. Encadenar deploy-staging → deploy-production con needs te da un pipeline de promoción donde producción nunca corre sobre un despliegue a staging fallido:

jobs:
  deploy-staging:
    runs-on: ubuntu-latest
    environment:
      name: staging
      url: https://staging.example.com
    steps:
      - uses: actions/checkout@v4
      - name: Deploy
        run: ./deploy.sh staging

  deploy-production:
    needs: deploy-staging
    runs-on: ubuntu-latest
    environment:
      name: production
      url: https://example.com
    steps:
      - uses: actions/checkout@v4
      - name: Deploy
        run: ./deploy.sh production

Revisores obligatorios

Se configura en GitHub: Settings → Environments → production → Required reviewers. El workflow se pausa hasta la aprobación — una puerta humana que aparece en la UI de Actions como despliegue pendiente, con la URL del entorno adjunta para verificarlo con un clic. También puedes añadir un temporizador de espera para forzar un periodo de soak antes de que producción tome el job.

Dependencias entre jobs y concurrencia

needs convierte una lista plana de jobs en un DAG. Lint y test corren en secuencia, luego build espera a ambos, y deploy solo se dispara en main:

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm run lint

  test:
    needs: lint              # Espera a que lint pase
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm test

  build:
    needs: [lint, test]      # Espera a los dos
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm run build

  deploy:
    needs: build
    if: github.ref == 'refs/heads/main'  # Solo en main
    runs-on: ubuntu-latest
    steps:
      - run: ./deploy.sh

Grupos de concurrencia

La pieza que falta en la mayoría de pipelines hechos a mano: sin concurrency, dos pushes a main corren dos despliegues a la vez, y gana el último en escribir — quizá sobrescribiendo un despliegue nuevo con uno viejo. Un grupo de concurrencia serializa las ejecuciones por rama:

concurrency:
  group: deploy-${{ github.ref }}
  cancel-in-progress: true

Con cancel-in-progress: true, un push nuevo cancela la ejecución obsoleta — ideal para CI, donde solo importa el último commit. Para despliegues usa cancel-in-progress: false: el segundo despliegue espera en cola detrás del primero en lugar de matar una liberación a producción a medias.

Workflows reutilizables

Cuando la misma lógica de job aparece en varios repos — o en varios workflows del mismo — extráela como workflow invocable:

# .github/workflows/test-suite.yml
name: Test Suite

on:
  workflow_call:
    inputs:
      node-version:
        required: false
        type: number
        default: 20
    secrets:
      API_KEY:
        required: false

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ inputs.node-version }}
          cache: npm
      - run: npm ci
      - run: npm test
        env:
          API_KEY: ${{ secrets.API_KEY }}

Se invoca desde otro workflow como un job completo:

# .github/workflows/ci.yml
name: CI

on:
  push:
    branches: [main]

jobs:
  test:
    uses: ./.github/workflows/test-suite.yml
    with:
      node-version: 22
    secrets:
      API_KEY: ${{ secrets.API_KEY }}

  deploy:
    needs: test
    runs-on: ubuntu-latest
    steps:
      - run: ./deploy.sh

Un workflow reutilizable es un job entero — con su propio runner y su propio hueco en el grafo de needs. Para compartir unos pocos steps dentro de un job, la herramienta correcta es una composite action (ver la receta de workflows reutilizables):

# .github/actions/setup-and-test/action.yml
name: 'Setup and Test'
description: 'Install deps and run tests'

inputs:
  node-version:
    required: false
    default: '20'
  test-command:
    required: false
    default: 'npm test'

runs:
  using: 'composite'
  steps:
    - uses: actions/setup-node@v4
      with:
        node-version: ${{ inputs.node-version }}
    - name: Install dependencies
      shell: bash
      run: npm ci
    - name: Run tests
      shell: bash
      run: ${{ inputs.test-command }}

Quien la llama la usa como un único step: - uses: ./.github/actions/setup-and-test, con sus propios inputs en with:. Las composite actions corren dentro del job que las invoca y comparten su filesystem — no se levanta ningún runner adicional.

Ejecución condicional

Las expresiones if condicionan steps o jobs enteros según el contexto, y las funciones de chequeo de estado permiten reaccionar a cómo fueron los pasos anteriores:

steps:
  - name: Only on main
    if: github.ref == 'refs/heads/main'
    run: ./deploy.sh

  - name: Only on PRs
    if: github.event_name == 'pull_request'
    run: npm run test:e2e

  - name: Skip on docs change
    if: !contains(github.event.head_commit.message, '[skip ci]')
    run: npm test

  - name: On failure
    if: failure()
    run: ./notify-slack.sh

  - name: Always run (cleanup)
    if: always()
    run: ./cleanup.sh

Las dos que más usarás: failure() para notificar cuando se rompe el build, y always() para limpieza que debe correr incluso tras un fallo — sin ella, el step se salta por defecto. Ojo al detalle: always() también corre en ejecuciones canceladas, y por eso existe cancelled() como chequeo aparte.

Build y push de Docker

El flujo completo de contenedores — buildx para la caché multicapa, metadata-action para etiquetas coherentes, GHCR como registro:

jobs:
  docker:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
    steps:
      - uses: actions/checkout@v4

      - uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - uses: docker/metadata-action@v5
        id: meta
        with:
          images: ghcr.io/${{ github.repository }}
          tags: |
            type=ref,event=branch
            type=sha,prefix={{branch}}-
            type=raw,value=latest,enable={{is_default_branch}}

      - 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

La estrategia de etiquetas importa más que el build: cada push recibe una etiqueta rama-sha12345 rastreable hasta el commit, latest solo se mueve en la rama por defecto, y packages: write queda limitado a este job. Desplegar la imagen después es otro asunto — la guía de estrategias de despliegue cubre los patrones rolling, blue-green y canary.

Pipeline completo: la integración

Todo lo anterior compone un único workflow. Este es el archivo que realmente commiteas:

# .github/workflows/ci.yml
name: CI/CD

on:
  push:
    branches: [main]
    paths: ["src/**", "tests/**", "package*.json", ".github/workflows/**"]
  pull_request:
    branches: [main]

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

permissions:
  contents: read

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
    strategy:
      fail-fast: false
      matrix:
        node-version: [18, 20, 22]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
          cache: npm
      - run: npm ci
      - run: npm test

  build:
    needs: [lint, test]
    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 build
      - uses: actions/upload-artifact@v4
        with:
          name: dist
          path: dist/
          retention-days: 7

  deploy-staging:
    needs: build
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    environment:
      name: staging
      url: https://staging.example.com
    steps:
      - uses: actions/download-artifact@v4
        with:
          name: dist
      - run: ./deploy.sh staging

  deploy-production:
    needs: deploy-staging
    runs-on: ubuntu-latest
    environment:
      name: production      # La aprobación de revisores lo bloquea
      url: https://example.com
    steps:
      - uses: actions/download-artifact@v4
        with:
          name: dist
      - run: ./deploy.sh production

Léelo como una historia: cada pull request recibe lint más una matriz de tests sobre tres versiones. Main recibe lo mismo, y luego un build cuyo artefacto fluye aguas abajo — el despliegue a staging lo descarga en lugar de reconstruir. Producción espera a staging y a una aprobación humana. El grupo de concurrencia cancela ejecuciones obsoletas de PR pero encola los despliegues. permissions: contents: read es el único permiso que todo el archivo necesita.

Las piezas que adaptarás primero: cambia npm por tu stack (setup-python/setup-go tienen la misma convención de cache:), añade el job de docker de la sección anterior si publicas contenedores, y apunta ./deploy.sh a lo que sea tu plataforma real — SSH, una CLI de nube, o un repo GitOps donde subes la etiqueta de imagen (la guía de GitOps con ArgoCD cubre ese patrón).

Buenas prácticas

  • Fija las versiones de las actions — usa @v4 en lugar de @main para evitar ataques a la cadena de suministro; en jobs sensibles, fija por SHA de commit
  • Usa npm ci, no npm install — instalaciones deterministas desde el lockfile
  • Cachea las dependencias — ahorra 30-60 segundos por job
  • Usa entornos para los despliegues — aprobaciones obligatorias para producción
  • Define grupos de concurrency — cancela ejecuciones obsoletas en la misma rama, encola despliegues
  • Usa workflows reutilizables — DRY para tu pipeline entre repositorios
  • Minimiza el alcance de los secretos — prefiere secretos de entorno sobre los de repositorio
  • Usa la clave permissions — restringe GITHUB_TOKEN al mínimo necesario
  • Corre los tests en paralelo — reparte las suites entre los jobs de la matriz
  • Usa if: always() para la limpieza — asegura que los recursos se liberen
  • Etiqueta las imágenes Docker con el SHA — rastrea cada despliegue hasta su commit
  • Usa filtros de paths — salta los workflows cuando solo cambian documentos

Errores comunes

  • No fijar las versiones de las actions — @main puede introducir cambios rompientes o código malicioso
  • Usar npm install en lugar de npm ci — builds no deterministas
  • No definir concurrency — dos pushes compiten por el mismo despliegue
  • Abusar de secrets.GITHUB_TOKEN — tiene permisos amplios por defecto
  • No usar environment en los despliegues a producción — sin puerta de aprobación
  • Escribir secretos en los archivos de workflow — son visibles en la UI
  • No cachear las dependencias — los builds lentos queman minutos de Actions
  • Ejecutar todo en cada push — usa filtros de paths para saltar workflows irrelevantes
  • No usar if: failure() para las notificaciones — los fallos pasan desapercibidos
  • No probar los workflows en local — usa act para correrlos antes de hacer push

Ver también

Referencias externas:

Preguntas frecuentes

¿Cuánto cuesta GitHub Actions?

En repositorios públicos, los runners hospedados estándar son gratis. En privados, los planes de pago incluyen una cuota mensual de minutos (2.000 en el plan Free) — y los minutos de Linux cuentan a razón de 1× mientras que Windows y macOS consumen la cuota más rápido. Los runners auto-hospedados siempre son gratis, pero la máquina la pagas tú.

¿Cuándo usar una matriz en lugar de jobs separados?

Usa una matriz cuando el cuerpo del job es idéntico y solo varían los inputs — versiones de Node, sistemas operativos, shards de tests. Escribe jobs separados cuando los pasos difieren: un job de despliegue comparte casi nada con un job de tests, y forzarlo en la matriz solo añade ruido de if.

¿Workflow reutilizable o composite action?

Un workflow reutilizable es un job completo: tiene su propio runner y su propio hueco en el grafo de needs, y puede invocarse entre repositorios. Una composite action es un paquete de steps que corre dentro del job que la llama. Comparte jobs con workflows reutilizables; comparte steps con composite actions.

¿Cómo ejecuto GitHub Actions en local?

Usa act — corre workflows en contenedores Docker en tu máquina:

# Instalar act
brew install act

# Correr un workflow concreto
act -W .github/workflows/ci.yml

# Correr con secretos
act -W .github/workflows/ci.yml --secret-file .secrets
¿Cómo evito que dos despliegues compitan entre sí?

Mete los despliegues en un grupo de concurrency con cancel-in-progress: false — la segunda ejecución espera en cola hasta que termine la primera. Reserva cancel-in-progress: true para los checks de CI, donde solo importa el último commit.

¿Cómo depuro un workflow que falla?
  1. Activa el log de depuración por step: define ACTIONS_STEP_DEBUG=true como secreto del repositorio
  2. Activa el log de diagnóstico del runner: define ACTIONS_RUNNER_DEBUG=true
  3. Usa una sesión tmate para depuración interactiva:
- name: Debug
  uses: mxschmitt/action-tmate@v3
  if: failure()
  timeout-minutes: 30