GitHub Agentic Workflows: Guía Completa

Aprende a configurar GitHub Agentic Workflows para automatizar tu repositorio con lenguaje natural en lugar de YAML

La semana pasada te comentaba las novedades que GitHub había presentado este 2026 para poder escalar runners sin Kubernetes con el nuevo Scale Set Client, si no lo has leído te lo dejo por aquí 👇🏻

GitHub Actions es una tecnología que me encanta, pero en el momento que escala tienes que pelearte con archivos YAML interminables para configurar nuestras integraciones continuas. La lógica se vuelve más compleja y frágil que el propio código de la aplicación que intenta desplegar.

Lo que acaba de lanzar GitHub en technical preview es conceptualmente diferente e interesante. Han presentado los GitHub Agentic Workflows, una iniciativa de GitHub Next y Microsoft Research que nos permite definir flujos de automatización en repositorios escribiendo en lenguaje natural (Markdown) en lugar de YAML puro. Y lo más importante: ejecutándolos bajo un entorno altamente seguro, aislado y auditable dentro de la infraestructura de GitHub Actions que ya conocemos.

Ojo, esto no es un sustituto de GitHub Actions. Piensa en ello como un complemento para acciones periódicas no deterministas.

Resumen ejecutivo (TL;DR)

GitHub Agentic Workflows es una nueva capa de abstracción para crear automatizaciones en repositorios usando lenguaje natural en lugar de programación imperativa, ejecutada por modelos de IA con fuertes medidas de seguridad.

• Permite describir la intención de un workflow como “revisa este issue” o “crea un reporte de estado cada día a X hora” en un archivo Markdown, y el agente decide la mejor manera de ejecutarlo.

• Introduce el concepto de Continuous AI, diseñado para complementar, no reemplazar, a tu CI/CD determinista tradicional.

• Prioriza la seguridad ejecutando los modelos con permisos de solo lectura por defecto y utilizando un mecanismo de safe-outputs para autorizar explícitamente operaciones de escritura como crear Pull Requests o comentar.

• Requiere un paso de compilación local que traduce tus instrucciones en un archivo .lock.yml blindado, el cual es interpretado finalmente por GitHub Actions.

El problema del YAML y el nacimiento del Continuous AI

Si lo piensas fríamente, GitHub Actions tradicional te obliga a pensar como una máquina. Tienes que definir el paso exacto, la herramienta exacta, el comando bash exacto y cómo procesar la salida con jq o awk. Esto es ideal para compilar un binario de Go o ejecutar tests unitarios porque quieres que el resultado sea determinista: la misma entrada debe producir la misma salida siempre.

Sin embargo, en el día a día del mantenimiento de un repositorio hay cientos de tareas que no son deterministas. Piensa en las issues, la actualización de la documentación cuando cambia el código, la revisión de accesibilidad o la sugerencia de refactorizaciones menores. Son tareas que requieren contexto, comprensión del lenguaje natural y un cierto grado de conocimiento técnico.

Aquí es donde entra el concepto de Continuous AI.

• El CI/CD se encarga de las tareas predecibles y repetitivas.

• El continuous AI se encarga de aplicar inteligencia automatizada y sistemática a la colaboración de software.

Los Agentic Workflows son la primera implementación real y nativa de este concepto en GitHub, permitiendo que agentes como Claude Code, OpenAI Codex o GitHub Copilot actúen como colaboradores asíncronos en tu equipo.

Más sobre Continuous AI: https://githubnext.com/projects/continuous-ai/

Diferencia entre Workflows Tradicionales vs Agénticos

En un workflow tradicional de GitHub Actions, tú defines un conjunto de reglas imperativas (si pasa X, ejecuta el script Y). La máquina no entiende lo que está haciendo, solo sigue instrucciones.

En un workflow agéntico, tú defines el estado final deseado usando lenguaje natural y proporcionas herramientas (tools), mientras que la IA se encarga de leer el contexto, analizar la situación y tomar decisiones sobre cómo alcanzar ese estado.

La trampa en la que cae mucha gente es pensar que podemos simplemente meter un script de Python que llame a la API de OpenAI dentro de un Action normal y corriente. Y sí, poder se puede, pero es un peligro a nivel de arquitectura. Hacer eso otorga a un agente de IA un acceso excesivo y sin restricciones a tu entorno de ejecución. Los Agentic Workflows solucionan este problema de raíz integrándose con GitHub Actions desde una filosofía de diseño centrada en la seguridad y el principio de mínimo privilegio.

