Skip to main content

Como usar a API REST para interagir com verificações

Use a API REST para criar GitHub Apps que executam verificações avançadas em alterações de código em um repositório. Você pode criar os aplicativos que realizam integração contínua, linting ou serviços de varredura de código e fornecem feedback detalhado sobre commits.

Visão geral

Em vez de oferecer status de criação de aprovação/falha binários, o GitHub Apps pode relatar status sofisticados, anotar linhas de código com informações detalhadas e executar testes novamente. A API REST para gerenciar as verificações está disponível exclusivamente para o GitHub Apps.

Para ver um exemplo de como usar a API REST com um GitHub App, confira "Como criar testes de CI com a API de Verificações".

Sobre os conjuntos de verificações

Quando alguém faz push de código em um repositório, o GitHub cria um conjunto de verificações para o último commit. Um conjunto de verificações é uma coleção das execuções de verificação criadas por um Aplicativo do GitHub individual para um commit específico. Os conjuntos de verificações resumem o estado e conclusão das execuções de verificação que um conjunto inclui.

Fluxo de trabalho dos conjuntos de verificações

O conjunto de verificações relata a conclusion da execução de verificação com a prioridade mais alta na conclusion do conjunto de verificações. Por exemplo, se três execuções de verificação tiverem as conclusões timed_out, success e neutral, a conclusão do conjunto de verificações será timed_out.

Por padrão, o GitHub cria um conjunto de verificações automaticamente quando o código é carregado no repositório. Esse fluxo padrão envia o evento check_suite (com a ação requested) para todos os Aplicativos do GitHub que têm a permissão checks:write. Quando o Aplicativo do GitHub recebe o evento check_suite, ele pode criar execuções de verificação para o commit mais recente. O GitHub adiciona automaticamente novas execuções de verificação ao conjunto de verificações correto com base no repositório e no SHA da execução de verificação.

Se você não desejar usar o fluxo automático padrão, você poderá controlar quando criar conjuntos de verificação. Para alterar as configurações padrão para a criação de conjuntos de verificações, use o ponto de extremidade Atualizar preferências do repositório para conjuntos de verificações. Todas as alterações nas configurações de fluxo automático são registradas no log de auditoria do repositório. Se você tiver desabilitado o fluxo automático, poderá criar um conjunto de verificações usando o ponto de extremidade Criar um conjunto de verificações. Você deve continuar usando o ponto de extremidade Criar uma execução de verificação para fornecer comentários sobre um commit.

A permissão de gravação para a API REST interagir com verificações só está disponível com relação a GitHub Apps. Os OAuth Apps e os usuários autenticados podem ver as execuções de verificação e os conjunto de verificações, mas não podem criá-los. Se você não estiver criando um GitHub App, poderá se interessar em usar a API REST para interagir com os status de commit.

Para usar os pontos de extremidade para gerenciar pacotes de verificações, o GitHub App precisa ter a permissão checks:write e poder assinar o webhook check_suite.

Para obter informações sobre como autenticar como um aplicativo GitHub, confira "Opções de autenticação para aplicativos GitHub".

Sobre as execuções de verificação

Uma execução de verificação é um teste individual que faz parte de um conjunto de verificações. Cada execução inclui um status e uma conclusão.

Fluxo de trabalho das execuções de verificação

Se uma execução de verificação estiver em um estado incompleto por mais de 14 dias, a conclusion da execução de verificação passará a ser stale e será exibida no GitHub como obsoleta com . Somente o GitHub pode marcar execuções de verificação como stale. Para obter mais informações sobre as possíveis conclusões de uma execução de verificação, confira o parâmetro conclusion.

Assim que você receber o webhook check_suite, poderá criar a execução de verificação, mesmo que a verificação não esteja concluída. Você poderá atualizar a status da execução da verificação conforme ela for concluída com os valores queued, in_progress ou completed e atualizar a output à medida que mais detalhes estiverem disponíveis. Uma verificação de execução pode conter registros de hora, um link para obter mais informações sobre o seu site externo, anotações detalhadas para linhas específicas de código, e informações sobre a análise realizada.

Anotação da execução de verificação

Uma verificação também pode ser reexecutada manualmente na interface do usuário do GitHub. Confira "Sobre as verificações de status" para obter mais detalhes. Quando isso ocorrer, o Aplicativo do GitHub que criou a execução de verificação receberá o webhook check_run solicitando uma nova execução de verificação. Se você criar uma execução de verificação sem criar um conjunto de verificações, o GitHub criará automaticamente o conjunto de verificações para você.

A permissão de gravação para a API REST interagir com verificações só está disponível com relação a GitHub Apps. Os OAuth Apps e os usuários autenticados podem ver as execuções de verificação e os conjunto de verificações, mas não podem criá-los. Se você não estiver criando um GitHub App, poderá se interessar em usar a API REST para interagir com os status de commit.

Para usar os pontos de extremidade para gerenciar as execuções de verificação, o GitHub App precisa ter a permissão checks:write e poder assinar o webhook check_run.

Execuções de verificação e ações solicitadas

Ao configurar uma verificação de execução com as ações solicitadas (não confundir com GitHub Actions), você pode exibir um botão na exibição de pull request no GitHub que permite que pessoas solicitem o seu GitHub App para executar tarefas adicionais.

Por exemplo, um aplicativo de linting de código poderia usar ações solicitadas para exibir um botão em um pull request para corrigir automaticamente erros de sintaxe detectados.

Para criar um botão que possa solicitar ações adicionais por meio do seu aplicativo, use o objeto actions quando Criar uma execução de verificação. Por exemplo, o objeto actions abaixo exibe um botão em uma solicitação de pull com o rótulo "Corrigir isso". O botão é exibido após a conclusão da execução da verificação.

"actions": [{
   "label": "Fix this",
   "description": "Let us fix that for you",
   "identifier": "fix_errors"
 }]

Botão de ação solicitada de execução de verificação

Quando um usuário clica no botão, o GitHub envia o webhook check_run.requested_action ao seu aplicativo. Quando o aplicativo recebe um evento de webhook check_run.requested_action, ele pode procurar a chave requested_action.identifier no conteúdo do webhook para determinar qual botão recebeu um clique e executar a tarefa solicitada.

Para ver um exemplo detalhado de como configurar ações solicitadas com a API REST, confira "Como criar testes de CI com a API de Verificações".

Retenção de dados de verificação

Verifica se os dados com mais de 400 dias estão arquivados. Como parte do processo de arquivamento, o GitHub cria um status de confirmação de rollup que representa o estado de todas as verificações para essa confirmação. Como consequência, a caixa de mesclagem em qualquer solicitação pull com verificações arquivadas necessárias estará em um estado bloqueado e você precisará executar novamente as verificações antes de poder mesclar a solicitação pull.