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 Criando verificações de CI com um Aplicativo do GitHub.
Você pode usar esses status com branches protegidos para impedir que as pessoas mesclem solicitações de pull prematuramente. Para saber mais, confira Sobre branches protegidos.
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.
O status pode ser queued, in_progress, requested, waiting, pending, ou completed. Apenas GitHub Actions podem definir um status de requested, waiting, ou pending.
Se o status for completed, a conclusão poderá ser qualquer uma das seguintes:
action_requiredcancelledtimed_outfailureneutralskippedstalestartup_failuresuccess
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 se autenticar como um GitHub App, confira "Sobre a autenticação com um GitHub App".
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.
O status pode ser queued, in_progress, requested, waiting, pending, ou completed. Apenas GitHub Actions podem definir um status de requested, waiting, ou pending.
Se o status for completed, a conclusão poderá ser qualquer uma das seguintes:
action_requiredcancelledtimed_outfailureneutralskippedsuccess
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.
As anotações adicionam informações de sua execução de verificação a linhas de código específicas. Cada anotação inclui uma propriedade annotation_level, que pode ser notice, warningou failure. A anotação também inclui path, start_line e end_line para especificar a qual local ela se refere. A anotação inclui uma message para descrever o resultado. Para saber mais, confira Pontos de extremidade da API REST para execuções de verificação.
Uma verificação também pode ser reexecutada manualmente na interface do usuário do GitHub. Confira Sobre verificações de status para obter mais detalhes. Quando isso ocorrer, o GitHub App 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 na guia Verificações de uma solicitação de pull com o rótulo "Corrigir". 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"
}]
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 Criando verificações de CI com um Aplicativo do GitHub.
Retenção de dados de verificação
A GitHub retém os dados de verificação por 400 dias. Após esses 400 dias, os dados são arquivados. Dez dias após o arquivamento, os dados são excluídos permanentemente.
Para mesclar uma solicitação de pull com verificações necessárias e arquivadas, execute novamente as verificações.