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 e para listar e atualizar suas referências (cabeçalhos de ramificação e tags).

Neste artigo

Visão geral

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

A API REST retornará 409 Conflict se o repositório Git estiver vazio ou indisponível. Quando um repositório está indisponível, isso normalmente significa que o GitHub está no processo de criação desse repositório. Para um repositório vazio, você pode usar o endpoint da API REST para criar conteúdo e inicializar o repositório, permitindo assim o uso da API para gerenciar o repositório 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 o objeto aponta
  • Recupere o conteúdo do objeto 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 possibilidade de mescla de pull requests

Aviso

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 explicitamente solicitar um pull request para criar um commit de teste de mesclagem. 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ê estiver usando métodos de sondagem que produzem refs git merge desatualizados, GitHub recomenda usar as seguintes etapas para obter as alterações mais recentes do branch padrão:

  1. Receber o webhook do pull request.
  2. Invoque GET /repos/{owner}/{repo}/pulls/{pull_number} para iniciar uma tarefa em segundo plano para criar o candidato a 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 nas refs do Git somente depois de executar as etapas anteriores.