gh-aw workflows agénticos: el repositorio github/gh-aw (GitHub Agentic Workflows) permite escribir una automatización en lenguaje natural, en un archivo Markdown, y hacer que un agente de IA la ejecute dentro de GitHub Actions. Tiene unas 5500 estrellas y 604 forks a finales de octubre de 2026, con licencia MIT («Copyright GitHub, Inc.» en el archivo LICENSE).
Para un SRE, el interés se resume en tres preguntas. ¿Qué puede hacer el agente en la CI? ¿Cuánto cuesta cada ejecución? ¿Cómo se observa lo ocurrido? Este artículo responde según el README y la documentación oficial, leídos el 27 de octubre de 2026. No es una prueba: span.observer no ha instalado la herramienta, y las imágenes vienen de la documentación del proyecto o reproducen sus ejemplos de configuración.
Un aviso más: la documentación indica que GitHub Agentic Workflows está en «Public Preview». Los detalles pueden cambiar rápido y varias funciones figuran como experimentales.
gh-aw workflows agénticos: qué dice el repositorio
- Principio: un workflow agéntico tiene dos partes. El frontmatter YAML fija los disparadores, los permisos, las herramientas y el motor de IA; el cuerpo Markdown describe la tarea. El comando
gh aw compilevalida el archivo y genera un.lock.yml, un workflow estándar de GitHub Actions. - Motores de IA integrados: GitHub Copilot (por defecto), Claude Code, OpenAI Codex, Google Gemini y Pi.
- Lugar en la CI: el README dice que la herramienta complementa la CI/CD y no la sustituye. Las compilaciones, pruebas y despliegues siguen siendo workflows deterministas. El agente se ocupa de lo que exige interpretación: triaje de incidencias, revisión de pull requests, análisis de fallos de CI, informes.
- Editor y licencia: repositorio de la organización GitHub, licencia MIT. span.observer es un blog independiente y no tiene vínculo con GitHub ni con Microsoft.
- Cifras: unas 5500 estrellas y 604 forks, leídos en la página del repositorio el 27 de octubre de 2026. El README menciona herramientas de Go (
go test,go build).

Esta imagen, tomada de la guía de inicio, muestra el resultado típico: el agente no escribe en el repositorio, produce una incidencia o un comentario.
Instalación paso a paso
La guía de inicio anuncia unos diez minutos. Los requisitos que cita: una cuenta con un proveedor de IA (Copilot, Anthropic, OpenAI o Google), un repositorio donde tengas acceso de escritura, GitHub Actions activado, la CLI gh en versión 2.0.0 o superior, y Linux, macOS o Windows con WSL.
Paso 1: instalar la extensión
gh auth login --scopes repo,workflow
gh extension install github/gh-aw
La documentación ofrece también un script install-gh-aw.sh si falla la autenticación. Como con cualquier curl | bash, léelo antes de ejecutarlo.
Paso 2: añadir un workflow de ejemplo
gh aw add-wizard githubnext/agentics/repo-status
El asistente comprueba los permisos del repositorio, propone un motor, configura la autenticación y añade el archivo .md y su .lock.yml en .github/workflows/. Antes de activarlo, la documentación pide revisar el tratamiento de datos del motor elegido, la sensibilidad del repositorio y el acceso a logs y artefactos.
Paso 3: autenticar el motor
Cada motor tiene su secreto: COPILOT_GITHUB_TOKEN (o copilot-requests: write con facturación de organización), ANTHROPIC_API_KEY, CODEX_API_KEY u OPENAI_API_KEY, GEMINI_API_KEY. Ejemplo de la documentación: gh secret set ANTHROPIC_API_KEY < /ruta/clave.txt. Un token de suscripción de Claude (CLAUDE_CODE_OAUTH_TOKEN) no es compatible.
Paso 4: compilar, ejecutar, seguir
gh aw compile
gh aw run repo-status
gh aw status
gh run watch
Confirma los dos archivos: la documentación dice que el .lock.yml generado es obligatorio y debe subirse junto con el Markdown. Una ejecución dura de dos a tres minutos según la guía.
Agentes en la CI: permisos y barreras de seguridad
Es el núcleo del diseño. Según el README, la ruta compatible arranca en solo lectura y en un entorno aislado (sandbox). Las escrituras pasan por «safe outputs»: el agente solicita una acción en forma estructurada y un job aparte, con permisos limitados, la aplica tras validarla.
- Solo lectura: el job del agente no tiene derechos de escritura y, según la FAQ, no recibe los secretos del repositorio por defecto. Un autor puede pasarlos de forma explícita a herramientas, pasos o jobs personalizados: hay que revisarlo.
- Safe outputs: crear una incidencia, un comentario, una pull request o añadir una etiqueta, con un máximo por ejecución (por ejemplo una incidencia). El contenido se sanea antes de aplicarse (secretos ocultos, filtrado de dominios de URL, límites de tamaño).
- Detección de amenazas: cuando hay safe outputs configurados, un job de análisis se ejecuta entre el agente y las escrituras. Busca inyección de prompt, fugas de secretos y parches maliciosos.
- Red: por defecto,
network: defaultssolo permite la infraestructura básica. Se añaden dominios o ecosistemas (node,python) ennetwork.allowed;network: {}bloquea todo. - Disparadores: la guía de inicio avisa de preferir
pull_requestapull_request_target, que se ejecuta en el contexto privilegiado del repositorio base.
El README lo dice sin rodeos: estos controles son configurables y usar workflows agénticos exige una revisión de seguridad y una supervisión humana atentas, bajo tu propio riesgo. Para el método en la empresa, consulta las barreras de seguridad de los agentes de IA en producción y supervisar un agente de código en la empresa.

