Acerca de los flujos de trabajo agente de GitHub

Automatice el trabajo repetitivo del repositorio con instrucciones de lenguaje natural ejecutadas por agentes de codificación de IA en GitHub Actions.

En este artículo

Nota:

Flujos de trabajo basados en agentes de GitHub are in versión preliminar pública and subject to change.

Acerca de flujos de trabajo basados en agentes

Flujos de trabajo basados en agentes de GitHub son automatizaciones de repositorios con tecnología de inteligencia artificial que se definen en Markdown y se ejecutan como GitHub Actions flujos de trabajo. A diferencia de la automatización tradicional con reglas if-then fijas, flujos de trabajo basados en agentes use agentes de codificación para comprender el contexto, tomar decisiones y tomar acciones significativas, todo ello desde instrucciones de lenguaje natural.

En la práctica, en comparación con los flujos de trabajo tradicionales que ejecutan pasos predefinidos:

  • Flujos de trabajo de agentes ejecute instrucciones de lenguaje natural con razonamiento contextual.
  • Aún defines salvaguardas en el frontmatter, como desencadenadores, permisos y salidas seguras.

Con flujos de trabajo basados en agentes, puede automatizar tareas como:

  • Evaluar los problemas entrantes y etiquetarlos por tipo y prioridad
  • Investigación de errores de CI y sugerencias de correcciones
  • Generación de informes de estado de repositorio diario o semanal
  • Mantener la documentación actualizada con los cambios de código
  • Mejora de la cobertura de pruebas

Ventajas de usar flujos de trabajo basados en agentes

  • Automatizar el trabajo de repositorio repetitivo. Defina la evaluación de prioridades de problemas, la investigación de CI, las actualizaciones de documentación y los informes en lenguaje natural.
  • Reduzca la complejidad del flujo de trabajo. Escriba instrucciones de Markdown en lugar de crear scripts de procedimientos complejos para cada escenario.
  • Mantener la supervisión humana en el proceso. Flujos de trabajo de agentes puede generar resultados listos para revisar, como incidencias, comentarios y solicitudes de extracción, mientras tú controlas las aprobaciones y las fusiones.
  • Ejecute agentes con seguridad por capas. Los agentes se ejecutan en contenedores protegidos por cortafuegos con tokens de acceso de solo lectura de forma predeterminada. Las acciones de escritura se limitan a las "salidas seguras" declaradas que haya definido y que hayan sido verificadas por un sistema de detección de amenazas agénticas.

Requisitos

Para crear y usar flujos de trabajo basados en agentes, necesita:

  • GitHub Actions habilitado para tu repositorio.
  • Una cuenta con un motor de IA (agente), como GitHub Copilot, Anthropic Claude, OpenAI Codexo Google Gemini.
  • GitHub CLI instalado y autenticado

Cómo flujos de trabajo basados en agentes funciona

Cada archivo markdown de flujo de trabajo tiene dos partes:

  • Frontmatter (YAML entre --- marcadores): configura cuándo se ejecuta el flujo de trabajo, qué permisos tiene y qué operaciones de escritura se permiten.
  • Cuerpo de Markdown: contiene las instrucciones del lenguaje natural que sigue el agente de IA.

En un nivel alto, el proceso para crear y usar flujos de trabajo basados en agentes es:

  1. Defina el archivo de flujo de trabajo .md agente, incluidas las instrucciones de frontmatter y markdown de YAML.
  2. Compila el archivo de flujo de trabajo de Markdown en un archivo de flujo de trabajo protegido .lock.ymlGitHub Actions.
  3. Confirme e inserte ambos archivos en la rama predeterminada del repositorio.
  4. Ejecute el flujo de trabajo como cualquier otro GitHub Actions flujo de trabajo, en un desencadenador o en la GitHub interfaz web del repositorio. También puede ejecutarlo desde el GitHub CLI.

Este es un ejemplo de un flujo de trabajo para crear un problema de informe de estado diario para un repositorio:

---
on: daily

permissions:
  contents: read
  issues: read
  pull-requests: read
  copilot-requests: write

network: defaults

tools:
  github:
    toolsets: [default]

safe-outputs:
  create-issue:

---

# Daily Repo Status Report

Review recent activity in the repository, including issues, pull requests, discussions, and code changes.

Create a GitHub issue summarizing what changed in the last 24 hours (merged pull requests, closed issues, and new discussions), any blockers or open questions mentioned in comments, progress toward visible goals, and recommended next steps for maintainers.

Keep the summary concise. Adjust the level of detail based on how much activity occurred.

Para obtener pasos detallados sobre cómo crear y actualizar flujos de trabajo basados en agentes, consulte Creación de flujos de trabajo agente de GitHub.

Agentes de codificación admitidos

