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

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 « Génération de vérifications CI avec un application GitHub ».

Vous pouvez utiliser des statuts avec des branches protégées pour empêcher les gens de fusionner prématurément des demandes d’extraction. Pour plus d’informations, consultez « À propos des branches protégées ».

À 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.

Le status peut être queued, in_progress, requested, waiting, pending ou completed. Seules les GitHub Actions peuvent définir l’état requested, waiting ou pending.

Si l’état est completed, la conclusion peut être l’une des suivantes :

• action_required
• cancelled
• timed_out
• failure
• neutral
• skipped
• stale
• startup_failure
• success

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 « À propos de l’authentification avec une application 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.

Le status peut être queued, in_progress, requested, waiting, pending ou completed. Seules les GitHub Actions peuvent définir l’état requested, waiting ou pending.

Si l’état est completed, la conclusion peut être l’une des suivantes :

• action_required
• cancelled
• timed_out
• failure
• neutral
• skipped
• success

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.

Les annotations ajoutent des informations de votre exécution de vérification à des lignes de code spécifiques. Chaque annotation inclut une propriété annotation_level, qui peut être notice, warning ou failure. L’annotation inclut également path, start_line et end_line pour spécifier l’emplacement auquel l’annotation fait référence. L’annotation inclut un message pour décrire le résultat. Pour plus d’informations, consultez « Points de terminaison d’API REST pour les exécutions de vérifications ».

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 l’onglet Vérifications 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"
}]

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 « Génération de vérifications CI avec un application GitHub ».

Rétention des données de vérification

Les administrateurs de site peuvent contrôler la stratégie de conservation pour les données de vérification sur votre instance GitHub Enterprise Server. Pour plus d’informations, consultez « Configuration d'applications ».

Pour les données de vérification archivées, un état de validation cumulatif s’affiche et représente l’état de toutes les vérifications de la validation. Pour fusionner une demande de tirage avec des vérifications à la fois obligatoires et archivées, vous devez réexécuter les vérifications.