# Como usar a API REST para interagir com verificações Você pode usar a API REST para criar GitHub Apps que faz 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 proporcionar status de criação de aprovação/falha, GitHub Apps pode relatar status enriquecidos, anotar linhas de código com informações detalhadas e executar testes novamente. A API REST para gerenciar verificações está disponível exclusivamente para seus aplicativos GitHub. Para obter um exemplo de como usar a API REST com um GitHub App, consulte [Criando verificações de CI com um aplicativo GitHub](/pt/enterprise-server@3.22/apps/creating-github-apps/writing-code-for-a-github-app/building-ci-checks-with-a-github-app#step-26-automatically-fix-rubocop-errors). Você pode usar esses status com [branches protegidos](/pt/enterprise-server@3.22/rest/repos#branches) para impedir que as pessoas mesclem solicitações de pull prematuramente. Para saber mais, confira [Sobre branches protegidos](/pt/enterprise-server@3.22/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches#require-status-checks-before-merging). ## Sobre os conjuntos de verificações Quando alguém envia código via push para um repositório, o GitHub cria uma suíte de verificação para a última confirmação. Um conjunto de verificações é uma coleção das [execuções de verificação](/pt/enterprise-server@3.22/rest/checks#check-runs) 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`. Só GitHub Actions pode definir um status de `requested`, `waiting`ou `pending`. Se o status for `completed`, a conclusão poderá ser qualquer uma das seguintes: * `action_required` * `cancelled` * `timed_out` * `failure` * `neutral` * `skipped` * `stale` * `startup_failure` * `success` 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 é enviado para o repositório. Esse fluxo padrão envia o evento `check_suite` (com `requested` ação) para todos os Aplicativos 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](/pt/enterprise-server@3.22/rest/checks#check-suites) 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 endpoint [Atualizar preferências do repositório para conjuntos de verificações](/pt/enterprise-server@3.22/rest/checks/suites#update-repository-preferences-for-check-suites). 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 check suite usando o endpoint [Create a check suite](/pt/enterprise-server@3.22/rest/checks/suites#create-a-check-suite). Você deve continuar usando o endpoint [Criar uma execução de verificação](/pt/enterprise-server@3.22/rest/checks/runs#create-a-check-run) 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](/pt/enterprise-server@3.22/rest/commits#commit-statuses). Para usar os pontos de verificação para gerenciar conjuntos de verificações, o GitHub App precisa ter a permissão `checks:write` e também pode assinar um webhook [check\_suite](/pt/enterprise-server@3.22/webhooks/webhook-events-and-payloads#check_suite). Para obter informações sobre como se autenticar como um GitHub App, confira [Sobre a autenticação com um aplicativo GitHub](/pt/enterprise-server@3.22/apps/creating-github-apps/authenticating-with-a-github-app/about-authentication-with-a-github-app). ## Sobre as execuções de verificação Uma execução de teste é um teste individual que faz parte de uma suíte de testes. Cada execução inclui um status e uma conclusão. O `status` pode ser `queued`, `in_progress`, `requested`, `waiting`, `pending`, ou `completed`. Só GitHub Actions pode definir um status de `requested`, `waiting`ou `pending`. Se o status for `completed`, a conclusão poderá ser qualquer uma das seguintes: * `action_required` * `cancelled` * `timed_out` * `failure` * `neutral` * `skipped` * `success` Se uma execução de verificação permanecer em estado incompleto por mais de 14 dias, o `conclusion` da execução de verificação se tornará `stale` e aparecerá em GitHub como desatualizado com . Somente GitHub pode marcar as 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`](/pt/enterprise-server@3.22/rest/checks#create-a-check-run--parameters). Assim que você receber o webhook [`check_suite`](/pt/enterprise-server@3.22/webhooks/webhook-events-and-payloads#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 do seu processo de verificação a linhas específicas de código. Cada anotação inclui uma propriedade `annotation_level`, que pode ser `notice`, `warning`ou `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](/pt/enterprise-server@3.22/rest/checks/runs). Uma verificação também pode ser executada manualmente na interface do usuário do GitHub. Confira [Verificações de status](/pt/enterprise-server@3.22/pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/about-status-checks#checks) para obter mais detalhes. Quando isso ocorrer, o GitHub App que criou a execução de verificação receberá o [`check_run`](/pt/enterprise-server@3.22/webhooks/webhook-events-and-payloads#check_run) webhook 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](/pt/enterprise-server@3.22/rest/commits#commit-statuses). Para usar os pontos de verificação para gerenciar conjuntos de verificações, o GitHub App precisa ter a permissão `checks:write` e também pode assinar um webhook [check\_run](/pt/enterprise-server@3.22/webhooks/webhook-events-and-payloads#check_run). ## Execuções de verificação e ações solicitadas Ao configurar uma execução de verificação com ações solicitadas (para não ser confundido com GitHub Actions), você pode exibir um botão na visualização da pull request em GitHub que permite que as pessoas solicitem que seu GitHub App execute 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`](/pt/enterprise-server@3.22/rest/checks/runs#create-a-check-run--parameters) quando [Criar uma execução de verificação](/pt/enterprise-server@3.22/rest/checks#create-a-check-run). 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. ```json "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 [`check_run.requested_action` webhook](/pt/enterprise-server@3.22/webhooks/webhook-events-and-payloads#check_run) para 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 GitHub](/pt/enterprise-server@3.22/apps/creating-github-apps/writing-code-for-a-github-app/building-ci-checks-with-a-github-app). ## Retenção de dados de verificação Os administradores do site podem controlar a política de retenção dos dados de verificações em sua instância do GitHub Enterprise Server. Para saber mais, confira [Configurando aplicativos](/pt/enterprise-server@3.22/admin/configuring-settings/configuring-user-applications-for-your-enterprise/configuring-applications#enabling-retention-policy-for-checks). Para mesclar uma solicitação de pull com verificações necessárias e arquivadas, execute novamente as verificações.