Seguridad: Cómo evitar que la IA destruya tu repositorio

De nada sirve tener un agente muy inteligente si un usuario puede hacer un ataque de prompt injection en un issue y lograr que la IA borre tu base de datos o filtre secretos del repositorio (si, si que se puede… ).

La arquitectura de seguridad de GitHub Agentic Workflows se basa en defensa en profundidad en 4 capas:

1. Aislamiento y solo lectura por defecto: Cuando el agente se ejecuta en el contenedor de GitHub Actions, lo hace en un entorno aislado (sandboxed) y sus permisos son estrictamente de solo lectura. No puede hacer git push ni modificar el repositorio directamente.

2. Safe Outputs (Salidas seguras): Si el agente está en modo solo lectura, hace su trabajo mediante un concepto llamado safe-outputs.

   Tú defines en la configuración qué operaciones tiene permitidas (por ejemplo, create-pull-request o create-issue).

   El agente solo puede solicitar que se ejecute esa acción preaprobada con el contenido sanitizado, y es la infraestructura la que realiza la escritura, no el modelo de IA. Esto garantiza que siempre quede un rastro auditable (una PR, un comentario) y que nosotros, los humanos tengamos siempre la última palabra antes de integrar código.

3. Integración con MCP (Model Context Protocol): Ya hemos hablado de MCP anteriormente en la newsletter. Este protocolo permite conectar modelos de IA con fuentes de datos externas de forma segura. Los Agentic Workflows exponen capacidades específicas del entorno de GitHub (leer archivos, consultar issues) mediante servidores MCP controlados y aislados en la red.

4. Compilación y Lock Files: El código fuente de tu workflow es un archivo Markdown (.md), pero GitHub Actions no sabe leer Markdown. La herramienta de línea de comandos gh aw compile procesa tu Markdown, valida la seguridad, revisa los permisos y genera un archivo .lock.yml que es el que realmente se ejecuta. Este archivo bloqueado es el que evita inyecciones en tiempo de ejecución.

Flujo de diseño a implementación de un workflow agéntico de GitHub

Si quieres profundizar en la parte de seguridad de los Workflows agénticos te recomiento esta página de documentación de GitHub.

Multi-Agente por diseño: Copilot, Claude o COdex

Un detalle que me encanta es la neutralidad del motor de IA. Aunque por defecto utiliza GitHub Copilot, la arquitectura está diseñada para ser agnóstica respecto al agente que haya por debajo.

Puedes configurar el flujo para que el motor de inferencia sea Claude de Anthropic o Codex de OpenAI. Esto es vital porque evita el vendor lock-in a nivel de prompt. Mantienes tu workflow en lenguaje natural intacto y simplemente cambias el motor en la configuración para comparar resultados, evaluar costes o aprovechar las fortalezas específicas de cada modelo.

Guía paso a paso: Cómo crear tu primer Agentic Workflow

Lo primero, necesitas preparar tu entorno local porque la generación del YAML final ocurre en tu máquina.

Primero, asegúrate de tener instalado la CLI de GitHub (gh) y luego instala la extensión específica para flujos agénticos:

gh extension install github/gh-aw

Ahora necesitas autenticar el entorno para que pueda hacer llamadas al modelo de IA. Debes generar un Personal Access Token (PAT) en la configuración de desarrollador de GitHub asegurándote de marcar el scope Copilot Requests. Una vez lo tengas, guárdalo como secreto en tu repositorio usando la CLI:

gh aw secrets set COPILOT_GITHUB_TOKEN --value TU_PAT_AQUI

La estructura básica se compone de un archivo Markdown ubicado en la ruta habitual .github/workflows/nombre-del-flujo.md. Este archivo tiene dos partes claramente diferenciadas: un Frontmatter en formato YAML en la cabecera (donde defines las reglas estrictas) y el cuerpo en Markdown (donde defines la lógica agéntica). Si leiste el post sobre Agent Skills seguramente te resulte familiar este formato.

Ejemplo real de un workflow agéntico: Solucionar Issues del repositorio

Para enseñarte un ejemplo de cómo se combinan el determinismo y la IA, fíjate en este ejemplo adaptado de un flujo para mejorar la calidad de los issues entrantes a un repositorio.

