Utilisation de l’API REST pour interagir avec votre base de données Git

Utilisez l’API REST pour lire et écrire des objets Git bruts dans votre base de données Git sur GitHub, et lister et mettre à jour vos références (têtes et étiquettes de branche).

Dans cet article

Vue d’ensemble

Cela vous permet en fait de réimplémenter un grand nombre de fonctionnalités Git avec l’API REST. En créant des objets bruts directement dans la base de données et en mettant à jour les références de branche, vous pouvez techniquement faire à peu près tout ce que Git peut faire sans avoir Git installé.

L’API REST retourne un 409 Conflict si le dépôt Git est vide ou indisponible. Un dépôt indisponible signifie généralement que GitHub est en train de créer le dépôt. Pour un référentiel vide, vous pouvez utiliser le point de terminaison d’API REST PUT /repos/{owner}/{repo}/contents/{path} pour créer du contenu et initialiser le référentiel afin de pouvoir utiliser l’API pour gérer la base de données Git. Contactez nous via le portail de support GitHub si cet état de réponse persiste.

Pour plus d’informations sur la base de données d’objets Git, lisez le chapitre Internes Git du livre Git Pro.

Par exemple, si vous souhaitez valider une modification dans un fichier de votre dépôt, vous devez :

  • Obtenir l’objet de validation actuel
  • Récupérer l’arborescence vers laquelle il pointe
  • Récupérer le contenu de l’objet blob que l’arborescence a pour ce chemin d’accès de fichier particulier
  • Modifier le contenu d’une manière ou d’une autre, envoyer un nouvel objet blob avec ce nouveau contenu, et obtenir un SHA de blob en retour
  • Publier un nouvel objet d’arborescence avec ce pointeur de chemin d’accès de fichier remplacé par votre nouveau SHA de blob, et obtenir un SHA d’arborescence en retour
  • Créer un objet de validation avec le SHA de validation actuel en tant que parent et le nouveau SHA d’arborescence, et récupérer un SHA de validation en retour
  • Mettre à jour la référence de votre branche pour qu’elle pointe vers le nouveau SHA de validation

Cela peut sembler complexe, mais c’est en fait assez simple lorsque vous comprenez le modèle et que celui-ci ouvre une tonne de choses que vous pourriez potentiellement faire avec l’API.

Vérification de la capacité de fusion des demandes de tirage

Warning

Évitez de dépendre de l’utilisation directe de Git, ou de GET /repos/{owner}/{repo}/git/refs/{ref} pour les mises à jour de références Git merge, car ce contenu devient obsolète sans avertissement.

Une API consommatrice doit effectuer explicitement une demande de tirage pour créer une validation de fusion test. Une validation de fusion test est créée lorsque vous affichez la demande de tirage dans l’interface utilisateur et que le bouton « Fusionner » s’affiche, ou lorsque vous obtenez, créez ou modifiez une demande de tirage à l’aide de l’API REST. Sans cette demande, les références Git merge deviendront obsolètes jusqu’au prochain affichage de la demande de tirage.

Si vous utilisez actuellement des méthodes d’interrogation qui produisent des références Git merge obsolètes, GitHub recommande d’utiliser les étapes suivantes pour obtenir les dernières modifications de la branche par défaut :

  1. Recevez le webhook de demande de tirage.
  2. Appelez GET /repos/{owner}/{repo}/pulls/{pull_number} pour démarrer un travail en arrière-plan afin de créer la validation de fusion candidate.
  3. Interrogez votre dépôt en utilisant GET /repos/{owner}/{repo}/pulls/{pull_number} pour voir si l’attribut mergeable est true ou false. Vous pouvez utiliser Git directement, ou GET /repos/{owner}/{repo}/git/refs/{ref} pour les mises à jour de références Git merge uniquement après avoir accompli les étapes précédentes.