Cette version de GitHub Enterprise Server n'est plus disponible depuis le 2024-03-26. Aucune publication de correctifs n’est effectuée, même pour les problèmes de sécurité critiques. Pour de meilleures performances, une sécurité améliorée et de nouvelles fonctionnalités, effectuez une mise à niveau vers la dernière version de GitHub Enterprise. Pour obtenir de l’aide sur la mise à niveau, contactez le support GitHub Enterprise.

Démarrage rapide pour la création d’applications GitHub

Créez rapidement une GitHub App qui commente les demandes de tirage.

Dans cet article

Introduction

Des GitHub Apps vous permettent d’automatiser des processus ou d’intégrer d’autres plateformes à GitHub. Pour plus d’informations, consultez « À propos de la création d’applications GitHub ».

Ce guide de démarrage rapide explique comment créer rapidement une GitHub App. Lorsqu’une demande de tirage est ouverte dans un référentiel auquel l’application a obtenu l’accès, l’application ajoute un commentaire à la demande de tirage.

Ce guide de démarrage rapide utilise du code préécrit pour vous aider à démarrer rapidement. Pour obtenir un tutoriel plus détaillé qui vous aide à écrire le code, consultez « Génération d’une application GitHub qui répond aux événements de webhook ».

Prérequis

Votre ordinateur ou codespace doit utiliser Node.js, version 12 ou ultérieure. Pour plus d’informations, consultez Node.js.

Étape 1 : Cloner le code de l’application

Pour vous aider à démarrer rapidement, nous avons écrit du code que vous pouvez utiliser. Si vous souhaitez apprendre à écrire le code vous-même, consultez « Génération d’une application GitHub qui répond aux événements de webhook ».

  1. Clonez le référentiel github/github-app-js-sample. Pour plus d’informations, consultez « Clonage d’un dépôt ». Vous pouvez utiliser un clone local ou GitHub Codespaces.
  2. Dans une fenêtre de terminal, accédez au répertoire dans lequel votre clone est stocké.
  3. Exécutez npm install pour installer les dépendances.

Étape 2 : Obtenir une URL de proxy webhook

Pour développer votre application localement, vous pouvez utiliser une URL de proxy webhook pour transférer des webhooks à partir de GitHub vers votre ordinateur ou codespace. Ce démarrage rapide utilise Smee.io pour fournir une URL de proxy webhook et transférer des webhooks.

  1. Dans votre navigateur, accédez à https://smee.io/.
  2. Cliquez sur Démarrer un nouveau canal.
  3. Copiez l’URL complète sous « URL du proxy webhook ». Vous utiliserez cette adresse ultérieurement.

Étape 3 : Inscrire une GitHub App

Les étapes suivantes vous guident tout au long de la configuration des paramètres d’application requis pour ce démarrage rapide. Pour plus d’informations sur les paramètres, consultez « Inscription d’une application GitHub ».

  1. Dans le coin supérieur droit de n’importe quelle page sur GitHub, cliquez sur votre photo de profil.
  2. Accédez aux paramètres de votre compte.
    • Pour une application appartenant à un compte personnel, cliquez sur Paramètres.
    • Pour une application appartenant à une organisation :
      1. Cliquez sur Vos organisations.
      2. À droite de l’organisation, cliquez sur Paramètres.
  3. Dans la barre latérale gauche, cliquez sur Paramètres de développeur.
  4. Dans la barre latérale à gauche, cliquez sur GitHub Apps .
  5. Cliquez sur Nouvelle application GitHub.
  6. Sous « Nom de l’application GitHub », entrez un nom pour votre application. Par exemple, USERNAME-quickstart-app où USERNAME est votre nom d'utilisateur GitHub.
  7. Sous « URL de la page d’accueil », entrez https://github.com/github/github-app-js-sample#readme.
  8. Ignorez les sections « Identification et autorisation des utilisateurs » et « Après installation » pour ce démarrage rapide. Pour plus d’informations sur ces paramètres, consultez « Inscription d’une application GitHub ».
  9. Assurez-vous que Actif est sélectionné sous « Webhooks ».
  10. Sous « URL de webhook », entrez l’URL de votre proxy webhook à partir d’une version antérieure. Pour plus d’informations, consultez « Étape 2 : Obtenir une URL de proxy webhook ».
  11. Sous « Webhook secret », entrez une chaîne aléatoire. Vous utiliserez cette chaîne plus tard.
  12. Sous « Autorisations du référentiel », en regard de « Demandes de tirage », sélectionnez Lire et écrire.
  13. Sous « S’abonner aux événements », sélectionnez Demande de tirage.
  14. Sous « Où cette application GitHub peut-elle être installée ? », sélectionnez Uniquement sur ce compte.
  15. Cliquez sur Créer une application GitHub.

