Como usar a API REST para interagir com seu banco de dados Git

Use a API REST para ler e gravar objetos Git brutos em seu banco de dados Git em GitHub Enterprise Cloud e para listar e atualizar suas referências (marcas e cabeçalhos de ramificação).

Neste artigo

Visão geral

Isso basicamente permite que você reimplemente uma série de funcionalidades do Git com a API REST, criando objetos sem processamento diretamente no banco de dados e atualizando referências de ramificações que você pode fazer tecnicamente sobre qualquer coisa que o Git possa fazer sem tê-lo instalado.

A API REST retornará 409 Conflict se o repositório Git estiver vazio ou indisponível. Um repositório indisponível normalmente significa que o GitHub Enterprise Cloud está no processo de criação do repositório. Para um repositório vazio, use o ponto de extremidade PUT /repos/{owner}/{repo}/contents/{path} API REST para criar um conteúdo e inicializar o repositório a fim de usar a API para gerenciar o banco de dados do Git. Entre em contato com conosco por meio do Portal de suporte do GitHub se esse status de resposta persistir.

Para obter mais informações sobre o banco de dados de objetos do Git, leia o capítulo Componentes internos do Git do livro Pro Git.

Por exemplo, se desejar fazer commit de uma alteração em um arquivo no seu repositório, você vai:

  • Obter o objeto do commit atual
  • Recuperar a árvore para a qual ele aponta
  • Recuperar o conteúdo do objeto do blob que a árvore tem para esse caminho específico do arquivo
  • Alterar o conteúdo de alguma forma e postar um novo objeto do blob com esse novo conteúdo, obtendo, em troca, o SHA do blob
  • Publicar um novo objeto da árvore com esse ponteiro do caminho de arquivo substituído pelo SHA do seu blob novo e obtendo, em troca, o SHA da árvore
  • Criar um novo objeto de confirmação com o SHA do commit atual como o principal e o SHA da novo da árvore, obtendo, em troca, o SHA do commit
  • Atualizar a referência do seu branch para apontar para o novo SHA do commit

Pode parecer complexo, mas, na verdade, é bem simples quando você entende o modelo e ele revela várias coisas que podem ser feitas com a API.

Verificar a mesclabilidade de pull requests

Warning

Não dependa do uso direto do Git ou de GET /repos/{owner}/{repo}/git/refs/{ref} para atualizações de referências de merge do Git, pois esse conteúdo fica desatualizado sem aviso.

Uma API de consumo precisa solicitar explicitamente uma solicitação de pull para criar um commit de mesclagem de teste. Um commit de mesclagem de teste é criado quando você visualiza a solicitação de pull na interface do usuário e o botão "Mesclar" é exibido ou quando você obtém, cria ou edita uma solicitação de pull usando a API REST. Sem essa solicitação, as referências de merge do Git ficarão desatualizadas até a próxima vez que alguém visualizar a solicitação de pull.

Se você está usando métodos de sondagem que produzem referências de merge obsoletas do Git, o GitHub recomenda usar as seguintes etapas para obter as últimas alterações do branch padrão:

  1. Receber o webhook do pull request.
  2. Chame GET /repos/{owner}/{repo}/pulls/{pull_number} para iniciar um trabalho em segundo plano para criar o candidato de commit de mesclagem.
  3. Sonde seu repositório usando GET /repos/{owner}/{repo}/pulls/{pull_number} para ver se o atributo mergeable é true ou false. Use o Git diretamente ou GET /repos/{owner}/{repo}/git/refs/{ref} para atualizações das referências de merge do Git somente depois de executar as etapas anteriores.