Tu pipeline de GitHub Actions falla y no sabes por donde empezar. El log es largo, el error no es claro y el deploy esta bloqueado. En este post te explico el workflow de diagnostico completo con las causas mas comunes y como solucionarlas. Si aun no tienes tu primer pipeline montado, empieza por el post de CI/CD con GitHub Actions desde cero.

Paso 1: Leer el log completo

El error visible en la vista resumen no siempre es el error real. Ve al step fallido, expande el log completo y busca las primeras lineas rojas — ahi suele estar la causa raiz.

En el log busca palabras clave:
ERROR / FATAL / failed / Permission denied
no such file / command not found
Cannot find module / Exit code: 1

Paso 2: Activar el modo debug

GitHub Actions tiene un modo debug que muestra mucho mas detalle. Añade estos secretos en Settings – Secrets and variables – Actions:

ACTIONS_RUNNER_DEBUG = true
ACTIONS_STEP_DEBUG = true

O activa debug al relanzar: Re-run jobs - Enable debug logging

Causas mas comunes de pipelines fallidos

Causa 1: Secreto que no existe o nombre incorrecto

Error tipico: Error: Input required and not supplied

Verificar en Settings - Secrets and variables - Actions
El nombre debe coincidir EXACTAMENTE (mayusculas/minusculas)

- name: Deploy
  with:
    password: secrets.MI_PASSWORD  # debe existir exactamente asi

Causa 2: Permisos insuficientes del GITHUB_TOKEN

Error tipico: Error: Resource not accessible by integration

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      packages: write
      id-token: write
      pull-requests: write

Causa 3: Tests que fallan en CI pero no en local

El runner es una maquina limpia. Las causas mas habituales son variables de entorno que tienes en local pero no en CI, o servicios externos no disponibles. Solucion: usar services para bases de datos:

jobs:
  test:
    runs-on: ubuntu-latest
    services:
      postgres:
        image: postgres:16
        env:
          POSTGRES_PASSWORD: testpassword
          POSTGRES_DB: testdb
        ports:
          - 5432:5432
        options: --health-cmd pg_isready --health-interval 10s
    steps:
      - uses: actions/checkout@v4
      - run: npm test
        env:
          DATABASE_URL: postgresql://postgres:testpassword@localhost:5432/testdb

Causa 4: Syntax error en el YAML del workflow

Error tipico: Invalid workflow file

Validar antes de hacer push:
npm install -g @actions/actionlint
actionlint .github/workflows/ci.yml

Errores frecuentes:
- Indentacion incorrecta (usa espacios, nunca tabs)
- Falta el caracter pipe para scripts multi-linea
- Comillas mal cerradas en strings

Causa 5: Action o version obsoleta

Error tipico: Unable to resolve action

Usa siempre versiones actualizadas:
uses: actions/checkout@v4
uses: actions/setup-node@v4
uses: docker/login-action@v3

Causa 6: Timeout del job

Error tipico: job has exceeded the maximum execution time

jobs:
  build:
    runs-on: ubuntu-latest
    timeout-minutes: 30
    steps:
      - name: Build
        timeout-minutes: 10
        run: npm run build

Workflow de diagnostico para pipelines fallidos

1. Abre el workflow fallido en GitHub y haz clic en el step con la X roja
2. Lee las primeras lineas del log buscando el error real
3. Si no es claro, activa debug con ACTIONS_STEP_DEBUG=true
4. Verifica que todos los secretos existen y tienen el nombre correcto
5. Comprueba los permisos del GITHUB_TOKEN en el job
6. Si el test falla solo en CI, revisa variables de entorno y servicios externos
7. Valida el YAML con actionlint antes del siguiente push
8. Revisa si alguna action uso una version obsoleta

Truco: ejecutar el pipeline localmente con act

act es una herramienta que ejecuta tus workflows de GitHub Actions en local usando Docker, sin necesidad de hacer push a GitHub:

Instalar act:
brew install act  # macOS
curl https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash  # Linux

Ejecutar el workflow en local:
act

Ejecutar un job especifico:
act -j test

Pasar secretos:
act -s MI_SECRETO=valor

Conclusion

Los pipelines fallidos en GitHub Actions casi siempre tienen una causa clara en el log. El 80% de los casos son secretos mal configurados, permisos insuficientes o dependencias que no se instalan en el runner. Con el modo debug activo y el workflow de diagnostico de este post, encontraras la causa en minutos.

En el proximo post salimos del CI/CD y arrancamos el Modulo de Cloud con Como pasar de sysadmin a DevOps: hoja de ruta completa. Tienes algun error de GitHub Actions recurrente que no aparece aqui? Cuentamelo en los comentarios.