Inscription d’une application GitHub à partir d’un manifeste

À propos des manifestes GitHub App

Quand une personne inscrit une GitHub App à partir d’un manifeste, il lui suffit de suivre une URL et de nommer l’application. Le manifeste inclut les autorisations, les événements et l’URL de webhook nécessaires pour inscrire automatiquement l’application. Le flux de manifeste crée l’inscription d’GitHub App, puis génère le secret du webhook, la clé privée (fichier PEM), le secret client ainsi que l’ID d’GitHub App. La personne qui crée l’inscription d’GitHub App à partir du manifeste sera propriétaire de l’inscription d’GitHub App et pourra choisir de modifier les paramètres de l’inscription, de la supprimer ou de la transférer à une autre personne sur GitHub.

Vous pouvez utiliser Probot pour bien démarrer avec les manifestes d’GitHub App ou pour voir un exemple d’implémentation. Pour en savoir plus, consultez « Utilisation de Probot pour implémenter le flux de manifeste de l’GitHub App ».

Voici quelques scénarios où vous pouvez utiliser les manifestes d’GitHub App pour inscrire des applications préconfigurées :

Aider les nouveaux membres de l’équipe à être rapidement opérationnels quand ils développent des GitHub Apps.
Autoriser d’autres utilisateurs à étendre une GitHub App à l’aide des API GitHub sans exiger qu’ils configurent une application.
Créez des conceptions de référence d’GitHub App à partager avec la communauté GitHub.
Assurez-vous de déployer les GitHub Apps sur des environnements de développement et de production à l’aide de la même configuration.
Effectuer le suivi des révisions d’une configuration d’GitHub App.

Implémentation du flux de manifeste d’GitHub App

Le flux de manifeste de l’GitHub App utilise un processus d’établissement de liaison similaire au flux OAuth. Le flux utilise un manifeste pour inscrire une GitHub App et reçoit un code temporaire permettant de récupérer la clé privée, le secret de webhook et l’ID.

Note

Vous devez effectuer les trois étapes du flux de manifeste de l’GitHub App en moins d’une heure.

Suivez ces étapes pour implémenter le flux de manifeste de l’GitHub App :

Vous redirigez les personnes vers GitHub pour inscrire une nouvelle GitHub App.
GitHub redirige les personnes vers votre site.
Vous échangez le code temporaire pour récupérer la configuration de l’application.

Vous redirigez les personnes vers GitHub pour inscrire une nouvelle GitHub App

Pour rediriger les utilisateurs vers l’inscription d’une nouvelle GitHub App, fournissez un lien sur lequel ils peuvent cliquer afin d’envoyer une requête POST à https://github.com/settings/apps/new pour un compte personnel, ou à https://github.com/organizations/ORGANIZATION/settings/apps/new pour un compte d’organisation, en remplaçant ORGANIZATION par le nom du compte d’organisation où l’application sera inscrite.

Vous devez inclure les paramètres du manifeste de l’GitHub App sous forme de chaîne codée au format JSON dans un paramètre appelé manifest. Vous pouvez également inclure un paramètre state pour plus de sécurité.

La personne qui inscrit l’application est redirigée vers une page GitHub comportant un champ d’entrée où elle peut modifier le nom de l’application que vous avez incluse dans le paramètre manifest. Si vous n’incluez pas name dans manifest, elle peut définir le nom de son choix pour l’application dans ce champ.

Paramètres de manifeste de l’GitHub App

Nom	Type	Description
`name`	`string`	Nom de l’GitHub App.
`url`	`string`	Obligatoire. Page d’accueil de votre GitHub App.
`hook_attributes`	`object`	Configuration du webhook de l’GitHub App.
`redirect_url`	`string`	URL complète de redirection, une fois qu’un utilisateur a lancé l’inscription d’une GitHub App à partir d’un manifeste.
`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.
`setup_url`	`string`	URL complète permettant de rediriger les utilisateurs après l’installation de votre GitHub App si une configuration supplémentaire est nécessaire.
`description`	`string`	Description de l’GitHub App.
`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.
`default_events`	`array`	Liste des événements auxquels l’GitHub App est abonnée.
`default_permissions`	`object`	L’ensemble d’autorisations nécessaires pour l’GitHub App. Le format de l’objet utilise le nom d’autorisation de la clé (par exemple `issues`) et le type d’accès de la valeur (par exemple `write`). Pour plus d’informations, consultez « Choix des autorisations pour une application GitHub ».
`request_oauth_on_install`	`boolean`	Définissez sur `true` pour demander à l’utilisateur d’autoriser l’GitHub App une fois l’GitHub App installée.
`setup_on_update`	`boolean`	Définissez sur `true` pour rediriger les utilisateurs vers `setup_url` après la mise à jour de l’installation de votre GitHub App.

L’objet hook_attributes a les clés suivantes.

Nom	Type	Description
`url`	`string`	Obligatoire. URL du serveur qui va recevoir les requêtes `POST` du webhook.
`active`	`boolean`	Fournit les détails de l’événement quand ce crochet se déclenche. La valeur par défaut est true.

Paramètres

Nom	Type	Description
`state`	`string`	Chaîne aléatoire non modifiable. Elle est utilisée pour protéger contre les attaques de falsification de requête intersite.

Exemples

Cet exemple utilise un formulaire sur une page web avec un bouton qui déclenche la requête POST pour un compte personnel :

