gh-aw workflows agénticos: agentes de IA en GitHub Actions

gh-aw workflows agénticos: agentes de IA en GitHub Actions con permisos de solo lectura, topes de coste y logs de ejecución que puedes vigilar.
gh-aw workflows agentiques : agents IA dans GitHub Actions

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 compile valida 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).
Ejemplo de la documentación de gh-aw: una incidencia Daily Repo Report creada por el bot github-actions, con los puntos destacados del repositorio en 30 días
Source : github.github.com

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: defaults solo permite la infraestructura básica. Se añaden dominios o ecosistemas (node, python) en network.allowed; network: {} bloquea todo.
  • Disparadores: la guía de inicio avisa de preferir pull_request a pull_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.

Ejemplo de la galería de gh-aw: incidencia abierta por un workflow CI Failure Doctor, con resumen, detalles del fallo (run, commit, disparador push) y análisis de causa raíz de una prueba en Go
Source : github.github.com

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-credits y max-daily-ai-credits en 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.
Extractos de la documentación Cost Management de gh-aw: frontmatter con skip-if-match, max-ai-credits y observability.otlp, y luego los comandos gh aw logs, gh aw audit y gh aw health
Source : github.github.com

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-request o 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 schedule o workflow_dispatch y 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.yml generado en la revisión de código, como cualquier workflow de Actions.
  • Reduce network.allowed a lo estrictamente necesario y vigila las líneas DENIED.
  • Extrae cada semana gh aw logs --json: duración, tokens y AIC por workflow, y compara dos runs con gh 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.

Total
0
Shares
Leave a Reply

Your email address will not be published. Required fields are marked *

Previous Post
Skill Recorder skill agent : relire et auditer un skill

Skill Recorder skill agente: revisar y auditar un skill

Next Post
CLAUDE.md Karpathy : mesurer l'effet sur un agent de code

CLAUDE.md Karpathy: cómo medir su efecto en un agente de código

Related Posts