Imagina que un usuario abre un issue con muy poca información, sin etiquetas y con un título vago. El objetivo es que la IA lo analice, le dé un formato estructurado y asigne etiquetas pertinentes.

Primero creamos el archivo .github/workflows/mejorar-issues.md:

# Esta primera sección es el Frontmatter
---
on:
  issues:
    types: [opened]
permissions:
  issues: read
safe-outputs:
  update-issue:
    title:
    body:
tools:
  github:
    toolsets: [issues]
---
# Mejorador de Calidad de Issues

Tu objetivo es mejorar los nuevos issues para que sean claros, estén bien estructurados y sean fáciles de entender para el equipo de desarrollo.

## Contexto del Issue
| Campo  | Valor          |
| ------ | -------------- |
| Número | #$ISSUE_NUMBER |
| Autor  | @$ISSUE_AUTHOR |
| Título | $ISSUE_TITLE   |
| Cuerpo | $ISSUE_BODY    |

## Tareas a realizar

1. Obtener contexto:
   - Lee el archivo README para entender el propósito del proyecto.
   - Lista las etiquetas disponibles en el repositorio.

2. Traducción y Claridad:
   - Si el issue NO está en inglés, tradúcelo al inglés manteniendo intactos todos los detalles técnicos y logs de error.

3. Mejora del Título:
   - Añade un prefijo estandarizado basado en el tipo de issue detectado (Bug, Feature, Docs, Refactor).
   - Ejemplo: "[Bug] Error de login con caracteres especiales".

4. Reestructuración del Cuerpo:
   - Utiliza secciones claras en formato Markdown.
   - Para bugs, asegúrate de crear las secciones "Descripción", "Pasos para reproducir" y "Comportamiento esperado vs actual".

5. Aplicar cambios:
   - Utiliza la herramienta de salida segura para actualizar el issue #$ISSUE_NUMBER con el nuevo título y cuerpo.
   - Añade un comentario breve resumiendo los cambios realizados.
   - Asigna entre 1 y 3 etiquetas relevantes basadas en el contexto del repositorio.

## Reglas estrictas
- Nunca cambies el significado técnico original reportado por el usuario.
- Si el issue ya está perfectamente redactado, realiza cambios mínimos o ninguno.
- Mantén un tono de ayuda profesional.

Aquí hay varios elementos de diseño que merecen un análisis profundo.

• En el Frontmatter, utilizamos el trigger estándar de GitHub Actions (on: issues), muy similar a como lo hacemos en GitHub Actions. La sección permissions está restringida únicamente a lectura, limitando la superficie de ataque si algo sale mal.

• En safe-outputs le estamos diciendo a la infraestructura de ejecución: “El modelo de IA tiene permiso exclusivo para actualizar el título y el cuerpo de un issue existente” (update-issue). Si el agente alucina e intenta borrar una rama del repositorio, la petición será interceptada y bloqueada en la capa de seguridad porque no está declarada explícitamente como una salida segura.

• En la sección de tools, limitamos el servidor MCP de GitHub únicamente al conjunto de herramientas (toolsets) relacionadas con issues, evitando que la IA pierda tiempo o recursos explorando partes irrelevantes de la API de GitHub.

• Finalmente, el cuerpo del documento mezcla variables de entorno inyectadas en tiempo real ($ISSUE_TITLE, $ISSUE_BODY) dentro de una tabla de contexto, seguidas de instrucciones paso a paso muy precisas y reglas de restricción.

¿Cómo lanzar el workflow agéntico? Compilación y ejecución

El archivo Markdown de arriba no hace nada por sí solo. Tienes que compilarlo ejecutando:

gh aw compile

Este comando analiza tu archivo Markdown, valida que las herramientas y los safe-outputs solicitados existen y son seguros, y genera un archivo .github/workflows/mejorar-issues.lock.yml junto con una carpeta interna .github/aw. El archivo YAML generado es ilegible para un humano (y no se debe editar), pero contiene toda la lógica de orquestación, aprovisionamiento de contenedores y proxy MCP necesarios para ejecutar el flujo de manera segura en la infraestructura de Actions.

Debes hacer un commit y hacer push tanto del .md como del .lock.yml a tu repositorio. A partir de ese momento, cada vez que alguien abra un issue, GitHub Actions levantará el entorno y ejecutará la lógica agéntica.

GitHub Agentic Workflows

