Parte 1: Entendiendo Github AW

Imaginemos un mundo donde las mejoras en un repositorio son enviadas automáticamente cada mañana, listas para ser revisadas. Los issues son automáticamente categorizados, fallas en la integración continua analizadas, la documentación se mantiene actualizada y los tests mejorados. Todo esto definido a través de unos simples archivos markdown y que sigue los principios de Continuous AI.

captionless image

Coding Agents, en Github Actions

Con coding agents, describes la automatización que quiere realizar en lenguaje natural. En vez de escribir scripts complejos que manejen la categorización de un issue, revisión de código, o manejo de despliegues, simplemente defines lo que quieres que suceda. El agente de IA entiende el contexto del repositorio, interpreta la situación y decide que acciones tomar, todo a partir de una pocas líneas de texto. Veamos un ejemplo:

// file: .github/workflows/issue-analyzer.md
---
on:                        # Trigger: cuándo se ejecuta
  issues:
    types: [opened]
permissions: read-all      # Security: solo lectura por defecto
safe-outputs:              # Operaciones de escritura permitidas
  add-comment:
---
# Analizador de Issues
Analiza el issue actual y pregunta por mas detalles si la solicitud no está clara.

Con esto, cada vez que alguien cree un issue en nuestro repositorio, el trigger detectará este evento y ejecutará el contenido de nuestro workflow, en este caso el agente revisará el issue y de no ser muy clara la descripción, le solicitará a la persona que lo realizó que de mas detalles. Si quieres conocer mas detalles sobre la sección de YAML que hay al inicio del archivo puedes leer sobre frontmatter.

Pero esto no es todo, adicional a crear el archivo markdown debemos “compilarlo” para que Github lo pueda interpretar como un action. Como bien dice la guía de inicio rápido de los Github Actions, estos deben tener como extensión de nombre de archivo el formato YAML/YML. Así que para compilar el markdown que tenemos en lenguaje natural, primero debemos cerciorarnos de tener instalado el CLI de Github. Aquí dejo el enlace de instalación. Adicional a esto debemos instalar la extensión de los agentic workflows de la siguiente manera:

gh extension install github/gh-aw

Una vez verifiquemos la instalació del CLI, podemos ejecutar el siguiente comando:

gh aw compile

Con esto, el CLI va a recorrer la carpeta .github/workflows en busca de archivos markdown que cumplan con el formato del frontmatter y los va a “compilar” a formato YAML, dando como resultado algo similar a esto:

# file: .github/workflows/issue-analyzer.lock.yaml
jobs:
  activation:
    run: check authorization
  agent: needs[activation] # Contenedor aislado
    permissions: contents: read # Solo lectura!
    run: copilot -p "Analyze package.json for breaking changes..."
  safe-outputs: needs[agent] # Contenedor aislado
    run: gh issue comment add ...
    permissions: issues: write

Es importante tener en cuenta que cada que se realicen modificaciones al archivo markdown hay que ejecutar el comando que lo compila a formato YAML. De no hacerlo nos va a saltar un error al momento de ejecutar el action indicando que los archivos no están sincronizados.

Seguridad

Hoy en día es muy importante ser cautelosos con la información que le proveemos a un modelo de inteligencia artificial, y por esto es que Github diseño un entorno seguro en el que el agente se puede ejecutar sin causar repercusiones como eliminar un base de datos por “error”, o reescribir toda una base de código sin una autorización previa. Aquí dejo un diagrama para entender mejor cómo se ejecutan estos flujos de trabajo agénticos.

Diagrama de seguridad AW

