Depurar workflows en GitHub Actions implica revisar logs paso a paso, validar variables de entorno y confirmar que cada secret esté disponible en el runner correcto. Aquí entenderás cómo leer los logs, detectar errores silenciosos y corregir un workflow file que parece exitoso pero falla por dentro.

Cómo se conecta una action de AWS con secrets en GitHub Actions

Cuando una action del marketplace necesita credenciales sensibles, la forma recomendada es pasarlas mediante secrets configurados en el repositorio.

En el marketplace aparecen más de 500 resultados al buscar AWS. Un buen ejemplo es la action Deploy Docker to AWS EC2, que toma una aplicación Docker y la sube a una instancia EC2. Su documentación muestra un workflow file llamado Basic deploy que se dispara con cada push a la rama main y corre sobre Ubuntu.

El único step del job usa la etiqueta uses para invocar la action bitovi/github-actions-deploy-docker-to-ec2@0.5.0. Después aparece el parámetro with, donde se pasan los valores que la action requiere: aws_access_key_id, aws_secret_access_key, aws_default_region y un archivo .env.

¿Para qué sirve la palabra clave with en una action? Permite enviarle parámetros internos a la action, respetando la indentación de YAML para que cada valor quede como atributo del objeto.

Esos valores no se escriben en texto plano. Se extraen de la cuenta de AWS, se guardan en la sección de secrets del repositorio con los mismos nombres que pide la action, y se referencian con la sintaxis ${{ secrets.NOMBRE }}.

Cómo leer los logs de un workflow run fallido

En la pestaña Actions verás todos los workflow runs ejecutados, exitosos y fallidos. Al entrar a uno fallido aparece el mensaje típico: Process completed with exit code 1, que indica que el proceso no terminó bien.

Cada job tiene una estructura predecible que conviene conocer:

• Setup job: muestra el sistema operativo del runner (por ejemplo Ubuntu), la imagen usada, permisos del token interno de GitHub y otra información del entorno.
• Checkout: clona el repositorio dentro del runner. Es una action que se usa en casi todos los workflows.
• Steps personalizados: corren los comandos definidos en el workflow file.
• Post de cada action: paso oculto que limpia archivos y procesos creados por la action para liberar el runner.
• Complete job: cierra procesos huérfanos y termina la ejecución.

En un caso real, el job de inicializar el repo falló al intentar crear un commit vacío. El log recomendaba ejecutar git pull antes, porque la rama remota ya tenía cambios. Como los steps de un job son secuenciales, todos los steps posteriores quedaron cancelados, marcados con un símbolo distinto al check.

Por qué un workflow puede mostrar éxito pero fallar silenciosamente

Un check verde no siempre significa que todo funcionó como esperabas. Por eso el hábito de leer los logs es tan importante como escribir el workflow.

En el ejemplo de la clase anterior, el step saludos secretos debía imprimir Hola, Juan, hoy es lunes seguido de una contraseña oculta. El log mostró el saludo incompleto: faltaba la palabra inicial. El check aparecía verde, pero el resultado estaba mal.

¿Por qué una variable de entorno no aparece en otro job? Cada job corre en un runner distinto, es decir, en máquinas virtuales separadas que no comparten variables entre sí.

Al abrir los detalles del comando, la lista de variables de entorno mostraba dia_de_la_semana=lunes, pero la variable saludo no existía en ese runner. Revisando el workflow file, la variable saludo estaba declarada solo dentro del job saludo_a_variables, no a nivel global del workflow. El segundo job intentaba leerla sin haberla recibido nunca.

Cómo corregir variables de entorno entre jobs

La solución es declarar la variable también en el job que la necesita. Editas el workflow file, copias el bloque env con saludo y lo pegas dentro del segundo job. Después haces commit con un mensaje tipo fix: agregar variable a job y vuelves a correr el workflow desde la pestaña Actions.

Al re ejecutar, el step imprime el saludo completo y la contraseña queda enmascarada por seguridad, que es justo el comportamiento esperado de un secret.

Qué hábitos adoptar al crear un nuevo workflow

Depurar bien un workflow en GitHub Actions se vuelve mucho más fácil con tres prácticas concretas:

1. Revisar los logs completos de cada step, incluso cuando el check sea verde.
2. Validar el alcance de cada variable de entorno: si vive en el workflow, en el job o en el step.
3. Probar el workflow varias veces tras cada cambio para confirmar que el comportamiento es el esperado.

Con estos hábitos vas a detectar errores silenciosos, entender mejor cómo se aíslan los runners y construir pipelines más confiables. Cuéntame en los comentarios qué error silencioso has encontrado tú al revisar logs.