Criando fluxos de trabalho agênticos do GitHub

Sobre a criação de Fluxos de trabalho agênticos do GitHub

Você pode criar Fluxos de trabalho agênticos do GitHub com um agente de codificação (recomendado) ou manualmente. Um fluxo de trabalho é um arquivo markdown em .github/workflows/ que contém front matter em YAML para configuração e instruções em linguagem natural para o agente de IA.

Para criar um fluxo de trabalho agêntico, defina o fluxo de trabalho em Markdown, compile-o em um arquivo .lock.yml, faça commit de ambos os arquivos e execute-o por meio de gatilhos GitHub Actions ou do GitHub CLI.

Este artigo se concentra nas tarefas principais: criar, atualizar e reutilização de fluxos de trabalho. Para obter detalhes técnicos completos e padrões adicionais, consulte o Fluxos de trabalho agênticos do GitHub site de documentação.

Pré-requisitos

Antes de começar, verifique se você tem:

• Uma conta de IA: GitHub Copilot, , Anthropic ClaudeOpenAI Codexou Google Gemini

• Um GitHub repositório no qual você tem permissão de gravação

• GitHub Actions habilitado para o repositório

• GitHub CLI (gh) v2.0.0 ou posterior instalado e autenticado

  Para verificar sua versão, execute gh --version. Para autenticar, execute:

  gh auth login --scopes repo,workflow
  

• A extensão Fluxos de trabalho agênticos do GitHub para o GitHub CLI está instalada:

  gh extension install github/gh-aw
  

  Se você estiver usando GitHub CLI a versão 2.90.0 ou posterior, executar qualquer gh aw comando solicitará que você instale a extensão automaticamente se ela ainda não estiver instalada.

Authentication

Você pode configurar a autenticação com o mecanismo de IA escolhido (agente de codificação) de duas maneiras:

• Usando o recurso integrado GITHUB_TOKEN para o faturamento da organização (recomendado). Essa opção é especificamente para o GitHub Copilot mecanismo e só pode ser usada por repositórios pertencentes a uma organização com um GitHub Copilot plano.
• Uso de personal access token ou chave de API para repositórios pessoais e mecanismos de IA de terceiros.

Usando o recurso integrado GITHUB_TOKEN

Se você estiver usando GitHub Copilot em um repositório pertencente à organização, poderá usar o GITHUB_TOKEN interno do GitHub Actions em vez de um personal access token. Isso cobra diretamente da sua organização pelo uso do fluxo de trabalho e evita a necessidade de gerenciar um segredo personal access token para solicitações do Copilot. Para fazer essa configuração:

1. O administrador da sua organização deve habilitar a política "Permitir o uso do Copilot CLI cobrado da organização", caso ela ainda não esteja habilitada, nas configurações do Copilot.
2. Para fluxos de trabalho que você deseja cobrar de uma organização, coloque copilot-requests: write no frontmatter do fluxo de trabalho permissions.

Habilitando a cobrança da organização

"Permitir o uso do Copilot CLI cobrado da organização" deve estar habilitada nas configurações de política de GitHub Copilot. Se a política "Copilot CLI" já estiver habilitada, a política de cobrança será habilitada por padrão.

1. No canto superior direito de GitHub, clique na foto de perfil e clique em Your organizations.

2. Selecione uma organização clicando nela.

3. No nome da organização, clique em Settings. Caso não consiga ver a guia "Configurações", selecione o menu suspenso , clique em Configurações.

   

4. Na barra lateral, clique Copilot e clique em Políticas.

5. Habilite "Copilot CLI" e, em seguida, habilite "Permitir o uso do Copilot CLI cobrado da organização".

Faturamento de um fluxo de trabalho para uma organização

Ao criar um fluxo de trabalho, você deve incluir copilot-requests: write sob permissions no frontmatter do fluxo de trabalho. Quando essa permissão é definida, o token GitHub Actions' é usado para solicitações de Copilot e COPILOT_GITHUB_TOKEN é ignorado para essas solicitações. Se o token GitHub Actions não tiver acesso GitHub Copilot da organização, o fluxo de trabalho falhará ao enviar solicitações Copilot e você deverá configurar COPILOT_GITHUB_TOKEN em vez disso.

permissions:
  contents: read
  copilot-requests: write

Usando uma chave personal access token ou uma chave de API

Para repositórios pessoais ou motores de IA de terceiros, você precisa criar um segredo de repositório que armazene um personal access token ou uma chave de API. Para GitHub Copilot, o segredo é COPILOT_GITHUB_TOKEN, que armazena um(a) personal access token detalhado(a).