Patrones de diseño para casos de uso reales: ¿Qué es DailyOps y MultiRepoOps?

Una vez que entiendes la mecánica, las posibilidades son muchas y seguro que ya tienes alguna idea en mente de cómo integrarlo en algún repositorio.

Al basarse en la lectura de contexto natural, se abren patrones de automatización que antes eran imposibles de mantener mediante scripts bash. La propia documentación oficial categoriza estos casos de uso en varios patrones, siendo DailyOps y Continuous Documentation los más potentes.

Fíjate en este ejemplo de un workflow programado diariamente para generar un reporte de estado del equipo:

---
on:
  schedule: daily
permissions:
  contents: read
  issues: read
  pull-requests: read
safe-outputs:
  create-issue:
    title-prefix: "[estado-equipo] "
    labels: [reporte, estado-diario]
    close-older-issues: true
---

## Reporte Diario de Issues

Genera un reporte de estado diario positivo y estructurado para el equipo en forma de issue de GitHub.

## Qué debes incluir

- Actividad reciente del repositorio (issues, PRs, discusiones, releases, cambios en el código).
- Seguimiento del progreso, recordatorios de objetivos del sprint y aspectos destacados.
- Estado general del proyecto y recomendaciones.
- Próximos pasos accionables para los mantenedores.

Este workflow se levanta cada mañana, el agente consume el estado actual del repositorio, obtiene los datos de los Pull Requests mergeados, lee los comentarios de los issues cerrados y sintetiza todo en un formato sencillo de leer.

Otros patrones de diseño que se están explorando incluyen:

• Continuous QA: Diagnóstico automático de fallos en la integración continua (CI), análisis de logs de errores complejos y propuestas de parches (fixes) mediante PRs.

• Continuous Documentation: Mantenimiento activo de los archivos README y de la documentación técnica para asegurar que siempre reflejen los últimos cambios del código fuente, evitando el clásico problema de documentación obsoleta.

• MultiRepoOps: Flujos que sincronizan estados, características o métricas a través de múltiples repositorios de una misma organización, actuando como un orquestador inteligente.

• Si quieres ver la lista completa de agentes de diseño, GitHub los ha recopilado aquí.

Costes y limitaciones de GitHub Agentic Workflows

Respecto los compromisos técnicos. Ejecutar IA dentro de un pipeline de integración tiene un coste directo en cuanto a costes de facturación y de precisión.

Cuando utilizas GitHub Copilot con la configuración por defecto, cada ejecución de un Agentic Workflow suele incurrir en dos llamadas de tipo premium request: una para procesar la tarea principal del agente y otra independiente para validar la seguridad y los guardrails a través de los safe-outputs. A escala empresarial, si lanzas un flujo agéntico en cada push a cualquier rama, la factura puede escalar rápidamente.

La recomendación oficial de GitHub es comenzar vinculando estos flujos a eventos de baja frecuencia como tareas programadas diarias, creación de releases o a triggers manuales workflow_dispatch antes de automatizarlos completamente por evento.

Otro aspecto vital es el factor humano. La IA es una herramienta de asistencia, no un desarrollador autónomo infalible como ya todos habremos comprobado. Un principio de diseño fundamental de GitHub Agentic Workflows es que los Pull Requests generados por agentes nunca se mergeen automáticamente, siempre debe haber un humano responsable (el famoso Human-in-the-loop) que revise, valide y apruebe los cambios propuestos por la IA. Las alucinaciones en modelos de lenguaje siguen siendo una realidad técnica.

El código fuente en Markdown de estos flujos debe tratarse con el mismo rigor que el código de producción. Debes aplicar code reviews, iterar sobre las instrucciones progresivamente y versionar los cambios con cuidado. A veces, alterar una sola frase en el Markdown puede cambiar drásticamente el comportamiento del agente.

Referencias técnicas

1. Repositorio oficial y documentación de GitHub Agentic Workflows - Especificaciones técnicas, CLI y guía de configuración inicial.

2. Documentación sobre cómo funcionan bajo el capó (How they work) - Explicación profunda de la compilación WASM, aislamiento y dependencias.

3. Artículo de lanzamiento en el Blog de GitHub - Contexto sobre el concepto de Continuous AI y ejemplos de aplicación en la industria.

4. Portal de GitHub Next: Agentic Workflows - Estado de la investigación, filosofía de diseño y modelos soportados.