Automating GitHub Workflow with Actions

1. A Anatomia de um Commit Automatizado

Antes de criar um Pull Request, precisamos entender como o Git representa as alterações. Um Pull Request é simplesmente um pedido para mesclar uma branch em outra. Portanto, nosso primeiro trabalho é criar essa branch com nossos commits.

Fazer um commit via API não é um único comando. Envolve a recriação dos objetos fundamentais do Git:

1. Blobs: O conteúdo de cada arquivo alterado é salvo como um objeto "blob".
2. Tree: A estrutura de diretórios do repositório é representada por um objeto "tree", que aponta para os blobs (arquivos) e outras árvores (subdiretórios). Para o nosso commit, criamos uma nova árvore que reflete o estado do repositório após nossas alterações.
3. Commit: Um objeto "commit" é criado, apontando para a nova árvore e para o commit "pai" (o último commit da branch base). Ele também contém a mensagem do commit, o autor, etc.
4. Reference: Finalmente, uma "referência" (como refs/heads/feature/PROJ-123) é criada ou atualizada para apontar para o nosso novo objeto de commit. Este passo é o que efetivamente "cria" ou "empurra" a branch.

Este processo de baixo nível nos dá controle total, que é exatamente o que um agente autônomo precisa.

2. Implementando o Fluxo de Commit com a API do GitHub

Para entender como esses passos se traduzem em chamadas de API, vamos analisar um guia prático.

Como seu background principal é em C#/.NET, vamos ver como esse mesmo fluxo se parece usando a biblioteca Octokit.net.

Dentro do seu agente, você criaria uma "ferramenta" ou "skill" (provavelmente em Node.js, no ambiente Forge) que encapsularia essa lógica. Ela receberia os caminhos dos arquivos, seus conteúdos e uma mensagem de commit, e executaria essa sequência de chamadas de API para cada repositório no seu workspace.

3. Criando o Pull Request

Uma vez que as branches com os commits existem em cada repositório remoto, o passo final é criar os Pull Requests. Este é um processo muito mais simples, geralmente uma única chamada de API.

A chamada de API seria um POST para o endpoint /repos/{owner}/{repo}/pulls. O corpo desta requisição conteria:

• title: O título do PR (ex: feat(PROJ-123): Implementa data de nascimento do usuário).
• body: A descrição detalhada, que o agente pode gerar para resumir as alterações e incluir um link para o ticket do Jira.
• head: O nome da nossa branch de recursos (ex: feature/PROJ-123-backend).
• base: O nome da branch alvo (ex: main ou develop).
• E opcionalmente: reviewers, assignees, labels, etc.

4. Um Blueprint para uma Ferramenta de PR Robusta

Embora nosso agente vá fazer isso através de chamadas de API diretas, podemos nos inspirar em ferramentas existentes para projetar uma ação robusta. O create-pull-request é uma GitHub Action popular que serve como um excelente "blueprint".

5. Integrando com o Ecossistema Atlassian

Como tudo isso se encaixa no seu objetivo de usar Rovo e Forge?

No Módulo 5, definimos o que são as "ações" ou "ferramentas" de um agente. O fluxo de trabalho que descrevemos hoje seria implementado como duas ações principais no Forge:

1. commit_and_push(repository, branch_name, files, commit_message): Esta função em Forge conteria o código Node.js para executar a sequência de criação de blobs, árvores, commits e a atualização da referência.
2. create_pull_request(repository, branch_name, base_branch, title, body): Esta função faria a chamada de API POST para criar o Pull Request e retornaria sua URL.

O seu agente orquestrador, após gerar e agregar todos os arquivos, executaria o seu plano, que se pareceria com algo assim:

1. Para o repositório backend-repo:
   • Chamar commit_and_push com os arquivos C# e o script de migração.
   • Chamar create_pull_request para criar o PR do backend. Armazenar a URL.
2. Para o repositório frontend-repo:
   • Chamar commit_and_push com os arquivos React.
   • Chamar create_pull_request para criar o PR do frontend. Armazenar a URL.
3. ... e assim por diante para cada repositório modificado.

O vídeo a seguir sobre Rovo ilustra como essas ações (chamadas de "skills") e a lógica de automação se unem.

Conclusão

Nesta lição, detalhamos o mecanismo para que o agente possa materializar seu trabalho no GitHub. Passamos da teoria dos objetos Git para a implementação prática usando a API REST, e vimos como isso se encaixa na arquitetura de um agente Rovo.

Principais Pontos:

• A criação de um commit via API é um processo de múltiplos passos que envolve a criação de blobs, uma árvore, um commit e a atualização de uma referência.
• Bibliotecas como Octokit.net (para C#) ou equivalentes em Node.js simplificam a interação com a API do Git Data.
• A criação de um Pull Request é uma única chamada de API que associa a branch de origem (head) com a de destino (base) e anexa metadados como título e descrição.
• As ferramentas do nosso agente devem ser projetadas para serem robustas, inspirando-se em exemplos como a GitHub Action create-pull-request, e devem retornar saídas úteis como a URL do PR.
• No ecossistema Atlassian, essa lógica seria encapsulada em skills personalizadas do Forge, que o agente orquestrador invocaria como parte de seu plano de execução.

Agora que temos os Pull Requests criados e suas URLs em mãos, o ciclo de trabalho do agente está quase completo. Na próxima lição, vamos fechar o ciclo: usaremos uma ação do Jira para atualizar o ticket original, adicionando comentários com os links para os PRs e movendo seu status para "In Review", notificando a equipe de que o trabalho automatizado está pronto para a validação humana.