Flujos de trabajo basados en agentes de GitHub admite varios agentes de codificación, entre los que se incluyen:

  • GitHub Copilot (requiere un GitHub Copilot plan)
  • Anthropic Claude
  • OpenAI Codex
  • Google Gemini

Se especifica qué agente usar en la propiedad enginefrontmatter del flujo de trabajo. Cada motor requiere su propio secreto de autenticación configurado en el repositorio. GitHub Copilot es el motor predeterminado si no se especifica ninguno.

Para obtener más información, consulte la referencia del motor.

Barreras de protección de seguridad

Flujos de trabajo basados en agentes de GitHub están diseñados con seguridad como prioridad:

  • Solo lectura de forma predeterminada: los flujos de trabajo tienen permisos de repositorio de solo lectura a menos que conceda explícitamente más.
  • Salidas seguras: las operaciones de escritura (como la creación de problemas, la adición de comentarios o la apertura de solicitudes de incorporación de cambios) solo se permiten mediante la validación declarada safe-outputs en la instancia de frontmatter.
  • Los secretos permanecen fuera del entorno de ejecución del agente: las credenciales confidenciales se conservan en procesos posteriores aislados en lugar de exponerse directamente al agente.
  • Detección de amenazas: las salidas propuestas se examinan en busca de cambios sospechosos o inseguros antes de aplicar las operaciones de escritura.
  • Ejecución con firewall: los agentes se ejecutan en entornos aislados GitHub Actions .
  • Acceso basado en roles: Puede restringir quién puede activar o modificar flujos de trabajo basados en agentes mediante controles de acceso basados en roles.

Para ver un tutorial completo de arquitectura, consulte la documentación de seguridad.

Uso y facturación

El costo total de flujos de trabajo basados en agentes tiene dos partes:

  • GitHub Actions minutos consumidos en tareas del flujo de trabajo.
  • Costos de inferencia del motor de IA configurado.

Para la inferencia, Flujos de trabajo basados en agentes de GitHub utilice AI Credits (AIC) como métrica general para hacer seguimiento y presupuestar en todos los motores. 1 AIC = $0.01 USD.

La forma en que se aplica la facturación depende del motor:

  • Motor predeterminado GitHub Copilot : el uso de AIC se asigna a AI credits en GitHub Copilot la facturación.
  • Motor de terceros: la facturación de la inferencia corre a cargo de ese proveedor.

Puede usar GitHub CLI para revisar el uso y el coste estimado de flujos de trabajo basados en agentes. Use gh aw logs para ver las ejecuciones de flujo de trabajo recientes, incluida la duración, el uso de tokens y las estimaciones de AIC entre ejecuciones. Use gh aw audit RUN-ID para inspeccionar una sola ejecución con más detalle, incluido el uso de tokens y el costo estimado de inferencia. Los valores de AIC son estimaciones de mejor esfuerzo y es posible que no coincidan exactamente con las facturas del proveedor, por lo que debe comprobar los cargos finales en el panel de facturación del proveedor.

También puede establecer max-ai-credits en el frontmatter del flujo de trabajo para limitar el uso de la inferencia en una sola ejecución. El límite predeterminado es 1000 AIC por ejecución.

Para obtener información general sobre la facturación y la guía de optimización Flujos de trabajo basados en agentes de GitHub de costos, consulte Administración de costos en el Flujos de trabajo basados en agentes de GitHub sitio de documentación.

Activar la facturación de la organización para Flujos de trabajo basados en agentes de GitHub

En GitHub Copilot el caso de los flujos de trabajo agente en repositorios propiedad de la organización, si la organización tiene un GitHub Copilot plan, se recomienda encarecidamente usar GitHub Actions" integrado GITHUB_TOKEN. Este enfoque factura a la organización y evita usar un personal access token.

Para facturar a la organización, necesita:

  1. Un administrador de la organización debe habilitar "Copilot CLI" y "Permitir el uso de Copilot CLI facturado a la organización" en la configuración de directiva de GitHub Copilot. Si "Copilot CLI" ya está habilitado, la directiva de facturación está habilitada de forma predeterminada.
  2. En el frontmatter de cada flujo de trabajo, incluya copilot-requests: write dentro del objeto permissions.

Cuando copilot-requests: write se establece en los permisos del frontmatter del flujo de trabajo, se utiliza el token de GitHub Actions en las solicitudes de Copilot, por lo que no necesitas un COPILOT_GITHUB_TOKEN. Si el token GitHub Actions no tiene acceso a GitHub Copilot desde la organización, el flujo de trabajo falla al enviar solicitudes a Copilot, y debe configurar COPILOT_GITHUB_TOKEN en su lugar.

Para obtener instrucciones detalladas sobre la configuración, consulte el componente integrado GITHUB_TOKEN.

Pasos siguientes