A API Checks API do GitHub visa tornar possível integrar as verificações de código em um fluxo de trabalho de integração contínua. Por exemplo, poderia se passar um código-fonte numa ferramenta de análise, e apresentar os resultados diretamente na visualização do pull request. O feedback pode ser tão detalhado quanto desejado, mostrando, por exemplo, a linha de código que causou um problema, permitindo assim que o autor do commit corrija os problemas e execute uma nova verificação no código.
A API de verificação (Checks API) do GitHub pode ser considerada uma evolução da API tradicional de status do GitHub (Statuses API), que permite que serviços externos marquem os commits com um código de status (falhou /passou) que é refletido nos pull requests referentes a esses commits.
Ao usar a Checks API, os integradores têm agora um controle mais refinado sobre o status de um commit ou pull request, incluindo sucesso, falha, neutro, cancelado, timed_out ou ação_requerida, bem como enfileirado, in_progress ou concluído. Além disso, uma verificação pode incluir uma variedade de dados, como informações textuais, imagens, e etc. Isso permite criar fluxos de trabalho sofisticados em que você tem várias verificações rodando num commit ou pull request, e o GitHub mostrará quais passaram e quais falharam e requerem atenção.
O GitHub suporta vários níveis de controles de fluxos de trabalho de verificação:
- Automático: todos os aplicativos instalados com a permissão
checks:writereceberão eventos para que comecem a analisar as alterações. Todos os aplicativos que executam verificações são listados pela interface do usuário do GitHub para que o integrador e o desenvolvedor possam monitorar como as verificações progridem e tomar medidas, se necessário. - Usuário: uma verificação específica pode ser solicitada por meio de uma solicitação como:
POST /repos/:owner/:repo/check-suite-requests, ou adicionando-se diretivas para uma mensagem de commitskip-checks: true or request-checks: true - Interface Web: os usuários podem executar verificações individuais ou em todos os fluxos usando a interface web do GitHub.
Para que um aplicativo do GitHub consiga executar verificações ele deve manipular os webhooks check_suite, que especificam as ações solicitadas. O app pode, então, criar uma nova verificação que o GitHub adicionará à suíte de verificação desse aplicativo, que resume todas as verificações e os resultados. Inicialmente, o aplicativo criará uma execução de verificação no estado enfileirado ou em andamento, atualizando-a à medida que avança.
Atualmente, a Checks API do GitHub funciona somente com a API REST do GitHub, enquanto o suporte para verificações na API do GraphQL está em funcionamento.