Inscription d’une application GitHub à l’aide de paramètres d’URL

À propos des paramètres d’URL pour l’inscription GitHub Apps

Vous pouvez utiliser des paramètres d’URL pour préélectionner les paramètres de configuration d’une nouvelle GitHub App inscription et partager un lien personnalisé avec d’autres personnes. Le lien amène les personnes à une GitHub App page d’inscription, où les paramètres de l’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 qui utilisent GitHub Enterprise Server qui ne peuvent pas installer d’applications à partir du GitHub Marketplace.

Vous pouvez également créer un GitHub App manifeste. 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 un GitHub App 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. Remplacez ORGANIZATION par le nom de l’organisation dans laquelle vous souhaitez que le client inscrive l’application.
Pour inscrire une application sur un compte d’entreprise, ajoutez des paramètres d’URL à : http(s)://HOSTNAME/enterprises/ENTERPRISE/settings/apps/new. Remplacez ENTERPRISE par le nom de l’entreprise 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

GitHub App paramètres de configuration

Vous pouvez utiliser les paramètres de requête suivants pour sélectionner une configuration spécifique pour l’inscription 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 du GitHub App. Donnez un nom clair et succinct à votre application. Votre application ne peut pas avoir le même nom qu’un utilisateur existant GitHub , sauf s’il s’agit de votre propre utilisateur ou nom d’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 du GitHub App.
`url`	`string`	URL complète de la page d’accueil de votre GitHub Appsite web.
`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 après qu’un utilisateur a installé 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`	Définissez à `true` lorsque votre GitHub App est disponible pour le public ou à `false` lorsqu'elle n'est accessible qu'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 webhook nécessitent des autorisations `read` ou `write` pour une ressource avant que vous puissiez sélectionner l’événement lors de l’enregistrement d’un nouveau GitHub App. Pour plus d’informations, consultez la GitHub App section événements de webhook . 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. Lorsque vous définissez l’autorisation `single_file` sur `read` ou `write`, ce champ fournit le chemin d’accès au fichier unique que vous GitHub App gérez. 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. Lorsque vous définissez l’autorisation `single_file` sur `read` ou `write`, ce tableau peut stocker les chemins d’accès d’un maximum de dix fichiers que vous GitHub App gérerez. 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`.

GitHub App Autorisations

Vous pouvez utiliser les paramètres de requête pour sélectionner les autorisations pour l’inscription 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 n’inclurait pas l’autorisation checks.

Pour plus d’informations sur les autorisations et GitHub Apps, consultez Choix des autorisations pour une application GitHub. Pour consulter la liste des autorisations disponibles et leurs noms paramétrés, consultez Gestion de vos jetons d’accès personnels.

GitHub App Événements webhook

Vous pouvez utiliser des paramètres de requête pour activer le GitHub App webhook, désigner une URL de webhook et abonner l’application pour recevoir des charges utiles de webhook pour des événements spécifiques.

Pour activer le GitHub App webhook, utilisez-le 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 webhook possibles et les GitHub App autorisations requises pour s’abonner à chaque événement, consultez Événements et charges utiles du webhook.

Par exemple, pour abonner un GitHub App afin de recevoir les charges utiles de webhook pour l’activité liée aux commentaires de commit, la chaîne de requête inclurait &webhook_active=true&webhook_url=https://example.com&events[]=commit_comment. Notez que l’événement de webhook commit_comment nécessite que GitHub App dispose d’un accès au minimum en lecture pour la permission de dépôt « Contents ». 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 GitHub autorisations d’application.

Vous ne pouvez pas utiliser les paramètres de requête pour définir la valeur d’un secret de webhook. Si une application nécessite un secret pour sécuriser son webhook, la valeur de ce secret doit être définie dans l’interface utilisateur GitHub par la personne qui enregistre l’application.

Pour plus d’informations sur les webhooks et GitHub Apps, consultez Utilisation de webhooks avec GitHub Apps.