Depura GitHub Actions desde tu Terminal con `gh`

Si tu flujo de trabajo para depurar GitHub Actions empieza abriendo tres pestañas del navegador, probablemente es más lento de lo necesario.

La mayoría de fallos en CI no requieren la interfaz de Actions para nada. El CLI gh te da el ciclo completo desde tu terminal: encontrar el run roto, leer el fallo, reintentarlo y verlo en vivo. Una vez que te acostumbras, volver al navegador se siente torpe.

Encuentra el run

gh run list --limit 10

Empieza aquí. Esto muestra los runs recientes, su estado y qué los activó.

Si un workflow lleva una eternidad en queued, lo vas a ver de inmediato. Si quieres hacer scripting con la salida, agrega --json y ahórrate el copiar y pegar.

Lee solo lo que falló

gh run view <run-id> --log-failed

Este es el comando que me hacía falta.

No siempre necesitas el volcado completo de logs. Usualmente necesitas el paso que falló. --log-failed va directo a la parte útil, lo cual importa mucho cuando tu workflow crece más allá de un par de jobs.

Si necesitas todo, cambia a --log. Si estás depurando un matrix build, pipea la salida a grep y sigue adelante.

Reintenta solo lo que se rompió

gh run rerun <run-id> --failed

Esto reintenta solo los jobs que fallaron, más todo lo que depende de ellos. Eso es usualmente lo que quieres.

Si el fallo vino de un test flaky, un timeout de registro, o cualquier otra tontería transitoria de CI, reejecutar todo el workflow es solo tiempo y cómputo desperdiciado.

Un detalle: no puedes reintentar un workflow mientras todavía está en progreso. El CLI puede devolver un error que suena como si el archivo del workflow fuera inválido. En la práctica, muchas veces solo significa que el run no ha terminado aún.

Si quieres reintentar un job específico, primero obtén el ID correcto:

gh run view <run-id> --json jobs --jq '.jobs[] | {name, databaseId}'

Usa databaseId con --job. No confíes en agarrar un número cualquiera de la interfaz web esperando que coincida con lo que el CLI espera.

Míralo en vivo

gh run watch <run-id>

Esto transmite el run mientras sucede. Es lo más cercano a tail -f para Actions, y es mucho mejor que refrescar el navegador cada 20 segundos.

Si ya vives en la terminal, esto se siente como la pieza que faltaba.

Dispara un run sin hacer push de un commit

gh workflow run <workflow-file>.yml --ref <branch>

Si un workflow soporta workflow_dispatch, úsalo. Es una de las formas más simples de probar cambios en workflows sin crear commits desechables solo para picar al CI.

Si tu workflow no expone workflow_dispatch, vale la pena arreglarlo. Los triggers manuales hacen la depuración más fácil y los demos más limpios.

El 403 que te hace perder demasiado tiempo

Un número sorprendente de fallos en Actions se reducen a una cosa: GITHUB_TOKEN no tiene el permiso que tu workflow necesita, y el mensaje de error usualmente es menos claro de lo que debería.

Si tu workflow necesita escribir en el repositorio o actualizar un pull request, declara los permisos explícitamente:

permissions:
  contents: write
  pull-requests: write

No te fíes de los defaults y después te sorprendas cuando una escritura falla a mitad de una automatización. Pide el mínimo que necesitas, a propósito.

El ciclo que realmente uso

gh run list                       # encuentra el run
gh run view <run-id> --log-failed # lee el fallo
gh run rerun <run-id> --failed    # reintenta solo lo que se rompió
gh run watch <run-id>             # sigue el reintento en vivo

Eso es suficiente para una buena parte de la depuración diaria de Actions. El navegador sigue teniendo su lugar, pero no necesita ser tu opción por defecto.

Referencia completa: cli.github.com/manual/gh_run

Depura GitHub Actions desde tu Terminal con gh