À propos des paramètres d’URL de l’GitHub App
Vous pouvez ajouter des paramètres de requête à ces URL pour présélectionner la configuration d’une GitHub App dans un compte personnel ou d’organisation :
- Compte personnel :
http(s)://HOSTNAME/settings/apps/new - Compte d’organisation :
http(s)://HOSTNAME/organizations/:org/settings/apps/new
La personne qui crée l’application peut modifier les valeurs présélectionnées à partir de la page d’inscription de l’GitHub App avant de l’envoyer. Si vous n’incluez pas les paramètres obligatoires dans la chaîne de requête de l’URL, par exemple name, la personne qui crée l’application devra entrer une valeur avant de l’envoyer.
Dans le cas des applications qui nécessitent un secret pour sécuriser leur webhook, la valeur du secret doit être définie dans le formulaire par la personne qui crée l’application, et non à l’aide des paramètres de requête. Pour plus d’informations, consultez « Sécurisation de vos webhooks ».
L’URL suivante crée une application publique appelée octocat-github-app avec une URL de rappel et une description préconfigurées. Cette URL sélectionne également les autorisations d’accès en lecture et en écriture pour checks, 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&events[]=check_run&events[]=check_suite
La liste complète des paramètres de requête, des autorisations et des événements disponibles est listée dans les sections ci-dessous.
Paramètres de configuration de l’GitHub App
| Nom | 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 existant, sauf s’il s’agit de votre propre nom d’utilisateur ou d’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. |
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. |
webhook_active | boolean | Affectez-lui la valeur false pour désactiver le webhook. Le webhook est activé par défaut. |
webhook_url | string | URL complète à laquelle vous souhaitez envoyer les charges utiles des événements de webhook. |
webhook_secret | string | Vous pouvez spécifier un secret pour sécuriser vos webhooks. Pour plus d’informations, consultez « Sécurisation de vos webhooks ». |
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 connaître les événements disponibles et les autorisations nécessaires, 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. |
Autorisations de l’GitHub App
Vous pouvez sélectionner des autorisations dans une chaîne de requête en utilisant le nom d’autorisation figurant dans le tableau suivant en tant que nom de paramètre de requête, et le type d’autorisation en tant que valeur de requête. Par exemple, pour sélectionner les autorisations Read & write dans l’interface utilisateur pour contents, votre chaîne de requête doit inclure &contents=write. Pour sélectionner les autorisations Read-only dans l’interface utilisateur pour blocking, votre chaîne de requête doit inclure &blocking=read. Si vous souhaitez sélectionner no-access dans l’interface utilisateur pour checks, votre chaîne de requête ne doit pas inclure l’autorisation checks.
| Autorisation | Description |
|---|---|
administration | Octroie l’accès à différents points de terminaison pour l’administration de l’organisation et du dépôt. Il peut s’agir de l’une des valeurs suivantes : none, read ou write. |
checks | Octroie l’accès à l’API des vérifications. Il peut s’agir de l’une des valeurs suivantes : none, read ou write. |
contents | Octroie l’accès à divers points de terminaison qui vous permettent de modifier le contenu du dépôt. Il peut s’agir de l’une des valeurs suivantes : none, read ou write. |
deployments | Octroie l’accès à l’API des déploiement. Il peut s’agir de l’une des valeurs suivantes : none, read ou write. |
followers | Octroie l’accès à l’API des abonné. Il peut s’agir de l’une des valeurs suivantes : none, read ou write. |
gpg_keys | Octroie l’accès à l’API des clés GPG. Il peut s’agir de l’une des valeurs suivantes : none, read ou write. |
issues | Octroie l’accès à l’API des problèmes. Il peut s’agir de l’une des valeurs suivantes : none, read ou write. |
keys | Octroie l’accès à l’API des clés publiques. Il peut s’agir de l’une des valeurs suivantes : none, read ou write. |
members | Octroie l’accès à la gestion des membres d’une organisation. Il peut s’agir de l’une des valeurs suivantes : none, read ou write. |
organization_hooks | Octroie l’accès à l’API des webhooks d’organisation. Il peut s’agir de l’une des valeurs suivantes : none, read ou write. |
organization_plan | Octroie l’accès à l’obtention d’informations sur le plan d’une organisation à l’aide du point de terminaison « Organisations ». Il peut s’agir de l’une des valeurs suivantes : none ou read. |
organization_projects | Octroie l’accès à l’API des projets. Il peut s’agir de l’une des valeurs suivantes : none, read, write ou admin. |
pages | Octroie l’accès à l’API de GitHub Pages. Il peut s’agir de l’une des valeurs suivantes : none, read ou write. |
plan | Octroie l’accès à l’obtention d’informations sur le plan GitHub d’un utilisateur à l’aide du point de terminaison « Utilisateurs ». Il peut s’agir de l’une des valeurs suivantes : none ou read. |
pull_requests | Octroie l’accès à divers points de terminaison de demande de tirage. Il peut s’agir de l’une des valeurs suivantes : none, read ou write. |
repository_hooks | Octroie l’accès à l’API des webhooks de dépôt. Il peut s’agir de l’une des valeurs suivantes : none, read ou write. |
repository_projects | Octroie l’accès à l’API des projets. Il peut s’agir de l’une des valeurs suivantes : none, read, write ou admin. |
single_file | Octroie l’accès à l’API de contenu. Il peut s’agir de l’une des valeurs suivantes : none, read ou write. |
starring | Octroie l’accès à l’API d’attribution d’étoiles. Il peut s’agir de l’une des valeurs suivantes : none, read ou write. |
statuses | Octroie l’accès à l’API des états. Il peut s’agir de l’une des valeurs suivantes : none, read ou write. |
team_discussions | Octroie l’accès à l’API des discussions d’équipe et à l’API des commentaires de discussion d’équipe. Peut avoir l’une des valeurs suivantes : none, read ou write. |
vulnerability_alerts | Octroie l’accès à la réception d’Dependabot alerts dans un référentiel. Pour en savoir plus, consultez À propos des alertes Dependabot. Peut avoir l’une des valeurs suivantes : none, read ou write. |
watching | Octroie l’accès permettant de lister et de changer les dépôts auxquels un utilisateur est abonné. Il peut s’agir de l’une des valeurs suivantes : none, read ou write. |
Événements de webhook de l’GitHub App
| Nom de l’événement de webhook | Autorisation requise | Description |
|---|---|---|
check_run | checks | L’activité de suite d’exécutions a eu lieu. Le type d’activité est spécifié dans la propriété action de l’objet de charge utile. Pour plus d’informations, consultez l’API REST « Vérifications ». |
check_suite | checks | L’activité de suite de vérifications a eu lieu. Le type d’activité est spécifié dans la propriété action de l’objet de charge utile. Pour plus d’informations, consultez l’API REST « Vérifications ». |
commit_comment | contents | Un commentaire de commit est créé. Le type d’activité est spécifié dans la propriété action de l’objet de charge utile. Pour plus d’informations, consultez l’API REST « Commentaires de commit ». |
create | contents | Une branche ou une étiquette Git est créée. Pour plus d’informations, consultez l’API REST « Base de données Git ». |
delete | contents | Une branche ou une étiquette Git est supprimée. Pour plus d’informations, consultez l’API REST « Base de données Git ». |
deployment | deployments | Un déploiement est créé. Le type d’activité est spécifié dans la propriété action de l’objet de charge utile. Pour plus d’informations, consultez l’API REST « Déploiements ». |
deployment_status | deployments | Un déploiement est créé. Le type d’activité est spécifié dans la propriété action de l’objet de charge utile. Pour plus d’informations, consultez l’API REST « Déploiements ». |
fork | contents | Un utilisateur duplique un dépôt. Pour plus d’informations, consultez l’API REST « Référentiels ». |
gollum | contents | Une page wiki est créée ou mise à jour. Pour plus d’informations, consultez « À propos des wikis ». |
issues | issues | Activité liée à un problème. Le type d’activité est spécifié dans la propriété action de l’objet de charge utile. Pour plus d’informations, consultez l’API REST « Problèmes ». |
issue_comment | issues | Activité liée à un problème ou à un commentaire de demande de tirage. Le type d’activité est spécifié dans la propriété action de l’objet de charge utile. Pour plus d’informations, consultez l’API REST « Problèmes ». |
label | metadata | Activité liée à une étiquette. Le type d’activité est spécifié dans la propriété action de l’objet de charge utile. Pour plus d’informations, consultez l’API REST « Problèmes ». |
member | members | Activité liée aux collaborateurs du référentiel. Le type d’activité est spécifié dans la propriété action de l’objet de charge utile. Pour plus d’informations, consultez l’API REST « Référentiels ». |
membership | members | Activité liée à l’appartenance à une équipe. Le type d’activité est spécifié dans la propriété action de l’objet de charge utile. Pour plus d’informations, consultez l’API REST « Teams ». |
milestone | pull_request | Activité liée aux jalons. Le type d’activité est spécifié dans la propriété action de l’objet de charge utile. Pour plus d’informations, consultez l’API REST « Problèmes ». |
organization | members | Activité liée à une organisation et à ses membres. Le type d’activité est spécifié dans la propriété action de l’objet de charge utile. Pour plus d’informations, consultez l’API REST « Organisations ». |
page_build | pages | Représente une tentative de génération d’un site GitHub Pages, qu’elle réussisse ou non. Une poussée sur une branche activée pour GitHub Pages (gh-pages pour les pages de projet, la branche par défaut pour les pages d’utilisateur et d’organisation) déclenche cet événement. |
project | repository_projects ou organization_projects | Activité liée aux tableaux de projets. Le type d’activité est spécifié dans la propriété action de l’objet de charge utile. Pour plus d’informations, consultez l’API REST « Project boards ». |
project_card | repository_projects ou organization_projects | Activité liée aux cartes dans un tableau de projet. Le type d’activité est spécifié dans la propriété action de l’objet de charge utile. Pour plus d’informations, consultez l’API REST « Project boards ». |
project_column | repository_projects ou organization_projects | Activité liée aux colonnes dans un tableau de projet. Le type d’activité est spécifié dans la propriété action de l’objet de charge utile. Pour plus d’informations, consultez l’API REST « project columns ». |
public | metadata | Quand un dépôt privé est rendu public. Sans aucun doute : le meilleur événement GitHub AE. |
pull_request | pull_requests | Activité liée aux demandes de tirage. Le type d’activité est spécifié dans la propriété action de l’objet de charge utile. Pour plus d’informations, consultez l’API REST « Tirages ». |
pull_request_review | pull_request | Activité liée aux révisions de demande de tirage. Le type d’activité est spécifié dans la propriété action de l’objet de charge utile. Pour plus d’informations, consultez l’API REST « Tirages ». |
pull_request_review_comment | pull_request | Activité liée aux commentaires de révision des demandes de tirage dans la différence unifiée de la demande de tirage. Le type d’activité est spécifié dans la propriété action de l’objet de charge utile. Pour plus d’informations, consultez l’API REST « Tirages ». |
pull_request_review_thread | pull_request | Activité liée à un thread de commentaire sur une demande de tirage marquée comme résolue ou non résolue. Le type d’activité est spécifié dans la propriété action de l’objet de charge utile. |
push | contents | Un ou plusieurs commits sont poussés sur une branche ou une étiquette de dépôt. |
release | contents | Activité liée à une version. Le type d’activité est spécifié dans la propriété action de l’objet de charge utile. Pour plus d’informations, consultez l’API REST « Publications ». |
repository | metadata | Activité liée à un dépôt. Le type d’activité est spécifié dans la propriété action de l’objet de charge utile. Pour plus d’informations, consultez l’API REST « Référentiels ». |
status | statuses | Lorsque l’état d’un commit Git change. Pour plus d’informations, consultez l’API REST « À propos des états de validation ». |
team | members | Activité liée à l’équipe d’une organisation. Le type d’activité est spécifié dans la propriété action de l’objet de charge utile. Pour plus d’informations, consultez l’API REST « Teams ». |
team_add | members | Quand un dépôt est ajouté à une équipe. |
watch | metadata | Quand une personne met une étoile à un dépôt. Le type d’activité est spécifié dans la propriété action de l’objet de charge utile. Pour plus d’informations, consultez l’API REST « starring ». |