El ejemplo anterior viene de la galería «CI Failure Investigation»: un workflow agéntico que lee un run fallido y abre una incidencia con una pista de la causa. Es el caso de uso más cercano al trabajo de un SRE.
Costes: créditos, duraciones y disparadores
La documentación «Cost Management» divide el coste en dos: los minutos de GitHub Actions de los jobs y la inferencia que factura el proveedor de IA. Da un orden de magnitud: un job de preactivación de 10 a 30 segundos y luego un job de agente de 1 a 15 minutos, cada uno con cerca de 1,5 minutos de preparación del runner.
La unidad de seguimiento es el AI Credit (AIC): un AIC equivale a 0,01 USD. Los valores se calculan en la medida de lo posible a partir del catálogo de precios models.dev y pueden diferir de la factura real: la documentación pide comprobarlo con el proveedor.
Los valores por defecto que cita la documentación:
- 20 minutos de límite para el paso del agente, 60 minutos para el job del agente y 10 minutos para el job de detección;
- 1000 AIC por ejecución de workflow y 5000 AIC por workflow y día (ventana de 24 horas);
- ajustables con
timeout-minutes,max-ai-creditsymax-daily-ai-creditsen el frontmatter.
La palanca principal sigue siendo la frecuencia. La documentación clasifica push, check_run y check_suite como riesgo alto: en un repositorio activo pueden lanzar cientos de ejecuciones al día. Aconseja empezar con schedule o workflow_dispatch y evitar lanzar el agente cuando no hace falta, con skip-if-match o un noop escrito en $GH_AW_SAFE_OUTPUTS. Para el seguimiento de tokens en telemetría, consulta el coste de un agente de IA en tokens con OpenTelemetry.
Observar las ejecuciones: logs, duraciones, fallos
Cada ejecución es primero un run de GitHub Actions: la pestaña Actions muestra los logs por paso, y la duración por job indica el gasto en minutos. gh-aw añade comandos propios, descritos en la documentación:
gh aw logs: tabla de runs (10 por defecto) con duración, tokens, AIC y número de turnos; opciones--engine,--start-date -30d,--count,--firewall,--json. Los fallos, tiempos agotados y cancelaciones se agrupan en «clusters» de síntomas; la documentación aclara que no son causas demostradas ni tasas de fallo.gh aw audit <run-id-o-url>: informe de un run (métricas, llamadas a herramientas, estado de los servidores MCP, análisis del cortafuegos, safe outputs). Con dos identificadores, compara el segundo con el primero. Una URL de job sin ancla extrae el primer paso fallido.gh aw health: estado de los workflows de un repositorio en 7, 30 o 90 días, sobre una muestra de la revisión actual.gh aw status: estado de los workflows.

