Módulo 2: Anatomy Of A Github Actions Workflow
1. Introducción: leer y escribir un workflow con criterio
Descripción
En el Módulo 1 instalaste act, corriste un "hola mundo" de punta a punta, y dejaste andes-cargo-infra/ listo — repositorio Git inicializado, .actrc pineado, .github/workflows/ creado, LocalStack corriendo en tu host. Todo eso funcionó, pero corriste el YAML de la lección 7 copiándolo, sin que nadie te explicara todavía, campo por campo, qué hace cada línea. Este módulo cierra esa brecha: vas a diseccionar la sintaxis completa de un workflow de GitHub Actions —on, jobs, steps, runs-on, uses, with, env— sobre un archivo real que vas a correr con tus propias manos, vas a aprender a disparar cualquier evento sin necesitar una cuenta de GitHub (act -e), y vas a aprender a pasarle secretos a esa simulación de forma segura. Sales de este módulo con el primer workflow que de verdad toca Andes Cargo: hello-andes-cargo.yml, corriendo dentro de andes-cargo-infra/.
Conexión con el módulo
Las lecciones 2 a 5 son la disección: anatomía completa de un bloque de workflow (lección 2), qué evento lo dispara y cuándo (lección 3), el disparador schedule con sintaxis cron (lección 4), y qué es una Action reutilizable, con el riesgo de cadena de suministro nombrado (lección 5). Las lecciones 6 y 7 son manos a la obra puras: escribes un evento a mano y se lo pasas a act con -e (lección 6), y le pasas secretos sin nunca comprometerlos en un commit (lección 7). La lección 8 —el proyecto de este módulo— junta todo: el primer workflow real de Andes Cargo, corrido con act push, con un step que confirma que el contenedor del job puede alcanzar el LocalStack que corre en tu host.
Qué te llevas del Módulo 1 (y qué falta)
Al cerrar el Módulo 1 sabías, en la práctica, que un workflow tiene un archivo .yml, que act -l lo lista, y que act push lo corre. Lo que todavía no sabías —y es exactamente lo que resuelve este módulo—:
- Qué significa cada campo de un workflow: por qué
onva primero, qué agrupajobs, por quéstepses una lista ordenada, qué decideruns-on, y la diferencia exacta entre un step que ejecuta un comando (run) y uno que reutiliza código de otra persona (uses). - Qué eventos existen, más allá del
pushdel Módulo 1:pull_request,workflow_dispatch, y por qué el filtrobranches:/paths:de un evento importa para un pipeline real comoapply.yml. - Cómo simular cualquier evento sin depender de tener una cuenta de GitHub ni un repositorio remoto — vas a escribir el payload de un Pull Request a mano.
- Cómo pasarle secretos a una corrida local sin escribirlos jamás en el YAML ni en un commit.
El mapa de este módulo: las 8 lecciones
| # | Lección | Qué practicas |
|---|---|---|
| 1 | Introducción (esta) | El mapa del módulo, qué falta del Módulo 1, qué vas a poder leer/escribir al terminar |
| 2 | Anatomía completa de un bloque de workflow | on/jobs/steps/runs-on/uses/with/env, diseccionados sobre un workflow real |
| 3 | Disparadores: push, pull_request, workflow_dispatch | Qué dispara un workflow y cuándo; filtros branches:/paths: |
| 4 | El disparador schedule y sintaxis cron | Sintaxis cron:; el caso de drift detection que llega en el Módulo 5 |
| 5 | Actions reutilizables: uses, with, y la cadena de suministro | actions/checkout@v4, hashicorp/setup-terraform@v3; tag vs. SHA |
| 6 | Manos a la obra: simulando eventos con act -e | Ejecutado: pr-event.json escrito a mano, act pull_request -e |
| 7 | Manos a la obra: pasando secretos a act | Ejecutado: .secrets (gitignorado), act --secret-file, -s |
| 8 | Proyecto: el primer workflow real de Andes Cargo | Ejecutado: hello-andes-cargo.yml, act push, LocalStack desde el runner |
Analogía del módulo: leer un contrato, no solo firmarlo
En el Módulo 1 corriste un workflow como quien firma un contrato sin leerlo, confiando en que el ejemplo funcionaba porque la lección lo decía. Este módulo te enseña a leer el contrato completo antes de firmarlo — y, más adelante, a redactar el tuyo propio. Un workflow de GitHub Actions tiene la misma estructura predecible que cualquier contrato bien escrito: primero dice bajo qué condiciones aplica (on — el equivalente a "este contrato entra en vigor cuando ocurra X"), después agrupa las obligaciones por bloque (jobs — "estas son las cláusulas del comprador, estas las del vendedor"), y dentro de cada bloque, una secuencia ordenada de pasos concretos (steps — "primero se paga la seña, después se firma la escritura, nunca al revés"). uses es la cláusula que dice "aplica el procedimiento estándar de tal notaría, no lo inventes de nuevo cada vez" — reutilizar trabajo ya hecho y probado, en vez de escribir cada verificación desde cero.
Vas a aprender a leer ese contrato completo en este módulo, sobre un archivo real, ejecutándolo mientras lo lees — no en abstracto.
Lo que NO cambia en este módulo
Sigues sin gastar un centavo, y sigues sin tocar la infraestructura de negocio de Andes Cargo. Ningún workflow de este módulo corre terraform plan ni terraform apply sobre los cuatro recursos reales —eso empieza recién en el Módulo 3—. El proyecto del Módulo 2, hello-andes-cargo.yml, hace lo mínimo necesario para probar que el camino hasta LocalStack funciona (awslocal sts get-caller-identity, un comando de solo lectura, sin crear ni modificar nada), no para desplegar nada todavía. Misma cuenta 000000000000, misma región us-east-1, mismo andes-cargo-infra/ heredado sin una sola línea de HCL nueva.
Antes y después de este módulo
ANTES (fin del Módulo 1) DESPUÉS (fin del Módulo 2)
"Copié el YAML de la lección "Sé qué significa cada campo:
y `act push` funcionó." on, jobs, steps, runs-on,
uses, with, env."
"Solo sé disparar `push`, y solo "Puedo simular cualquier
porque el workflow escuchaba push." evento —incluido un Pull
Request— escribiendo su
payload a mano."
"No sé cómo le pasaría credenciales "Sé pasar secretos sin
a un workflow sin escribirlas en escribirlos nunca en el
el archivo." YAML ni en un commit."Errores comunes
Pensar que un workflow es solo "una lista de comandos de terminal" (conceptual, la confusión central de este módulo). Qué pasa: alguien mira un workflow y lo lee como si steps fuera simplemente un script de bash con nombres bonitos, ignorando on, jobs, runs-on como "metadata que no importa". Por qué pasa: los steps son, superficialmente, lo más parecido a lo que ya conoces de una terminal. Cómo detectarlo: si al copiar un workflow ajeno solo miras la sección run: y saltas directo a lo que hace, sin fijarte qué evento lo dispara ni en qué imagen corre. Cómo corregirlo: on decide si el job corre; runs-on decide dónde; solo después de eso importa qué corre. Un step perfecto en un job que nunca se dispara no hace nada — la lección 2 de este módulo dedica tiempo igual a cada campo, no solo a steps.
Asumir que act -e es exclusivo de Pull Requests (de alcance, adelantado de la lección 6). Qué pasa: alguien entiende act -e archivo.json únicamente como "la forma de simular un PR", sin darse cuenta de que sirve para cualquier evento que necesite un payload más rico que el que act genera por defecto —un push con un mensaje de commit específico, un workflow_dispatch con inputs concretos—. Cómo corregirlo: la lección 6 lo muestra con pull_request porque es el caso más común en esta guía, pero el mecanismo (-e ruta/al/evento.json) es genérico para cualquier evento de GitHub Actions.
Ejercicios
Ejercicio 1 — Ordena los campos por su función. Sin mirar la lección 2 todavía, intenta emparejar cada campo con su función: on, jobs, steps, runs-on, uses, with, env. Funciones: (a) variables de entorno disponibles para los comandos; (b) qué evento dispara el workflow; (c) parámetros de entrada para una Action reutilizada; (d) la imagen/sistema donde corre un job; (e) la secuencia ordenada de acciones dentro de un job; (f) referencia a código reutilizable de otra persona o repositorio; (g) la agrupación de trabajo, cada una potencialmente en paralelo.
Ver solución
on → (b). jobs → (g). steps → (e). runs-on → (d). uses → (f). with → (c). env → (a). Si emparejaste la mayoría sin mirar, ya tienes la intuición correcta antes de entrar a la lección 2 — que va a confirmar cada una con un workflow real corriendo.
Ejercicio 2 — Explica la analogía del contrato con tus propias palabras. Sin usar la palabra "contrato", explica a un colega en dos frases por qué on va conceptualmente "antes" que jobs, y por qué jobs va "antes" que steps.
Ver solución
Una respuesta completa suena, más o menos, así: "on decide si el workflow corre en absoluto para este evento —sin eso, nada de lo que sigue importa—. jobs agrupa el trabajo en unidades que pueden correr en paralelo o depender unas de otras, y cada job necesita su propia secuencia de steps porque los pasos son órdenes, uno después del otro, dentro de esa unidad específica de trabajo." La jerarquía no es arbitraria: cada nivel acota al siguiente.
Ejercicio 3 — Anticipa el proyecto del módulo. Sin haber visto todavía hello-andes-cargo.yml (llega en la lección 8), predice: ¿qué tipo de comando esperarías que ese workflow ejecute para "confirmar que el contenedor del job puede llegar a LocalStack", sin crear ni modificar ningún recurso?
Ver solución
Un comando de solo lectura, que no cree ni modifique nada — la respuesta que da la lección 8 es awslocal sts get-caller-identity, el mismo comando que usaste en el Módulo 1 para confirmar tu identidad dentro del laboratorio LocalStack. Es la elección correcta precisamente porque no compromete nada: si falla, sabes que es un problema de red entre el contenedor del job y el host, no un error en un apply a medio terminar.
Resumen y siguiente paso
En esta lección viste el mapa completo de las 8 lecciones de este módulo, y la diferencia entre "correr un workflow porque la lección lo dice" y "leer un workflow con criterio". La analogía del contrato —condiciones primero (on), obligaciones agrupadas después (jobs), pasos ordenados al final (steps)— es la idea que vas a reutilizar en cada lección de este módulo.
Antes de avanzar deberías poder: nombrar las 8 lecciones de este módulo y qué aporta cada una; emparejar los siete campos principales de un workflow con su función; y explicar por qué on decide si el resto del archivo importa siquiera.
La lección 2 abre la disección con la anatomía completa de un workflow real —no un fragmento aislado— corrido con act mientras lo leemos.
Recursos
- GitHub Docs — Workflow syntax for GitHub Actions — la referencia completa de la sintaxis que este módulo va a diseccionar.
- nektosact.com — User Guide —
act -e,act --secret-filey-s, usados en las lecciones 6 y 7. terraform-and-iac-guide, Módulo 2 (NIEVA) — la misma progresión pedagógica (anatomía de sintaxis antes que proyecto real) aplicada a HCL en vez de YAML.