Skip to main content
We publish frequent updates to our documentation, and translation of this page may still be in progress. For the most current information, please visit the English documentation.

Utilisation de l’API REST pour interagir avec des vérifications

Vous pouvez utiliser l’API REST pour créer des GitHub Apps qui exécutent des contrôles puissants sur les modifications du code dans un dépôt. Vous pouvez créer des applications qui effectuent une intégration continue, un linting de code ou des services d’analyse de code et fournir des commentaires détaillés sur les validations.

Vue d’ensemble

À la place des états de build binaires « pass/fail », GitHub Apps peut signaler des états détaillés, annoter des lignes de code avec des informations détaillées et réexécuter les tests. L’API REST pour gérer les vérifications est disponible exclusivement pour vos applications GitHub.

Pour obtenir un exemple d’utilisation de l’API REST avec une GitHub App, consultez « Création de tests CI avec l’API Checks ».

À propos des suites de vérifications

Lorsqu’une personne pousse (push) du code vers un dépôt, GitHub crée une suite de vérifications pour le dernier commit. Une suite de vérifications est une collection d’exécutions de vérifications créées par une application GitHub pour un commit spécifique. Les suites de vérifications récapitulent l’état et la conclusion des exécutions de vérifications qui se trouvent dans la suite.

Vérifier le workflow d’une suite

La suite de vérifications indique la conclusion de l’exécution de vérifications ayant la priorité la plus élevée dans sa propre conclusion. Par exemple, si trois séries de vérifications ont les conclusions timed_out, successet neutral, la conclusion de la suite de vérifications sera timed_out.

Par défaut, GitHub crée automatiquement une suite de vérifications lorsque le code est poussé vers le dépôt. Ce flux par défaut envoie l’événement check_suite (avec l’action requested) à toutes les applications GitHub qui disposent de l’autorisation checks:write. Lorsque votre application GitHub reçoit l’événement check_suite, elle peut créer de nouvelles exécutions de vérifications pour le dernier commit. GitHub ajoute automatiquement de nouvelles exécutions de vérifications à la suite de vérifications correspondante, en fonction du dépôt et du SHA de l’exécution de vérification.

Si vous ne souhaitez pas utiliser le flux automatique par défaut, vous pouvez contrôler à quel moment créer les suites de vérifications. Pour modifier les paramètres par défaut de la création de suites de vérifications, utilisez le point de terminaison Mettre à jour les préférences du dépôt pour les suites de vérifications. Toutes les modifications apportées aux paramètres de flux automatique sont enregistrées dans le journal d’audit du dépôt. Si vous avez désactivé le flux automatique, vous pouvez créer une suite de vérifications à l’aide du point de terminaison Créer une suite de vérifications. Vous devez continuer à utiliser le point de terminaison Créer une exécution de vérification pour fournir des commentaires sur un commit.

L’autorisation d’écriture permettant à l’API REST d’interagir avec les vérifications n’est disponible que pour GitHub Apps. OAuth Apps et les utilisateurs authentifiés peuvent afficher les exécutions de vérification et les suites de vérifications, mais ils ne peuvent pas les créer. Si vous ne générez pas de GitHub App, l’utilisation de l’API REST pour interagir avec les états de validation peut vous intéresser.

Pour utiliser les points de terminaison afin de gérer les suites de vérifications, GitHub App doit avoir l’autorisation checks:write et peut également s’abonner au webhook check_suite.

Pour plus d’informations sur l’authentification en tant qu’application GitHub, consultez « Options d’authentification pour les applications GitHub ».

À propos des exécutions de vérifications

Une exécution de vérification est un test individuel qui fait partie d’une suite de vérifications. Chaque exécution comprend un état et une conclusion.

Workflow des exécutions de vérifications

Si une exécution de vérification est à l’état incomplet pendant plus de 14 jours, la conclusion de l’exécution de vérification devient stale et apparaît dans GitHub comme étant obsolète avec . Seul GitHub peut marquer les exécutions de vérifications comme étant stale. Pour plus d’informations sur les conclusions possibles d’une exécution de vérification, consultez le paramètre conclusion.

Dès que vous recevez le webhook check_suite, vous pouvez créer l’exécution de vérification, même si la vérification n’est pas terminée. Vous pouvez mettre à jour le status de l’exécution de vérification quand elle est en cours avec les valeurs queued, in_progress ou completed, et vous pouvez mettre à jour output lorsque plus de détails sont disponibles. Une exécution de vérification peut contenir des horodatages, un lien vers plus de détails sur votre site externe, des annotations détaillées concernant des lignes de code spécifiques ainsi que des informations sur l’analyse effectuée.

Annotation d’exécution de vérification

Une vérification peut également être réexécutée manuellement dans l’interface utilisateur GitHub. Pour plus d’informations, consultez « À propos des vérifications d’état ». Lorsque cela se produit, l’application GitHub qui a créé l’exécution de vérification reçoit le webhook check_run demandant une nouvelle exécution de vérification. Si vous créez une exécution de vérification sans créer de suite de vérifications, GitHub créera automatiquement la suite de vérifications.

L’autorisation d’écriture permettant à l’API REST d’interagir avec les vérifications n’est disponible que pour GitHub Apps. OAuth Apps et les utilisateurs authentifiés peuvent afficher les exécutions de vérification et les suites de vérifications, mais ils ne peuvent pas les créer. Si vous ne générez pas de GitHub App, l’utilisation de l’API REST pour interagir avec les états de validation peut vous intéresser.

Pour utiliser les points de terminaison afin de gérer les exécutions de vérifications, GitHub App doit avoir l’autorisation checks:write et peut également s’abonner au webhook check_run.

Vérifier les exécutions et les actions demandées

Lorsque vous configurez une exécution de vérification avec les actions demandées (à ne pas confondre avec GitHub Actions), vous pouvez afficher un bouton dans la vue de demande de tirage (pull request) sur GitHub pour permettre aux utilisateurs de demander à votre GitHub App d’effectuer des tâches supplémentaires.

Par exemple, une application de linting de code peut utiliser les actions demandées pour afficher un bouton dans une demande de tirage permettant de corriger automatiquement les erreurs de syntaxe détectées.

Pour créer un bouton permettant de demander des actions supplémentaires à partir de votre application, utilisez l’objet actions lorsque vous créez une exécution de vérification. Par exemple, l’objet actions ci-dessous affiche un bouton dans une demande de tirage avec l’étiquette « Fix this » (Corriger). Le bouton s’affiche une fois l’exécution de vérification terminée.

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

Bouton d’action demandée dans l’exécution de vérification

Lorsqu’un utilisateur clique sur le bouton, GitHub envoie le webhook check_run.requested_action à votre application. Lorsque votre application reçoit un événement de webhook check_run.requested_action, elle peut rechercher la clé requested_action.identifier dans la charge utile du webhook afin de déterminer le bouton sur lequel l’utilisateur a cliqué et d’effectuer la tâche demandée.

Pour obtenir un exemple détaillé de la configuration des actions demandées avec l’API REST, consultez « Création de tests CI avec l’API Checks ».

Rétention des données de vérification

Vérifie que les données datant de plus de 400 jours sont archivées. Dans le cadre du processus d’archivage GitHub crée un état de commit cumulatif représentant l’état de toutes les vérifications de ce commit. Par conséquent, la zone de fusion dans toute demande de tirage avec des vérifications archivées qui sont nécessaires sera dans un état bloqué, et vous devrez réexécuter les vérifications avant de pouvoir fusionner la demande de tirage.