<form action="https://github.com/settings/apps/new?state=abc123" method="post">
 Register a GitHub App Manifest: <input type="text" name="manifest" id="manifest"><br>
 <input type="submit" value="Submit">
</form>

<script>
 input = document.getElementById("manifest")
 input.value = JSON.stringify({
   "name": "Octoapp",
   "url": "https://www.example.com",
   "hook_attributes": {
     "url": "https://example.com/github/events",
   },
   "redirect_url": "https://example.com/redirect",
   "callback_urls": [
     "https://example.com/callback"
   ],
   "public": true,
   "default_permissions": {
     "issues": "write",
     "checks": "write"
   },
   "default_events": [
     "issues",
     "issue_comment",
     "check_suite",
     "check_run"
   ]
 })
</script>

Cet exemple utilise un formulaire sur une page web avec un bouton qui déclenche la requête POST pour un compte d’organisation. Remplacez ORGANIZATION par le nom du compte d’organisation dans lequel vous souhaitez inscrire l’application.

<form action="https://github.com/organizations/ORGANIZATION/settings/apps/new?state=abc123" method="post">
 register a GitHub App Manifest: <input type="text" name="manifest" id="manifest"><br>
 <input type="submit" value="Submit">
</form>

<script>
 input = document.getElementById("manifest")
 input.value = JSON.stringify({
   "name": "Octoapp",
   "url": "https://www.example.com",
   "hook_attributes": {
     "url": "https://example.com/github/events",
   },
   "redirect_url": "https://example.com/redirect",
   "callback_urls": [
     "https://example.com/callback"
   ],
   "public": true,
   "default_permissions": {
     "issues": "write",
     "checks": "write"
   },
   "default_events": [
     "issues",
     "issue_comment",
     "check_suite",
     "check_run"
   ]
 })
</script>

2. GitHub redirige les personnes vers votre site

Lorsque la personne clique sur Créer une GitHub App, GitHub redirige vers l’instance redirect_url avec un code temporaire dans un paramètre de code. Par exemple :

https://example.com/redirect?code=a180b1a3d263c81bc6441d7b990bae27d4c10679

Si vous avez fourni un paramètre state, vous voyez également ce paramètre dans redirect_url. Par exemple :

https://example.com/redirect?code=a180b1a3d263c81bc6441d7b990bae27d4c10679&state=abc123

3. Vous échangez le code temporaire pour récupérer la configuration de l’application

Pour permettre l’établissement d’une liaison, envoyez le code temporaire dans une requête POST au point de terminaison Créer une GitHub App à partir d’un manifeste. La réponse inclut id (ID GitHub App), pem (clé privée) et webhook_secret. GitHub crée automatiquement un secret webhook pour l’application. Vous pouvez stocker ces valeurs dans des variables d’environnement sur le serveur de l’application. Par exemple, si votre application utilise dotenv pour stocker les variables d’environnement, vous devez stocker les variables dans le fichier .env de votre application.

Vous devez effectuer cette étape du flux de manifeste de l’GitHub App en moins d’une heure.

Note

Ce point de terminaison est à débit limité. Consultez Limites de débit pour savoir comment obtenir l’état de votre limite de débit actuelle.

POST /app-manifests/{code}/conversions

Pour plus d’informations sur la réponse du point de terminaison, consultez Créer une GitHub App à partir d’un manifeste.

Une fois la dernière étape du flux de manifeste effectuée, la personne qui inscrit l’application à partir du flux est propriétaire d’une GitHub App inscrite qu’elle peut installer dans l’un de ses dépôts personnels. Elle peut étendre l’application en utilisant les API GitHub, transférer sa propriété à une autre personne, ou la supprimer à tout moment.

Utilisation de Probot pour implémenter le flux de manifeste de l’GitHub App

Probot est un framework créé avec Node.js. Il effectue la plupart des tâches nécessaires à l’ensemble des GitHub Apps, par exemple la validation des webhooks et l’authentification. Probot implémente le flux de manifeste GitHub App, ce qui facilite la création et le partage des conceptions de référence d’GitHub App avec la communauté GitHub.

Pour créer une application Probot à partager, suivez ces étapes :

Générer une nouvelle GitHub App.
Ouvrez le projet que vous avez créé, puis personnalisez les paramètres dans le fichier app.yml. Probot utilise les paramètres de app.yml en tant que paramètres du manifeste de l’GitHub App.
Ajoutez le code personnalisé de votre application.
Exécutez l’GitHub App localement ou hébergez-la où vous le souhaitez. Quand vous accédez à l’URL de l’application hébergée, vous voyez une page web avec un bouton Inscrire l’GitHub App sur lequel les utilisateurs peuvent cliquer pour inscrire une application préconfigurée.

À l’aide de dotenv, Probot crée un fichier .env, puis définit les variables d’environnement APP_ID, PRIVATE_KEY et WEBHOOK_SECRET avec les valeurs récupérées dans la configuration de l’application.

Hébergement de votre application avec Glitch

Vous pouvez voir un exemple d’application Probot, qui utilise Glitch pour héberger et partager l’application. L’exemple utilise l’API des vérifications, puis sélectionne les événements ainsi que les autorisations d’API des vérifications nécessaires dans le fichier app.yml. Glitch est un outil qui vous permet de « remixer vos propres » applications. Le remixage d’une application crée une copie de l’application que Glitch héberge et déploie. Consultez « À propos de Glitch » pour en savoir plus sur le remixage d’applications Glitch.

Inscription d’une application GitHub à partir d’un manifeste

Dans cet article