Sobre os fluxos de trabalho agênticos do GitHub

Automatize tarefas repetitivas do repositório com instruções em linguagem natural executadas por agentes de programação com IA em GitHub Actions.

Neste artigo

Observação

Fluxos de trabalho agênticos do GitHub are in prévia pública and subject to change.

Sobre o fluxos de trabalho baseados em agentes

Fluxos de trabalho agênticos do GitHub são automações de repositório alimentadas por IA que você define no markdown e executa como GitHub Actions fluxos de trabalho. Ao contrário da automação tradicional com regras fixas if-then, fluxos de trabalho baseados em agentes use agentes de codificação para entender o contexto, tomar decisões e tomar ações significativas, tudo a partir de instruções de linguagem natural.

Na prática, em comparação com fluxos de trabalho tradicionais que executam etapas predefinidas:

  • Fluxos de trabalho de agentes execute instruções de linguagem natural com raciocínio contextual.
  • Você ainda define restrições no frontmatter, como gatilhos, permissões e saídas seguras.

Com fluxos de trabalho baseados em agentes, você pode automatizar tarefas como:

  • Triando problemas recebidos e classificando-os por tipo e prioridade
  • Investigando falhas de CI e sugerindo correções
  • Gerando relatórios diários ou semanais sobre a situação do repositório
  • Manter a documentação atualizada com alterações de código
  • Melhorando a cobertura do teste

Benefícios de usar fluxos de trabalho baseados em agentes

  • Automatize o trabalho repetitivo do repositório. Definir triagem de problemas, investigação de CI, atualizações de documentação e relatórios em linguagem natural.
  • Reduza a complexidade do fluxo de trabalho. Escreva instruções de markdown em vez de criar scripts de procedimento complexos para cada cenário.
  • Mantenha a revisão humana envolvida no processo. Fluxos de trabalho de agentes pode gerar saídas prontas para revisão, como problemas, comentários e solicitações de pull, enquanto você controla aprovações e mesclagens.
  • Execute agentes com segurança em camadas. Os agentes são executados em contêineres protegidos por firewall com tokens somente de leitura por padrão. As ações de escrita são limitadas a "saídas seguras" declaradas, que você definiu e que foram verificadas pela detecção agentiva de ameaças.

Requisitos

Para criar e usar fluxos de trabalho baseados em agentes, você precisa:

  • GitHub Actions habilitado para seu repositório.
  • Uma conta com um mecanismo de IA (agente), comoGitHub Copilot, , Anthropic ClaudeOpenAI Codexou Google Gemini.
  • GitHub CLI instalado e autenticado

Como fluxos de trabalho baseados em agentes funcionam

Cada arquivo markdown de fluxo de trabalho tem duas partes:

  • Frontmatter (YAML entre --- marcadores): configura quando o fluxo de trabalho é executado, quais permissões ele tem e quais operações de gravação são permitidas.
  • Corpo em Markdown: Contém instruções em linguagem natural que o agente de IA segue.

Em um alto nível, o processo para criar e usar fluxos de trabalho baseados em agentes é:

  1. Defina o arquivo de fluxo .md de trabalho agente, incluindo instruções de frontmatter e markdown do YAML.
  2. Compile o arquivo de fluxo de trabalho Markdown para um arquivo de fluxo de trabalho reforçado .lock.ymlGitHub Actions.
  3. Confirme e envie os dois arquivos por push para o branch padrão do repositório.
  4. Execute o fluxo de trabalho como qualquer outro GitHub Actions fluxo de trabalho, por um gatilho ou na interface web do seu GitHub repositório. Você também pode executá-lo do GitHub CLI.

Aqui está um exemplo de fluxo de trabalho para criar uma issue de relatório diário de status para um repositório:

---
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 obter etapas detalhadas sobre como criar e atualizar fluxos de trabalho baseados em agentes, consulte Criando fluxos de trabalho agênticos do GitHub.

Agentes de codificação com suporte

Fluxos de trabalho agênticos do GitHub dão suporte a vários agentes de codificação, incluindo:

  • GitHub Copilot (requer um GitHub Copilot plano)
  • Anthropic Claude
  • OpenAI Codex
  • Google Gemini: Um projeto de inteligência artificial do Google.

