À propos des paramètres d'URL pour enregistrer des GitHub Apps
Vous pouvez utiliser les paramètres d’URL pour présélectionner les paramètres de configuration d’une nouvelle inscription d’GitHub App et partager un lien personnalisé avec d’autres personnes. Le lien les renvoie à une page d’inscription d’GitHub App, où les paramètres d’application sont préremplis en fonction des paramètres d’URL que vous avez inclus dans l’URL.
Cette approche est utile pour les intégrateurs qui souhaitent que les clients configurent une application sur leur compte personnel ou leur organisation avec certaines spécifications, ou pour les clients utilisant GitHub Enterprise Server qui ne peuvent pas installer d’applications à partir de GitHub Marketplace.
Vous pouvez également créer un manifeste d’GitHub App. Pour plus d’informations, consultez « AUTOTITLE ».
Création d’une URL de configuration personnalisée avec des paramètres de requête
Pour créer une URL de configuration personnalisée pour une GitHub App sur un compte personnel ou d’organisation, ajoutez des paramètres de requête après les URL de base suivantes.
- Pour inscrire une application sur un compte personnel, ajoutez des paramètres d’URL à :
- Pour inscrire une application sur un compte d’organisation, ajoutez des paramètres d’URL à : . Remplacez par le nom de l’organisation dans laquelle vous souhaitez que le client inscrive l’application.
Dans la page d’inscription d’application, la personne qui inscrit l’application peut modifier les valeurs présélectionnées avant d’envoyer l’application. Si vous n’incluez pas les paramètres pour les valeurs obligatoires (comme ) dans la chaîne de requête de l’URL, la personne qui inscrit l’application devra entrer les valeurs avant d’inscrire l’application.
Par exemple, l'URL suivante enregistre une application publique nommée sur un compte personnel. Avec les paramètres de requête, l’URL préconfigure une description et une URL de rappel. Elle sélectionne également les autorisations d’accès en lecture et en écriture pour , active les webhooks en utilisant le paramètre , s’abonne aux événements de webhook et , puis sélectionne l’option permettant de demander l’autorisation de l’utilisateur (OAuth) durant l’installation :
https://github.com/settings/apps/new?name=octocat-github-app&description=An%20Octocat%20App&callback_urls[]=https://example.com&request_oauth_on_install=true&public=true&checks=write&webhook_active=true&events[]=check_run&events[]=check_suite
Paramètres de configuration de l’GitHub App
Vous pouvez utiliser les paramètres de requête suivants afin de sélectionner une configuration spécifique pour l’inscription d’GitHub App. Par exemple, pour appeler l’application « octocat-github-app », votre chaîne de requête devra inclure .
| Nom du paramètre | Type de données | Description |
|---|---|---|
name | string | Nom de l’GitHub App. Donnez un nom clair et succinct à votre application. Votre application ne peut pas avoir le même nom qu’un utilisateur GitHub, sauf si le nom est votre propre nom d’utilisateur ou le nom de votre organisation. Une version simplifiée du nom de votre application s'affiche dans l'interface utilisateur lorsque votre intégration effectue une action. |
description | string | Description de l’GitHub App. |
url | string | URL complète de la page d’accueil du site web de votre GitHub App. |
callback_urls | array of strings | URL complète de redirection, une fois qu’une personne a autorisé une installation. Vous pouvez fournir jusqu’à 10 URL de rappel. Ces URL sont utilisées si votre application doit générer un jeton d’accès utilisateur. Par exemple : . Pour plus d’informations, consultez « AUTOTITLE ». |
request_oauth_on_install | boolean | Si votre application autorise les utilisateurs à l’aide du flux OAuth, vous pouvez affecter la valeur à cette option pour permettre aux utilisateurs d’autoriser l’application quand ils l’installent, et ainsi de sauter une étape. Si vous sélectionnez cette option, [l'élément spécifique] cesse d’être disponible, et les utilisateurs seront redirigés vers votre [élément spécifique] après l’installation de l’application. |
setup_url | string | URL complète de redirection une fois qu’une personne a installé l’GitHub App, si l’application nécessite une configuration supplémentaire après l’installation. Pour plus d’informations, consultez « AUTOTITLE ». |
setup_on_update | boolean | Affectez-lui la valeur pour rediriger les utilisateurs vers l’URL de configuration quand les installations ont été mises à jour, par exemple après l’ajout ou la suppression de dépôts. |
public | boolean | Affectez-lui la valeur appropriée lorsque votre GitHub App est disponible au public, ou la valeur appropriée lorsqu'elle est uniquement accessible au propriétaire de l'application. Ce paramètre ne s’applique pas aux applications détenues par les entreprises. |
webhook_active | boolean | Configurez la valeur pour activer le webhook. Le webhook est désactivé par défaut. |
webhook_url | string | Adresse URL complète à laquelle vous souhaitez envoyer les charges utiles des événements de webhook. |
events | array of strings | Événements de webhook. Certains événements de webhook nécessitent des autorisations ou des permissions sur une ressource pour que vous puissiez sélectionner l’événement au moment de l’inscription d’une nouvelle GitHub App. Pour plus d’informations, consultez la section « Événements de webhook de l’GitHub App ». Vous pouvez sélectionner plusieurs événements dans une chaîne de requête. Par exemple : . |
single_file_name | string | Il s’agit d’une autorisation à étendue limitée, qui permet à l’application d’accéder à un seul fichier dans n’importe quel dépôt. Quand vous affectez à l’autorisation la valeur ou , ce champ fournit le chemin du fichier unique que votre GitHub App va gérer. Si vous devez gérer plusieurs fichiers, consultez ci-dessous. |
single_file_paths | array of strings | Cela permet à l’application d’accéder au maximum à dix fichiers spécifiques dans un dépôt. Quand vous affectez à l’autorisation la valeur ou , ce tableau peut stocker les chemins de dix fichiers au maximum que votre GitHub App va gérer. Ces fichiers reçoivent tous la même autorisation définie par . Ils n’ont pas d’autorisations individuelles distinctes. Quand deux fichiers ou plus sont configurés, l’API retourne , sinon elle retourne . |
Autorisations de l’GitHub App
Vous pouvez utiliser des paramètres de requête pour sélectionner les autorisations pour l’inscription d’GitHub App. Pour le paramètre de requête d’URL, utilisez le nom d’autorisation comme nom de paramètre de requête et définissez la valeur de la requête sur l’une des valeurs possibles pour ce jeu d’autorisations.
Par exemple, pour sélectionner les autorisations « Lecture et écriture » dans l’interface utilisateur pour , votre chaîne de requête devra inclure . Pour sélectionner les autorisations « Lecture seule » dans l’interface utilisateur pour , votre chaîne de requête devra inclure . Pour sélectionner « Aucun accès » dans l’interface utilisateur pour , votre chaîne de requête ne devra pas inclure l’autorisation .
Pour plus d’informations sur les autorisations et les GitHub Apps, consultez « AUTOTITLE ». Pour consulter la liste des autorisations disponibles et leurs noms paramétrés, consultez AUTOTITLE.
Événements de webhook GitHub App
Vous pouvez utiliser des paramètres de requête pour activer le webhook de l’GitHub App, désigner une URL de webhook et s’abonner à l’application pour recevoir des charges utiles de webhook pour des événements spécifiques.
Pour activer le webhook de l’GitHub App, utilisez-le dans votre chaîne de requête. Pour désigner une URL complète à laquelle vous souhaitez envoyer les charges utiles des événements de webhook, utilisez le paramètre spécifique dans votre chaîne de requête. Pour abonner l’application à des événements de charge utile de webhook spécifiques, utilisez comme nom de paramètre de requête et définissez la valeur de la requête avec le nom de l’événement de webhook. Pour plus d’informations sur les événements de webhook possibles et les autorisations d’GitHub App requises pour s’abonner à chaque événement, consultez « AUTOTITLE ».
Par exemple, pour s’abonner à une GitHub App afin de recevoir des charges utiles de webhook pour l’activité relative aux commentaires de commit, la chaîne de requête devra inclure . Notez que l’événement de webhook demande que l’GitHub App dispose au moins d’un accès de niveau lecture pour l’autorisation de dépôt « Contenu ». Par conséquent, votre chaîne de requête doit également inclure un paramètre pour définir l’autorisation à ou . Pour plus d’informations, consultez « Autorisations des applications GitHub ».
Vous ne pouvez pas utiliser les paramètres de requête pour définir la valeur d’un secret de webhook. Si une application exige un secret pour sécuriser son webhook, la valeur du secret doit être définie dans l’interface utilisateur de GitHub par la personne qui inscrit l’application.
Pour plus d’informations sur les "webhooks" et GitHub Apps, consultez AUTOTITLE.