Se você usar gh aw add-wizard, o fluxo de configuração solicitará que você crie esse segredo. Se você estiver criando um fluxo de trabalho agêntico pela interface web do GitHub ou manualmente, primeiro precisará adicionar você mesmo o segredo nos segredos GitHub Actions do seu repositório, seja na interface GitHub ou com gh aw secrets set na CLI. Para obter instruções, consulte a referência de autenticação.

Criação de um fluxo de trabalho

A maneira recomendada de criar fluxos de trabalho baseados em agentes é usar um agente de codificação da CLI ou VS Code. Isso fornece um caminho guiado para criar, compilar e confirmar o fluxo de trabalho.

Usando um agente de código de CLI ou o VS Code

1. Usando a extensão GitHub CLIFluxos de trabalho agênticos do GitHub (gh aw), inicialize o repositório para autoria agentiva (recomendado para configuração inicial em um repositório):

   gh aw init
   

   Isso adiciona habilidades, instruções e um agente personalizado relacionados à criação de fluxo de trabalho agente, para que os agentes de codificação possam criar e editar fluxos de trabalho com mais eficiência.

2. Inicie seu agente de codificação no contexto do repositório (por exemplo, CLI do Copilot ou modo de agente do VS Code).

3. Insira um prompt mencionando a agentic-workflows habilidade e descrevendo o fluxo de trabalho desejado:

   Copilot prompt

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

4. O agente criará o fluxo de trabalho e compilará o fluxo de trabalho usando o GitHub CLI.

5. Examine o fluxo de trabalho e peça ao agente para confirmar e efetuar push dos arquivos.

6. Acione o fluxo de trabalho na guia GitHub Actions, ou com GitHub CLI run:

   gh aw run YOUR-WORKFLOW-NAME
   

Outros métodos de criação

Você também pode criar fluxos de trabalho agente:

• Na interface web GitHub. Consulte criando fluxos de trabalho na interface da Web GitHub.
• Manualmente. Consulte a criação de fluxos de trabalho por edição manual.

Referência da estrutura de fluxo de trabalho

Cada arquivo markdown de fluxo de trabalho tem duas partes:

Seção	Purpose
Frontmatter YAML	Define gatilhos (on), permissões, saídas seguras e o mecanismo de IA.
Conteúdo em Markdown	Instruções de linguagem natural que o agente de IA segue quando o fluxo de trabalho é executado.

Principais campos dos metadados iniciais:

Campo	Description
on	O gatilho de evento (mesma sintaxe dos gatilhos GitHub Actions).
permissions	Permissões de repositório concedidas ao agente. Usa read-all como padrão.
safe-outputs	Operações de escrita que o agente tem permissão para executar (por exemplo, create-issue, add-comment, create-pull-request).
engine	O mecanismo de IA a ser usado (copilot é o padrão; claude, codexe gemini também tem suporte).

Para obter a referência completa do frontmatter, consulte a Fluxos de trabalho agênticos do GitHubdocumentação sobre frontmatter.

Exemplo de fluxo de trabalho agente

O exemplo a seguir é um relatório semanal simplificado da atividade de issues de um repositório.

---
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.

Atualizando um fluxo de trabalho

Para atualizar um fluxo de trabalho existente:

1. Edite o arquivo Markdown do fluxo de trabalho em .github/workflows/.

2. Recompile para atualizar o arquivo de bloqueio:

   gh aw compile
   

3. Confirme e envie por push os dois arquivos atualizados.

4. Abra um pull request e verifique as checagens GitHub Actions.

Para obter diretrizes de edição detalhadas, consulte Editando fluxos de trabalho.

Reutilizando fluxos de trabalho

Você também pode importar fluxos de trabalho de repositórios externos que podem ser acessados. Por exemplo, você pode adicionar um fluxo de trabalho de githubnext/agentics:

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

Para configuração não interativa, você pode usar gh aw add e opcionalmente fixar uma versão.

Quando você importa um fluxo de trabalho, GitHub CLI armazena um valor source: na seção frontmatter para que você possa atualizar a partir do upstream posteriormente com gh aw update.

Importe apenas fluxos de trabalho de fontes confiáveis e examine o que um fluxo de trabalho faz antes de adicioná-lo ao repositório. Fluxos de trabalho marcados private: true não podem ser importados para outros repositórios.

Quando você atualiza um fluxo de trabalho importado, GitHub CLI tenta preservar as alterações locais. Se houver conflitos de mesclagem, resolva-os e execute gh aw compile novamente.

Para obter mais informações, consulte Reutilizando fluxos de trabalho.

Próximas Etapas 

• Para obter exemplos de fluxo de trabalho, padrões avançados, guias e informações de solução de problemas, consulte o site de Fluxos de trabalho agênticos do GitHub documentação.