Consejos y Trucos para Depurar GitHub Actions
Un workflow que funcionaba ayer ahora falla con un error críptico. No has cambiado nada. Los logs muestran un muro de pasos colapsados, y en algún lugar allí se encuentra el problema real. Este escenario frustra a todo ingeniero que mantiene pipelines de CI/CD.
La depuración efectiva de GitHub Actions requiere saber qué herramientas existen y cuándo usarlas. Esta guía cubre las técnicas estables y duraderas que te ayudan a diagnosticar fallos de workflow rápidamente, sin perder tiempo en enfoques que no funcionarán.
Puntos Clave
- Habilita el logging de depuración con los secrets
ACTIONS_STEP_DEBUGyACTIONS_RUNNER_DEBUGpara obtener mayor visibilidad sobre los fallos de workflow - Añade pasos de diagnóstico para mostrar detalles del entorno y usa
continue-on-error: truetemporalmente para aislar pasos inestables - Valida workflows localmente con actionlint y nektos/act antes de hacer push para detectar errores tempranamente
- Fija las versiones de las actions a tags específicos o SHAs para prevenir roturas inesperadas por cambios upstream
Habilita el Logging de Depuración para Mayor Visibilidad
Cuando los logs estándar de GitHub Actions no revelan suficiente detalle, habilita el logging de depuración. Dos secrets de repositorio controlan este comportamiento:
- ACTIONS_STEP_DEBUG: Establécelo en
truepara ver salida detallada de cada paso - ACTIONS_RUNNER_DEBUG: Establécelo en
truepara información de diagnóstico a nivel de runner
También puedes activar el modo de depuración sin modificar secrets. Al re-ejecutar un workflow fallido, selecciona “Re-run jobs” y marca la opción “Enable debug logging”. Esto proporciona trazas detalladas para esa ejecución específica sin afectar ejecuciones futuras.
El visor de logs de GitHub soporta streaming en vivo y visualización expandida de logs recientes, facilitando el seguimiento de jobs de larga duración en tiempo real. Usa la función de búsqueda dentro de los pasos expandidos para localizar errores específicos en lugar de desplazarte por todo.
Añade Pasos de Diagnóstico a tu Workflow
A veces necesitas información de depuración personalizada. Añade pasos que muestren detalles del entorno antes de operaciones críticas:
- name: Debug environment
run: |
echo "Node version: $(node --version)"
echo "Working directory: $(pwd)"
echo "Event: ${{ github.event_name }}"
env | sortPara pasos que fallan de manera impredecible, usa continue-on-error: true temporalmente. Esto permite que los pasos subsiguientes se ejecuten, exponiendo si el fallo se propaga o permanece aislado:
- name: Potentially flaky step
id: tests
continue-on-error: true
run: npm test
- name: Capture state after tests
if: always()
run: echo "Tests completed with status ${{ steps.tests.outcome }}"Elimina continue-on-error una vez que hayas identificado la causa raíz.
Valida Workflows Localmente Antes de Hacer Push
Hacer push de commits solo para probar la sintaxis del workflow desperdicia tiempo y desordena tu historial. Usa actionlint para detectar errores de YAML y errores de expresiones antes de que lleguen a GitHub:
actionlint .github/workflows/Para pruebas locales más completas, nektos/act ejecuta workflows en contenedores Docker que aproximan el entorno del runner de GitHub. No replicará todo—la retención de artefactos y las versiones exactas de software difieren—pero valida el orden de ejecución de pasos y detecta problemas obvios de configuración.
act -P ubuntu-latest=catthehacker/ubuntu:act-latestAmbas herramientas proporcionan ciclos de retroalimentación rápidos que reducen significativamente los ciclos de troubleshooting de workflows.
Discover how at OpenReplay.com.
Comprende el Comportamiento de los Artefactos
Los artefactos en GitHub Actions están limitados al ámbito del job. Múltiples jobs no pueden subir al mismo nombre de artefacto bajo el sistema v4—los intentos entrarán en conflicto en lugar de fusionarse. Siempre asigna a cada job un nombre de artefacto único, especialmente en builds de matriz o paralelos, para evitar fallos de subida y asegurar una recuperación predecible.
Usa Workflows Reutilizables para Reducir la Inestabilidad
La lógica de workflow duplicada entre repositorios introduce inconsistencia. Cuando los mismos pasos existen en múltiples lugares, la depuración se vuelve más difícil porque las correcciones deben propagarse por todas partes.
Los workflows reutilizables centralizan patrones comunes. Cuando corriges un bug o mejoras la confiabilidad en un lugar, todos los workflows que lo invocan se benefician. Este enfoque también facilita aplicar la depuración de CI/CD de manera consistente en toda tu organización.
Fija las Versiones de Actions y Evita Actions Obsoletas
Referencia las actions por SHA o tags de versión específicos en lugar de @main o @master. Las referencias no fijadas pueden romper workflows cuando ocurren cambios upstream:
# Prefiere esto
uses: actions/checkout@v4
# Evita esto
uses: actions/checkout@mainMuchas actions auxiliares de depuración antiguas usan versiones obsoletas de Node.js. GitHub advierte sobre estas en los logs del workflow. Reemplázalas con alternativas mantenidas para evitar fallos inesperados cuando GitHub eventualmente elimine el soporte para runtimes legacy.
Protege los Secrets en la Salida de Depuración
El logging de depuración expone más información, lo que crea riesgo. Nunca hagas echo de secrets directamente, ni siquiera en pasos de depuración. GitHub enmascara secrets conocidos, pero valores derivados o coincidencias parciales podrían filtrarse. Revisa la salida de depuración antes de compartir logs públicamente o en reportes de issues.
Conclusión
El troubleshooting de workflows se vuelve manejable cuando conoces las técnicas correctas. Habilita el logging de depuración para visibilidad, añade pasos de diagnóstico estratégicamente, valida localmente con actionlint o act, y mantén consistencia mediante workflows reutilizables. Estas mejores prácticas de GitHub Actions aplican independientemente de cómo evolucione la plataforma—son fundamentos que hacen la depuración de CI/CD más rápida y menos frustrante.
Preguntas Frecuentes
Los fallos aleatorios a menudo provienen de cambios en dependencias externas, como actualizaciones de versiones de actions no fijadas, problemas en registros de paquetes, o limitación de tasa. Timeouts de red y restricciones de recursos en runners compartidos también pueden causar fallos intermitentes. Habilita el logging de depuración y verifica si el fallo se correlaciona con momentos específicos o disponibilidad de servicios externos.
Usa el contexto steps con el atributo id del paso. Primero, asigna un id a tu paso, luego referencia sus outputs usando la sintaxis steps.step_id.outputs.output_name. Para el resultado de un paso con continue-on-error, usa steps.step_id.outcome que devuelve success, failure, cancelled, o skipped.
Sí. Usa actionlint para validar sintaxis YAML y expresiones localmente. Para pruebas más exhaustivas, nektos/act ejecuta workflows en contenedores Docker que simulan el entorno del runner de GitHub. Aunque act no puede replicar todas las características de GitHub, detecta la mayoría de errores de configuración y valida el orden de ejecución de pasos antes de hacer push.
ACTIONS_STEP_DEBUG habilita salida detallada para pasos individuales del workflow, mostrando información detallada sobre la ejecución de cada action. ACTIONS_RUNNER_DEBUG proporciona información de diagnóstico de nivel más bajo sobre el runner mismo, incluyendo configuración del entorno y operaciones internas. Para la mayoría de escenarios de depuración, ACTIONS_STEP_DEBUG proporciona suficiente detalle.
Understand every bug
Uncover frustrations, understand bugs and fix slowdowns like never before with OpenReplay — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data. Check our GitHub repo and join the thousands of developers in our community.
