À propos des paramètres d’URL pour inscrire 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 « Inscription d’une application GitHub à partir d’un manifeste ».
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 à :
http(s)://HOSTNAME/settings/apps/new - Pour inscrire une application sur un compte d’organisation, ajoutez des paramètres d’URL à :
http(s)://HOSTNAME/organizations/ORGANIZATION/settings/apps/new. RemplacezORGANIZATIONpar 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 name) 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 inscrit une application publique nommée octocat-github-app 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 checks, active les webhooks en utilisant le paramètre webhook_active, s’abonne aux événements de webhook check_run et check_suite, puis sélectionne l’option permettant de demander l’autorisation de l’utilisateur (OAuth) durant l’installation :
http(s)://HOSTNAME/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 name=octocat-github-app.
| Nom du paramètre | Type | 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 avec slug du nom de votre application s’affiche dans l’interface utilisateur quand 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 : callback_urls[]=https://example.com&callback_urls[]=https://example-2.com. Pour plus d’informations, consultez « À propos de l’URL de rappel d’autorisation utilisateur ». |
request_oauth_on_install | boolean | Si votre application autorise les utilisateurs à l’aide du flux OAuth, vous pouvez affecter la valeur true à 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, setup_url cesse d’être disponible, et les utilisateurs sont redirigés vers votre callback_url 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 « À propos de l’URL d’installation ». |
setup_on_update | boolean | Affectez-lui la valeur true 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 true quand votre GitHub App est accessible au public, ou la valeur false quand 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 | Affectez la valeur true pour activer le webhook. Le webhook est désactivé par défaut. |
webhook_url | string | 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 read ou write 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 : events[]=public&events[]=label. |
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 single_file la valeur read ou write, ce champ fournit le chemin du fichier unique que votre GitHub App va gérer. Si vous devez gérer plusieurs fichiers, consultez single_file_paths 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 single_file la valeur read ou write, 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 single_file. Ils n’ont pas d’autorisations individuelles distinctes. Quand deux fichiers ou plus sont configurés, l’API retourne multiple_single_files=true, sinon elle retourne multiple_single_files=false. |
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 contents, votre chaîne de requête devra inclure contents=write. Pour sélectionner les autorisations « Lecture seule » dans l’interface utilisateur pour blocking, votre chaîne de requête devra inclure blocking=read. Pour sélectionner « Aucun accès » dans l’interface utilisateur pour checks, votre chaîne de requête ne devra pas inclure l’autorisation checks.
Pour plus d’informations sur les autorisations et les GitHub Apps, consultez « Choix des autorisations pour une application GitHub ».
Événements de webhook de l’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 webhook_active=true dans votre chaîne de requête. Pour désigner une URL complète à laquelle vous souhaitez envoyer des charges utiles d’événement de webhook, utilisez webhook_url dans votre chaîne de requête. Pour abonner l’application à des événements de charge utile de webhook spécifiques, utilisez events[] 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 « Événements et charges utiles du webhook ».
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 &webhook_active=true&webhook_url=https://example.com&events[]=commit_comment. Notez que l’événement de webhook commit_comment 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 contents sur read ou write. 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 les GitHub Apps, consultez « Utilisation de webhooks avec des applications GitHub ».