Você especifica qual agente usar na propriedade enginefrontmatter do fluxo de trabalho. Cada mecanismo requer seu próprio segredo de autenticação configurado em seu repositório. GitHub Copilot será o mecanismo padrão se nenhum for especificado.

Para obter mais informações, consulte a referência do mecanismo.

Barreiras de segurança

Fluxos de trabalho agênticos do GitHub são projetados com segurança como prioridade:

  • Somente leitura por padrão: os fluxos de trabalho têm permissões de repositório somente leitura, a menos que você conceda explicitamente mais.
  • Saídas seguras: operações de gravação (como criar problemas, adicionar comentários ou abrir solicitações de pull) só são permitidas por meio de operações de gravação declaradas safe-outputs no frontmatter.
  • Os segredos permanecem fora do ambiente de execução do agente: credenciais confidenciais são mantidas em tarefas downstream isoladas, em vez de serem expostas diretamente ao agente.
  • Detecção de ameaças: as saídas propostas são verificadas quanto a alterações suspeitas ou não seguras antes que as ações de gravação sejam aplicadas.
  • Execução com firewall: agentes são executados em ambientes isolados GitHub Actions .
  • Acesso baseado em função: você pode restringir quem pode disparar ou modificar fluxos de trabalho baseados em agentes usando controles de acesso baseados em função.

Para obter um passo a passo completo da arquitetura, consulte a documentação de segurança.

Uso e cobrança

O custo total de fluxos de trabalho baseados em agentes tem duas partes:

  • GitHub Actions minutos consumidos por trabalhos de fluxo de trabalho.
  • Custos de inferência do mecanismo de IA configurado.

Para inferência, Fluxos de trabalho agênticos do GitHub use Créditos de IA (AIC) como métrica geral para monitorar e controlar o orçamento em diferentes mecanismos. 1 AIC = $0.01 USD.

A forma como a cobrança se aplica depende do mecanismo:

  • Mecanismo padrão GitHub Copilot: o uso de AIC é mapeado para AI credits no faturamento de GitHub Copilot.
  • Mecanismo de terceiros: a inferência é cobrada por esse provedor.

Você pode usar o GitHub CLI para revisar o uso e o custo estimado de fluxos de trabalho baseados em agentes. Use gh aw logs para visualizar execuções recentes de fluxos de trabalho, incluindo duração, uso de tokens e estimativas de AIC em diferentes execuções. Use gh aw audit RUN-ID para inspecionar uma única execução com mais detalhes, incluindo o uso de token e o custo estimado de inferência. Os valores AIC são estimativas de melhor esforço e podem não corresponder exatamente às faturas do provedor, portanto, verifique os encargos finais no painel de cobrança do provedor.

Você também pode definir max-ai-credits no frontmatter do fluxo de trabalho para restringir o uso de inferência a uma única execução. O limite padrão é 1.000 AIC por execução.

Para uma visão geral da cobrança do Fluxos de trabalho agênticos do GitHub e orientações sobre otimização de custos, consulte Gerenciamento de custos no site de documentação do Fluxos de trabalho agênticos do GitHub.

Ativar a cobrança da organização para Fluxos de trabalho agênticos do GitHub

Para GitHub Copilot fluxos de trabalho agênticos em repositórios pertencentes à organização, se a organização tiver o plano GitHub Copilot, recomendamos enfaticamente usar o GITHUB_TOKEN integrado do GitHub Actions. Essa abordagem cobra da organização e evita o uso de uma personal access token.

Para cobrar da organização, você precisa:

  1. Um administrador da organização para habilitar as opções "Copilot CLI" e "Permitir o uso do Copilot CLI cobrado da organização" nas configurações de política de GitHub Copilot. Se "Copilot CLI" já estiver habilitada, a política de cobrança será habilitada por padrão.
  2. No frontmatter de cada fluxo de trabalho, inclua copilot-requests: write sob o objeto permissions.

Quando copilot-requests: write é definido nas permissões de frontmatter do fluxo de trabalho, o token 'GitHub Actions' é usado para solicitações do Copilot, portanto você não precisa de um COPILOT_GITHUB_TOKEN. 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.

Para obter instruções detalhadas de configuração, consulte Como usar o integrado GITHUB_TOKEN.

Próximas Etapas