Creating a Pull Request

1. A Anatomia de uma Chamada de API para Pull Request

Assim como nas outras interações com o GitHub, a API REST nos fornece um endpoint específico para gerenciar pull requests. A criação de um PR é essencialmente uma requisição POST que informa ao GitHub que você deseja mesclar as alterações de um branch (o head) para outro (o base).

Para entender os detalhes, vamos consultar a documentação oficial.

Esses quatro parâmetros se traduzem diretamente nos campos que você preenche na interface do usuário do GitHub ao criar um PR manualmente.

Para realizar esta ação, nosso agente precisará da permissão de "Pull requests" (gravação) no repositório, algo que você configurou na lição sobre autenticação segura.

2. Implementando a Ação create-pull-request no Forge

Agora, vamos traduzir esse conhecimento da API em uma ação concreta do Forge. Primeiro, definimos a ação e seus parâmetros no manifest.yml.

# Em manifest.yml
rovo:agent:



  # ...
  actions:



    # ... outras ações como create-branch e commit-file
    - key: create-pull-request
      function: createPullRequest # Nome da função JS a ser exportada
      description: Cria um pull request em um repositório GitHub.
      parameters:
        type: object
        properties:
          repositoryOwner:
            type: string
            description: O proprietário do repositório GitHub.
          repositoryName:
            type: string
            description: O nome do repositório.
          headBranch:
            type: string
            description: O branch de origem contendo as alterações (o 'head').
          baseBranch:
            type: string
            description: O branch de destino para o qual as alterações serão mescladas (o 'base').
          title:
            type: string
            description: O título do pull request.
          body:
            type: string
            description: A descrição detalhada (corpo) do pull request.
        required:
          - repositoryOwner
          - repositoryName
          - headBranch
          - baseBranch
          - title

Com a ação definida, implementamos a lógica correspondente em src/index.js. A função fará uma requisição POST para o endpoint /pulls com os dados fornecidos.

import api from '@forge/api';

// ... outras funções de ação ...

/**
 * Cria um pull request em um repositório GitHub.
 * @param {object} payload - O payload da ação do agente.
 * @returns {Promise<object>} - Os detalhes do pull request criado, incluindo sua URL.
 */
export async function createPullRequest({
  repositoryOwner,
  repositoryName,
  headBranch,
  baseBranch,
  title,
  body
}) {
  console.log(`Criando pull request: '${title}' de ${headBranch} para ${baseBranch}.`);

  const githubApi = api.asUser().withProvider('github', 'github-api');
  const endpoint = `/repos/${repositoryOwner}/${repositoryName}/pulls`;

  // Preparar o corpo da requisição POST
  const requestBody = {
    title: title,
    head: headBranch,
    base: baseBranch,
    body: body,
  };

  // Fazer a requisição POST para criar o pull request
  const response = await githubApi.fetch(endpoint, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Accept': 'application/vnd.github+json',
      'X-GitHub-Api-Version': '2022-11-28'
    },
    body: JSON.stringify(requestBody),
  });

  if (response.status !== 201) { // 201 Created é o status de sucesso esperado
    const errorText = await response.text();
    console.error('Falha ao criar o pull request:', errorText);
    throw new Error(`Falha ao criar o pull request. Status: ${response.status}. Resposta: ${errorText}`);
  }

  const prDetails = await response.json();
  console.log(`Pull request criado com sucesso! URL: ${prDetails.html_url}`);

  // Retornar informações úteis, como a URL e o número do PR.
  return {
    number: prDetails.number,
    url: prDetails.html_url,
    state: prDetails.state,
  };
}

Análise do Código

• Endpoint e Método: Usamos o endpoint /repos/{owner}/{repo}/pulls com o método POST, conforme especificado na documentação.
• Corpo da Requisição: O objeto requestBody é uma tradução direta dos parâmetros da nossa ação para o formato que a API do GitHub espera.
• Manipulação de Resposta: Verificamos se o status da resposta é 201, que é o código HTTP para "Created" e indica sucesso. Se não for, lançamos um erro detalhado para facilitar a depuração.
• Valor de Retorno: Ao ter sucesso, extraímos e retornamos o html_url do pull request. Este é um dado extremamente valioso, pois permite que o agente (ou um sistema externo) tenha um link direto para o PR que acabou de criar, possibilitando, por exemplo, postar um comentário no Jira com o link para revisão.

3. Orquestrando o Fluxo de Trabalho Completo

Com as ações create-branch, commit-file e create-pull-request implementadas, nosso agente agora possui os blocos de construção para um fluxo de trabalho de desenvolvimento completo. O poder real emerge quando um orquestrador (como o próprio agente Rovo ou uma lógica de planejamento) invoca essas ações em sequência:

1. Analisar Tarefa: O agente lê uma tarefa do Jira.
2. Planejar Ações: Ele determina que precisa modificar o arquivo-A.cs e criar o arquivo-B.js.
3. Executar Ações:
   • Chama create-branch para criar feature/JIRA-123-new-login-flow.
   • Chama commit-file para o arquivo-A.cs no novo branch.
   • Chama commit-file para o arquivo-B.js no mesmo branch.
   • Chama create-pull-request com head: 'feature/JIRA-123...', base: 'main', title: '[JIRA-123] Novo Fluxo de Login' e um body que resume as alterações.

O vídeo a seguir, embora use o framework LangGraph, ilustra perfeitamente este conceito de um agente executando um plano passo a passo para, no final, criar um pull request.

Conclusão

Parabéns! Você acaba de implementar a peça final do quebra-cabeça para o ciclo básico de contribuição de código do seu agente. Agora ele pode não apenas executar o trabalho, mas também formalmente propô-lo para integração, fechando o loop do desenvolvimento de uma funcionalidade.

Principais Pontos:

• Endpoint Chave: A criação de pull requests é feita via POST /repos/{owner}/{repo}/pulls.
• Parâmetros Essenciais: Os parâmetros head, base, title, e body são fundamentais e mapeiam diretamente para a funcionalidade do PR.
• Valor do Retorno: A resposta da API em caso de sucesso contém informações vitais, como a URL do PR (html_url), que são cruciais para a rastreabilidade.
• Fluxo de Trabalho Completo: A combinação das ações de branch, commit e pull request forma um pipeline completo de contribuição de código que seu agente pode agora executar autonomamente.

Na Próxima Lição:

Com o Módulo 5, estabelecemos o "como" — como nosso agente pode agir no mundo externo (especificamente, no GitHub). No entanto, um agente poderoso precisa também do "o quê" e do "porquê". No próximo módulo, "Análise e Planejamento de Tarefas Orientados pelo Agente", vamos mergulhar na parte de "planejamento" do ciclo perceber-planejar-agir. Começaremos a ensinar nosso agente a pensar: como analisar um ticket do Jira, consultar a base de conhecimento e decompor uma tarefa complexa em uma sequência de ações como as que você acabou de construir.