Étape 4 : Stocker les informations d’identification et les informations de connexion

Dans ce démarrage rapide, vous allez stocker les informations d’identification de votre application et identifier les informations en tant que variables d’environnement dans un fichier .env. Quand vous déployez votre application, vous voudrez modifier la façon dont vous stockez les informations d'identification. Pour plus d’informations, consultez « Déployer votre application ».

Assurez-vous que vous êtes sur un ordinateur sécurisé avant d’effectuer ces étapes, car vous allez stocker vos informations d’identification localement.

Créez un fichier .env .

Votre dépôt cloné inclut .env dans le fichier .gitignore. Cette action vous empêche de valider accidentellement les informations d'identification de votre application. Pour plus d’informations sur les fichiers .gitignore, consultez « Ignorer des fichiers ».

  1. Accédez au répertoire dans lequel votre clone de github/github-app-js-sample est stocké.

  2. Créez un fichier appelé .env au niveau supérieur de ce répertoire.

  3. Ajoutez le contenu suivant à votre fichier .env. Remplacez YOUR_HOSTNAME par le nom de votre instance GitHub Enterprise Server. Vous mettrez à jour les autres valeurs ultérieurement.

    Text
    APP_ID="YOUR_APP_ID"
WEBHOOK_SECRET="YOUR_WEBHOOK_SECRET"
PRIVATE_KEY_PATH="YOUR_PRIVATE_KEY_PATH"
HOSTNAME="YOUR_HOSTNAME"

Si vous vous êtes éloigné des paramètres de votre application après la création de votre application, accédez à la page des paramètres de votre application :

  1. Dans le coin supérieur droit de n’importe quelle page sur GitHub, cliquez sur votre photo de profil.
  2. Accédez aux paramètres de votre compte.
    • Pour une application appartenant à un compte personnel, cliquez sur Paramètres.
    • Pour une application appartenant à une organisation :
      1. Cliquez sur Vos organisations.
      2. À droite de l’organisation, cliquez sur Paramètres.
  3. Dans la barre latérale gauche, cliquez sur Paramètres de développeur.
  4. Dans la barre latérale à gauche, cliquez sur GitHub Apps .
  5. En regard du nom de votre application, cliquez sur Modifier.

Obtenir les informations d’identification et les informations d’identification de votre application

  1. Dans la page des paramètres de votre application, en regard de « ID d’application », recherchez l’ID d’application de votre application.
  2. Dans votre fichier, .env remplacez YOUR_APP_ID par l’ID d’application de votre application.
  3. Dans la page des paramètres de votre application, sous « Clés privées », cliquez sur Générer une clé privée. Une clé privée au format PEM est téléchargée sur votre ordinateur. Pour plus d’informations, consultez « Gestion des clés privées pour les applications GitHub ».
  4. Si vous utilisez un codespace, déplacez le fichier PEM téléchargé dans votre codespace afin que votre codespace puisse accéder au fichier.
  5. Dans votre fichier .env, remplacez YOUR_PRIVATE_KEY_PATH le chemin complet de votre clé privée, y compris l’extension .pem.
  6. Dans votre fichier .env, remplacez YOUR_WEBHOOK_SECRET par le secret webhook de votre application. Si vous avez oublié votre secret webhook, sous « Secret webhook (facultatif) », cliquez sur Modifier le secret. Entrez un nouveau secret, puis cliquez sur Enregistrer les modifications.

Étape 5 : Installer votre application

Pour que votre application laisse un commentaire sur les demandes de tirage dans un référentiel, elle doit être installée sur le compte propriétaire du référentiel et lui accorder l’accès. Étant donné que votre application est privée, elle ne peut être installée que sur le compte propriétaire de l’application.

  1. Dans le compte propriétaire de l’application que vous avez créée, créez un nouveau référentiel sur lequel installer l’application. Pour plus d’informations, consultez « Création d’un dépôt ».
  2. Si vous vous êtes éloigné des paramètres de votre application après la création de votre application, accédez à la page des paramètres de votre application. Pour plus d’informations, consultez « Accéder aux paramètres de votre application ».
  3. Cliquez sur Page publique.
  4. Cliquez sur Installer.
  5. Sélectionner Ne sélectionner que les référentiels.
  6. Sélectionnez le menu déroulant Sélectionner les référentiels , puis cliquez sur le référentiel que vous avez choisi au début de cette section.
  7. Cliquez sur Installer.

Étape 6 : Démarrer votre serveur

