Creación de flujos de trabajo agente de GitHub

Acerca de cómo crear Flujos de trabajo basados en agentes de GitHub

Puede crear Flujos de trabajo basados en agentes de GitHub con un agente de codificación (recomendado) o manualmente. Un flujo de trabajo es un archivo Markdown en .github/workflows/ que contiene metadatos YAML para la configuración e instrucciones en lenguaje natural para el agente de IA.

Para crear un flujo de trabajo agéntico, define el flujo de trabajo en Markdown, compílalo en un archivo .lock.yml, haz commit de ambos archivos y, a continuación, ejecútalo mediante desencadenadores de GitHub Actions o el GitHub CLI.

Este artículo se centra en las tareas principales: crear, actualizar y reutilizar flujos de trabajo. Para obtener detalles técnicos completos y patrones adicionales, use el Flujos de trabajo basados en agentes de GitHub sitio de documentación.

Prerrequisitos

Antes de comenzar, asegúrese de que tiene:

• Una cuenta de IA: GitHub Copilot, Anthropic Claude, OpenAI Codexo Google Gemini

• Un repositorio GitHub en el que tiene permisos de escritura

• GitHub Actions activado para el repositorio

• GitHub CLI (gh) v2.0.0 o posterior instalado y autenticado

  Para comprobar la versión, ejecute gh --version. Para autenticarse, ejecute:

  gh auth login --scopes repo,workflow
  

• Extensión Flujos de trabajo basados en agentes de GitHub para el GitHub CLI instalado:

  gh extension install github/gh-aw
  

  Si usa GitHub CLI la versión 2.90.0 o posterior, al ejecutar cualquier gh aw comando se le pedirá que instale automáticamente la extensión si aún no está instalada.

Authentication

Puede configurar la autenticación con el motor de IA (agente de codificación) elegido de dos maneras:

• Uso de la instancia integrada GITHUB_TOKEN para la facturación de la organización (recomendado). Esta opción está diseñada específicamente para el motor GitHub Copilot y solo puede usarse en repositorios propiedad de una organización con un plan GitHub Copilot.
• Uso de una personal access token o clave de API para repositorios personales y motores de IA de terceros.

Uso de la instancia integrada GITHUB_TOKEN

Si usa GitHub Copilot en un repositorio que pertenece a una organización, puede usar la función GITHUB_TOKEN integrada de GitHub Actions en lugar de personal access token. Esto factura el uso del flujo de trabajo directamente a su organización y evita la necesidad de administrar un secreto de personal access token para las solicitudes de Copilot. Para configurar:

1. El administrador de la organización debe habilitar la directiva "Permitir el uso de Copilot CLI facturado a la organización", si aún no lo está, en la configuración de Copilot.
2. Para los flujos de trabajo que quiera facturar a una organización, coloque copilot-requests: write en el encabezado permissions del flujo de trabajo.

Habilitación de la facturación de la organización

“Permitir el uso de Copilot CLI cuyo coste se factura a la organización” debe estar habilitado en la configuración de la directiva GitHub Copilot. Si la directiva "Copilot CLI" ya está habilitada, la directiva de facturación está habilitada de forma predeterminada.

1. En la esquina superior derecha de GitHub, haz clic en la foto del perfil y luego en Your organizations.

2. Seleccione una organización haciendo clic en ella.

3. Debajo del nombre de la organización, haz clic en Settings. Si no puedes ver la pestaña "Configuración", selecciona el menú desplegable y, a continuación, haz clic en Configuración.

   

4. En la barra lateral, haga clic en Copilot y, a continuación, haga clic en Directivas.

5. Habilite "Copilot CLI" y, a continuación, habilite "Permitir el uso de Copilot CLI con cargo a la organización".

Facturación de un flujo de trabajo a una organización

Al crear un flujo de trabajo, debe incluir copilot-requests: write debajo de permissions en el frontmatter del flujo de trabajo. Cuando se establece este permiso, el token de GitHub Actions' se usa para las solicitudes de Copilot y se omite COPILOT_GITHUB_TOKEN para esas solicitudes. 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, por lo que debe configurar COPILOT_GITHUB_TOKEN en su lugar.

permissions:
  contents: read
  copilot-requests: write

Uso de una personal access token o clave de API

Para repositorios personales o motores de IA de terceros, debe crear un secreto del repositorio para almacenar un personal access token o una clave de API. Para GitHub Copilot, el secreto es COPILOT_GITHUB_TOKEN, que almacena un personal access token de grano fino.

Si usa gh aw add-wizard, el flujo de instalación le pedirá que cree ese secreto. Si va a crear un flujo de trabajo agéntico desde la interfaz web GitHub o manualmente, primero tendrá que añadir usted mismo el secreto en la sección de secretos GitHub Actions de su repositorio, ya sea en la IU GitHub o con gh aw secrets set en la CLI. Para obtener instrucciones, consulte referencia de autenticación.

Crear un flujo de trabajo