Para una vista de varios repositorios, la documentación propone observability.otlp: los runs envían spans OTLP a un colector, con atributos como gen_ai.usage.input_tokens y gen_ai.usage.output_tokens. Las trazas también se copian en el archivo otel.jsonl del artefacto del agente, y un fallo de exportación no hace fallar el workflow. Los secretos de las cabeceras se ocultan antes de exportar, pero la documentación avisa de que el enmascarado de la consola de Actions no sanea el contenido de los artefactos descargables. Para las trazas de agentes en general, consulta observar agentes MCP con OpenTelemetry.
Un bloqueo de red aparece en los logs como DENIED CONNECT registry.npmjs.org:443: la documentación recomienda comprobar que el destino es legítimo y añadir solo el dominio o el ecosistema necesario.
Límites y puntos abiertos
- Respaldo que señalar: «Public Preview» según la FAQ oficial. Varias funciones documentadas están marcadas como experimentales (por ejemplo
merge-pull-requesto las integraciones con Azure DevOps y Linear). - Vulnerabilidad anunciada: el README señala un fallo que afecta a las versiones
>= 0.83.3, < 0.85.4(aviso GHSA-8h78-hpm7-29gg); esas versiones se retiraron por precaución. Comprueba la versión que instalas. - Versiones: la documentación describe un ritmo de versiones menores semanal o quincenal y una comprobación en ejecución: un workflow compilado con una versión demasiado antigua o revocada puede fallar o avisar, y entonces hay que recompilar. No se pudo leer el número de la última release, por eso no se cita.
- No determinismo: el agente interpreta. Los resultados pueden variar entre ejecuciones; la CI determinista conserva las pruebas y los despliegues.
- Costes aproximados: el AIC es una estimación, no la factura del proveedor.
- Datos: el contenido del repositorio llega al proveedor del motor elegido; lee sus condiciones.
Para comparar con otros proyectos de agentes, consulta OpenBot, un espacio de trabajo de escritorio para agentes, y el servidor MCP de GitHub.
Buenas prácticas
- Empieza con un disparador
scheduleoworkflow_dispatchy un modelo ligero para medir el coste real. - Mantén los valores por defecto de solo lectura, añade los safe outputs uno a uno y ponles tope.
- Revisa el
.lock.ymlgenerado en la revisión de código, como cualquier workflow de Actions. - Reduce
network.alloweda lo estrictamente necesario y vigila las líneasDENIED. - Extrae cada semana
gh aw logs --json: duración, tokens y AIC por workflow, y compara dos runs congh aw audit. - Envía la telemetría a un colector central cuando haya varios repositorios.
Preguntas frecuentes
¿gh-aw sustituye a la CI existente?
No. El README dice que complementa la CI/CD. Las compilaciones, pruebas, análisis estático y despliegues siguen siendo workflows deterministas de Actions; el agente trata lo que exige interpretación.
¿Puede el agente modificar mi repositorio o leer mis secretos?
No por defecto: el job del agente arranca en solo lectura y sin los secretos del repositorio. Las escrituras pasan por safe outputs aplicados en jobs aparte. Un autor puede, sin embargo, conceder derechos directos o pasar secretos: revisa el .lock.yml.
¿Cómo limito y sigo el coste?
Pon tope con max-ai-credits y max-daily-ai-credits, evita los disparadores frecuentes y sigue duración, tokens y AIC con gh aw logs. La documentación recuerda que estas cifras son estimaciones que hay que comparar con la factura del proveedor.
Conclusión
gh-aw convierte un archivo Markdown en un workflow de GitHub Actions donde un agente trabaja con derechos reducidos. El proyecto es reciente y está en vista previa pública, y su documentación aporta topes, comandos de auditoría y una exportación OpenTelemetry que facilitan la operación. Pruébalo primero en un repositorio sin secretos, con un disparador programado. Fuentes: repositorio github/gh-aw y documentación oficial.
span.observer es un blog independiente de la comunidad, no afiliado a Dynatrace LLC, a GitHub ni a Microsoft. Las marcas citadas pertenecen a sus propietarios. Las herramientas cambian rápido: comprueba siempre los comandos y las opciones en su documentación oficial.