El agente corre un entorno aislado (sandbox), por defecto solo tiene permisos de lectura y no tiene acceso a hacer modificaciones en el repositorio (crear issues, pull requests…).
Las peticiones que realiza el agente pasan por un proxy que filtra y verifica que el agente solo llame los dominios permitidos en [allowlists](https://github.github.io/gh-aw/reference/frontmatter/#network-permissions-network) .
Enrutamiento centralizado con un MCP Gateway que administra la comunicación entre el agente y servicios externos, también valida las tools que el modelo invoca.
Cada tool y MCP invocado por el agente se ejecuta en un contenedor aislado que tiene capas de proxy adicionales para el tráfico de salida.

Safe Outputs

Las salidas seguras, como su nombre lo dice, aseguran que el agente no tenga acceso de escritura a recursos externos, por ejemplo, en el prompt no le podemos indicar que cree un pull request o un issue, esto debe ser indicado en el frontmatter del archivo markdown. De esta forma se garantiza que el agente no pueda modificar ningún aspecto del repositorio si no se le ha indicado en los safe outputs. En el ejemplo que veíamos anteriormente teníamos en los safe outputs el tipo add-comment lo que permite al agente “escribir” un comentario en el issue.

Pero no es el agente quién escribe el comentario si no que, en su salida indica el texto del comentario que quiere escribir, esto pasa por un filtro, y una vez validado se escribe el comentario a través de la API de Github.

Existen varios tipos de safe outputs, entre ellos existen los handoffs, que también se pueden usar en VSCode localmente, para que la salida de un agente sea la entrada de otro. Por ejemplo podría tener un agente que se encargue de planear los cambios a realizar en un repositorio, y que el resultado de ese agente (ya sea un archivo plano con el plan a ejecutar) se le pase a otro agente que sea especializado en implementar esos cambios. Aquí un ejemplo de cómo se podría ver en los agentic workflows:

---
on:
  issues:
    types: [opened]
safe-outputs:
  create-issue:
    assignees: ["copilot"]
---
Analyze issue and break down into implementation tasks

Para mas información sobre los tipos de safe outputs, ingresa aquí.

AI Engines

Estos flujos de trabajo soportan múltiples proveedores de IA:

Github Copilot (Recomendado, por defecto)
Claude
Codex
Gemini

Cabe resaltar que Github Copilot ofrece soporte para conectar MCP’s

Para cambiar el motor de IA simplemente en el frontmatter agregamos la siguiente línea:

---
on:
  issues:
    types: [opened]
safe-outputs:
  create-issue:
    assignees: ["copilot"]
engine: copilot # claude, codex, gemini
---

En caso de querer usar Claude, debemos generar primero una API Key en la developer platform de Anthropic y setearla con el siguiente comando:

gh aw secrets set ANTHROPIC_API_KEY --value "YOUR_ANTHROPIC_API_KEY"

También se puede agregar desde la web de Github, dentro del repositorio en la ruta Settings > Secrets and variables > Actions > Repository Secrets. Aquí puedes encontrar mas información.

Patrones de diseño

captionless image

En esta infografía quise resumir un poco todos los posibles casos de uso que pueden tener estos flujos de trabajo. En esta primera parte quiero abordar solamente lo que son las Trial Ops.

Trial Ops

Es un patrón de diseño para administrar ejecuciones de prueba o experimentaciones, y es que antes de agregar un flujo de trabajo a un repositorio real, podemos ejecutarlo en uno de prueba que simule ser ese repositorio objetivo. Para ejecutar eso localmente simplemente llamamos el siguiente comando:

gh aw trial ./.github/workflows/my-workflow.md

Con esto podemos verificar que el archivo markdown esté bien formado y no tenga problemas de sintaxis o semánticos en el frontmatter. Al ejecutar este comando sin especificar un repositorio, la línea de comandos nos va a preguntar si queremos crear un repositorio de prueba llamado gh-aw-trial , al aceptar, el CLI crearía el repositorio y subiría allí el workflow para ejecutarlo. En caso de que queramos realizar pruebas en un repositorio sin tener que agregar el workflow o clonarlo manualmente, se puede ejecutar lo siguiente.

gh aw trial ./.github/workflows/my-workflow.md --clone-repo myorg/real-repo

Esto clona el repositorio para que el workflow pueda acceder al código real sin necesidad de afectar el repositorio real. Para no extender mucho el artículo aquí dejo el enlace sobre Trial Ops.

En esta primera parte quise abordar sobre lo que son Agentic Workflows, un poco de su estructura interna y propiedades principales para empezar a construirlos. En los siguientes artículos empezaremos a ver mas casos de uso con funciones mas avanzadas.