Visão Geral
Em vez de proporcionar status de criação de aprovação/falha, os aplicativos GitHub podem relatar status enriquecidos, anotar linhas de código com informações detalhadas e executar testes novamente. A funcionalidade API de Verificação está disponível exclusivamente para os seus aplicativos GitHub.
Para obter um exemplo de como usar a API de verificação com um aplicativo GitHub, consulte "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 de execuções de verificação criadas por um único aplicativo GitHub 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 conjunto de verificações reporta conclusão da execução da verificação com a prioridade mais alta na conclusão do conjunto de verificações. Por exemplo, se três execuções de verificações tiverem 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. Este fluxo padrão envia o evento check_suite (com a ação requested) para todos os aplicativos GitHub com a permissão checks:write. Quando o seu aplicativo do GitHub receber o evento check_suite, ele poderá criar uma nova verificação executa o último commit. O GitHub adiciona automaticamente novas execuções de verificação ao conjunto de verificações 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ção, use o ponto de extremidade Atualizar as preferências do repositório para conjuntos de verificação. 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, você poderá criar um suíte de verificação usando o ponto de extremidade Criar uma conjunto de verificações. Você deve continuar usando o ponto de extremidade Criar uma execução de verificação para fornecer feedback sobre um commit.
A permissão de escrita para a API de verificação só está disponível para aplicativos GitHub. Aplicativos OAuth e usuários autenticados podem ver as execuções de verificação e conjunto de verificações, mas eles não são capazes de criá-los. Se você não estiver criando um aplicativo no GitHub, talvez você esteja interessado no Statuses API.
Para usar a API de conjuntos de verificações, o aplicativo GitHub deve ter a permissão de checks:write e também poderá assinar o webhook de check_suite.
Para obter informações sobre como efetuar a autenticação como um aplicativo GitHub, consulte "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.
Se uma execução de verificação estiver em um estado incompleto por mais de 14 dias, a execução de verificação conclusão irá tornar-se obsoleta e será exibida em GitHub como obsoleto com . Somente GitHub pode marcar a execuções de verificação como obsoleto. Para obter mais informações sobre possíveis conclusões de uma execução de verificação, consulte o parâmetro conclusão.
Assim que você receber o webhook de check_suite, você poderá criar a execução de verificação, mesmo que a verificação não esteja completa. Você pode atualizar o status da execução de verificação, pois ele é completado com os valores de queued, in_progress ou completed, e você poderá atualizar a saída de `` conforme mais informações forem disponibilizadas. 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.
Uma verificação também pode ser reexecutada manualmente na interface do usuário do GitHub. Consulte "Sobre verificações de statuspara obter mais informações. Quando isso ocorre, o aplicativo GitHub que criou a execução de verificação receberá o webhook check_run, solicitando uma nova verificação de execuçã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 escrita para a API de verificação só está disponível para aplicativos GitHub. Aplicativos OAuth e usuários autenticados podem ver as execuções de verificação e conjunto de verificações, mas eles não são capazes de criá-los. Se você não estiver criando um aplicativo no GitHub, talvez você esteja interessado no Statuses API.
Para usar a API de execução de verificações, o aplicativo GitHub deve ter a permissão checks:write e também deve poder assinar o webhook de 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 aplicativo GitHub 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 do seu aplicativo, use as ações objeto ao criar uma execução de verificação. Por exemplo, o objeto de ações abaixo exibe um botão em um pull request com a etiqueta "Corrija 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"
}]
Quando um usuário clica no botão, GitHub envia o webhook check_run.requested_action para seu aplicativo. Quando o seu aplicativo recebe um evento de webhook de check_run.requested_action, ele pode procurar a chave requested_action.identifier na carga do webhook para determinar qual botão se clicou para executar a tarefa solicitada.
Para obter um exemplo detalhado de como configurar as ações solicitadas com a API de verificações, consulte "Criar testes de CI com a API de verificações."