La manera recomendada de crear flujos de trabajo basados en agentes es usar un agente de codificación de la CLI o VS Code. Esto proporciona una ruta de acceso guiada para crear, compilar y confirmar el flujo de trabajo.

Uso de un agente de codificación de la CLI o VS Code

1. Con la extensión GitHub CLIFlujos de trabajo basados en agentes de GitHub (gh aw), inicialice el repositorio para la redacción asistida por agentes (recomendado para la configuración inicial de un repositorio):

   gh aw init
   

   Esto agrega aptitudes, instrucciones y un agente personalizado relacionado con la creación de flujos de trabajo agente, por lo que los agentes de codificación pueden crear y editar flujos de trabajo de forma más eficaz.

2. Inicie el agente de codificación en el contexto del repositorio (por ejemplo, CLI de Copilot o el modo de agente de VS Code).

3. Introduzca una instrucción en la que mencione la habilidad agentic-workflows y describa el flujo de trabajo que desea:

   Copilot prompt

   /agentic-workflows Create a new workflow that creates a daily report on
   recent activity in the repository, delivered as
   an issue.
   

4. El agente creará el flujo de trabajo y compilará el flujo de trabajo mediante GitHub CLI.

5. Revise el flujo de trabajo y pida al agente que confirme e inserte los archivos.

6. Inicie el flujo de trabajo desde la pestaña GitHub Actions, o con la ejecución GitHub CLI:

   gh aw run YOUR-WORKFLOW-NAME
   

Otros métodos de creación

También puede crear flujos de trabajo agente:

• En la GitHub interfaz web. Consulte crear flujos de trabajo en la interfaz web de GitHub.
• Manualmente. Consulte creación de flujos de trabajo mediante la edición manual.

Referencia de la estructura de flujo de trabajo

Cada archivo markdown de flujo de trabajo tiene dos partes:

Section	Purpose
Metadatos de cabecera YAML	Define desencadenadores (on), permisos, salidas seguras y el motor de IA.
Contenido en Markdown	Instrucciones del lenguaje natural que sigue el agente de IA cuando se ejecuta el flujo de trabajo.

Principales campos de metadatos de cabecera:

Campo	Descripción
on	El activador de eventos (la misma sintaxis que los activadores GitHub Actions).
permissions	Permisos de repositorio concedidos al agente. Tiene como valor predeterminado read-all.
safe-outputs	Operaciones de escritura que el agente puede realizar (por ejemplo, create-issue, add-comment, create-pull-request).
engine	El motor de IA que se va a usar (copilot es el valor predeterminado; claude, codexy gemini también se admiten).

Para obtener la referencia completa de frontmatter, consulte la Flujos de trabajo basados en agentes de GitHub documentación de frontmatter.

Ejemplo de flujo de trabajo agente

El siguiente ejemplo es un informe semanal simplificado de actividad de incidencias para un repositorio.

---
on: weekly on monday

permissions:
  issues: read
  copilot-requests: write

network: defaults

tools:
  github:
    toolsets: [issues]

safe-outputs:
  create-issue:

---

# Weekly issue activity report

Review issue activity from the last 7 days in this repository.

Create a GitHub issue that includes:

- Total issues opened and closed this week.
- The top recurring themes from issue titles and descriptions.
- A short list of notable issues that still need attention.
- Two or three actionable recommendations for maintainers.

Keep the report concise and action-oriented.

Actualización de un flujo de trabajo

Para actualizar un flujo de trabajo existente:

1. Editar el archivo Markdown del flujo de trabajo en .github/workflows/.

2. Vuelva a compilar para actualizar el archivo de bloqueo:

   gh aw compile
   

3. Confirme e inserte ambos archivos actualizados.

4. Abra una solicitud de incorporación de cambios y compruebe GitHub Actions las comprobaciones.

Para obtener instrucciones de edición detalladas, consulte Edición de flujos de trabajo.

Reutilización de flujos de trabajo

También puede importar flujos de trabajo desde repositorios externos a los que puede acceder. Por ejemplo, puede agregar un flujo de trabajo desde githubnext/agentics:

gh aw add-wizard githubnext/agentics/daily-repo-status

En una instalación no interactiva, puede utilizar gh aw add y, opcionalmente, fijar una versión.

Al importar un flujo de trabajo, GitHub CLI almacena un valor source: en frontmatter para que puedas actualizarlo más adelante desde el origen con gh aw update.

Importe solo flujos de trabajo de orígenes de confianza y revise lo que hace un flujo de trabajo antes de agregarlo al repositorio. Los flujos de trabajo marcados private: true no se pueden importar en otros repositorios.

Al actualizar un flujo de trabajo importado, GitHub CLI intenta conservar los cambios locales. Si hay conflictos de fusión, resuélvalos y vuelva a ejecutar gh aw compile.

Para más información, consulte Reutilización de flujos de trabajo.

Pasos siguientes

• Para ver ejemplos de flujo de trabajo, patrones avanzados, guías e información de solución de problemas, consulte el sitio deFlujos de trabajo basados en agentes de GitHub documentación.