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

À propos GitHub App des manifestes

Lorsqu’une personne inscrit à GitHub App partir d’un manifeste, elle doit uniquement suivre une URL et 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’enregistrement GitHub App et génère le secret webhook de l’application, la clé privée (fichier PEM), la clé secrète client et l'ID GitHub App. La personne qui crée l’inscription GitHub App à partir du manifeste possède l’inscription GitHub App et peut 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 commencer à utiliser GitHub App des manifestes ou voir un exemple d’implémentation. Pour en savoir plus, consultez Utilisation de Probot pour implémenter le GitHub App flux manifeste .

Voici quelques scénarios dans lesquels vous pouvez utiliser GitHub App des manifestes pour inscrire des applications préconfigurées :

Aidez les nouveaux membres de l’équipe à être opérationnels rapidement dans le cadre du développement de 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 GitHub App conceptions de référence à partager avec la GitHub communauté.
Veillez à déployer GitHub Apps dans des environnements de développement et de production à l’aide de la même configuration.
Suivez les révisions d’une GitHub App configuration.

Implémentation du GitHub App flux manifeste

Le GitHub App flux manifeste utilise un processus de négociation similaire au flux OAuth. Le flux utilise un manifeste pour enregistrer un GitHub App et reçoit un code temporaire utilisé pour récupérer la clé privée, le secret du webhook, et l'identifiant de l'application.

Remarque

Vous devez effectuer les trois étapes du GitHub App flux manifeste dans un délai d’une heure.

Procédez comme suit pour implémenter le GitHub App flux manifeste :

Vous redirigez les personnes vers GitHub pour enregistrer un nouveau GitHub App.

       GitHub redirige les personnes vers votre site.

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

1. Vous allez rediriger les personnes vers GitHub pour enregistrer un nouveau GitHub App

Pour rediriger les utilisateurs vers l’inscription d’un nouveau GitHub App, fournissez un lien pour qu’ils cliquent sur ce dernier pour envoyer une POST demande pour https://github.com/settings/apps/new 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 GitHub App paramètres manifeste en tant que chaîne encodée JSON dans un paramètre appelé manifest. Vous pouvez également inclure un stateparamètre pour plus de sécurité.

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

          GitHub App Paramètres du manifeste

Nom	Type	Description
`name`	`string`	Nom du GitHub App.
`url`	`string`

          **Obligatoire.** La page d’accueil de votre GitHub App.

hook_attributes | object | Configuration du webhook de GitHub App. redirect_url | string | URL complète à rediriger après qu’un utilisateur lance l’inscription d’un GitHub App depuis 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 vers laquelle rediriger les utilisateurs après avoir installé votre GitHub App configuration si une configuration supplémentaire est requise. description | string | Description du GitHub App. 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. default_events | array | Liste des événements auxquels s'abonne le GitHub App. default_permissions | object | Ensemble d’autorisations requises par le 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 ». Pour consulter la liste des autorisations disponibles et leurs noms paramétrés, consultez Gestion de vos jetons d’accès personnels. request_oauth_on_install | boolean | Définissez true pour demander à l'utilisateur d’autoriser le GitHub App, après que GitHub App est installé. setup_on_update | boolean | Définissez cette option sur true pour rediriger les utilisateurs vers la setup_url après qu'ils aient mis à jour votre installation 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 GitHub App, GitHub redirige de nouveau vers le redirect_url avec un paramètre de code temporaire 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 compléter le handshake, envoyez le temporaire code dans une demande POST au point de terminaison Créer un GitHub App à partir d’un manifeste. La réponse inclut le id (ID), GitHub App (clé privée) et pem``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 Manifest GitHub App dans un délai d'une heure.

Remarque

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 un GitHub App à partir d'un manifeste.

Lorsque la dernière étape du flux de manifeste est terminée, la personne qui inscrit l’application à partir du flux devient propriétaire d’un GitHub App enregistré qu'elle peut installer sur n'importe lequel de ses comptes. Ils peuvent choisir d’étendre l’application à l’aide des GitHub API, transférer la propriété à quelqu’un d’autre ou le supprimer à tout moment.

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

          [Probot](https://probot.github.io/) est une infrastructure créée avec [Node.js](https://nodejs.org/) qui effectue une grande partie des tâches nécessaires par tous GitHub Apps, comme la validation des webhooks et l’authentification. Probot implémente le [GitHub App flux de manifeste](#implementing-the-github-app-manifest-flow), ce qui facilite la création et le partage GitHub App de conceptions de référence avec la GitHub communauté.

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

       [Générer un nouveau GitHub App](https://probot.github.io/docs/development/#generating-a-new-app).

Ouvrez le projet que vous avez créé, puis personnalisez les paramètres dans le fichier app.yml. Probot utilise les paramètres définis dans app.yml comme les paramètres du GitHub App manifeste.
Ajoutez le code personnalisé de votre application.

       [Exécutez le fichier localement ou hébergez-le GitHub App](https://probot.github.io/docs/development/#running-the-app-locally) n’importe où vous le souhaitez. Lorsque vous accédez à l’URL de l’application hébergée, vous trouverez une page web avec un bouton **Inscrire GitHub App** que 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.

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

Dans cet article