À des fins de test, vous utiliserez votre ordinateur ou codespace comme serveur. Votre application est uniquement active lorsque votre serveur est en cours d’exécution.

  1. Dans une fenêtre du terminal, accédez au répertoire dans lequel votre clone de github/github-app-js-sample est stocké.

  2. Pour recevoir des webhooks transférés à partir de Smee.io, exécutez npx smee -u WEBHOOK_PROXY_URL -t http://localhost:3000/api/webhook. Remplacez WEBHOOK_PROXY_URL par l’URL de proxy de votre webhook. Si vous avez oublié votre URL, vous pouvez la trouver dans le champ « URL du webhook » de la page des paramètres de votre application.

    Une sortie de ce type doit s’afficher, où WEBHOOK_PROXY_URL est l’URL de votre proxy webhook :

    Forwarding WEBHOOK_PROXY_URL to http://localhost:3000/api/webhook
Connected WEBHOOK_PROXY_URL

  3. Dans une deuxième fenêtre du terminal, accédez au répertoire dans lequel votre clone de github/github-app-js-sample est stocké.

  4. Exécuter npm run server. Votre terminal doit indiquer Server is listening for events at: http://localhost:3000/api/webhook.

Étape 7 : Test de l’application

Maintenant que votre serveur exécute et reçoit des événements de webhooks transférés, testez votre application en ouvrant une demande de tirage.

  1. Ouvrez une demande de tirage sur le dépôt que vous avez créé à l’Étape 5 : Installer votre application. Pour plus d’informations, consultez « Création d’une demande de tirage ».
  2. Accédez à l’URL du proxy de votre webhook sur smee.io. Un événement pull_request devrait apparaître. Cela indique que GitHub a correctement envoyé un événement de demande de tirage lorsque vous avez créé une demande de tirage.
  3. Dans le terminal où vous avez exécuté npm run server, vous devez voir quelque chose comme « Reçu un événement de demande de tirage pour #1 » où l’entier après le # est le numéro de la demande de tirage que vous avez ouverte.
  4. Dans la chronologie de votre demande de tirage, vous devez voir un commentaire de votre application. Le commentaire utilise le contenu du fichier message.md dans votre dépôt cloné.
  5. Dans les deux fenêtres du terminal, entrez Ctrl+C pour arrêter votre serveur et arrêter d’écouter les webhooks transférés.

Étapes suivantes

Maintenant que vous disposez d’une application, vous pouvez développer le code de votre application, déployer votre application et rendre votre application publique.

Modifier le code de l’application

Dupliquez le dépôt github/github-app-js-sample et modifiez le code pour répondre à différents événements de webhook ou pour effectuer différentes requêtes d’API. Pour plus d’informations sur le code, consultez « Génération d’une application GitHub qui répond aux événements de webhook ».

N’oubliez pas de mettre à jour les autorisations de votre application si des autorisations supplémentaires sont nécessaires pour les demandes d’API que vous souhaitez effectuer ou les événements de webhook que vous souhaitez recevoir. Pour plus d’informations, consultez « Choix des autorisations pour une application GitHub ».

Déployer votre application

Ce tutoriel a utilisé votre ordinateur ou codespace comme serveur. Une fois que l’application est prête pour être utilisée en production, vous devez déployer votre application sur un serveur dédié. Par exemple, vous pouvez utiliser Azure App Service.

Une fois que vous disposez d’un serveur, mettez à jour l’URL du webhook dans les paramètres de votre application. Vous ne devez pas utiliser Smee.io pour transférer vos webhooks en production.

Vous devez également mettre à jour les constantes port et host dans le code. Pour plus d’informations, consultez « Génération d’une application GitHub qui répond aux événements de webhook ».

Vous ne devez jamais rendre public la clé privée ou le secret du webhook de votre application. Ce tutoriel a stocké les informations d’identification de votre application dans un fichier gitignored .env. Quand vous déployez votre application, choisissez un moyen sécurisé de stocker les informations d'identification et de mettre à jour votre code pour obtenir la valeur en conséquence. Vous pouvez par exemple stocker vos informations d’identification dans une variable d’environnement sur le serveur sur lequel votre application est déployée. Vous pouvez également utiliser un service de gestion des secrets comme Azure Key Vault.

Partager vos données

Si vous souhaitez partager votre application avec d’autres utilisateurs et organisations, rendez-la publique. Pour plus d’informations, consultez « Rendre une application GitHub publique ou privée ».

Suivre les bonnes pratiques

Vous devez vous efforcer de suivre les bonnes pratiques avec votre GitHub App. Pour plus d’informations, consultez « Meilleures pratiques pour la création d’une application GitHub ».