Comment étendre GitHub, améliorer votre flux de travail avec les applications GitHub

GitHub Apps est la méthode officiellement recommandée pour s'intégrer à GitHub. Dans cet article, je vais vous montrer comment créer une application GitHub en moins de cinq minutes, en utilisant le framework d'application Probot.

Vous êtes-vous déjà demandé si vous pouviez étendre GitHub pour effectuer des actions spécifiques ou utiliser des fonctionnalités qui reflètent le flux de travail de votre équipe ? Les applications GitHub peuvent le faire pour vous.

Applications GitHub sont des applications qui vous donnent accès aux API GitHub afin que vous puissiez créer des intégrations avec GitHub, avec les avantages de la productivité, de la flexibilité et de la friction réduite dans votre flux de travail. Ils peuvent être installés directement sur les organisations et les comptes d'utilisateurs, et avoir accès à des référentiels spécifiques. Ils sont livrés avec des autorisations granulaires et des webhooks intégrés.

Pour améliorer votre flux de travail, vous pouvez créer une application GitHub qui contient plusieurs scripts ou une application entière, puis connecter cette application à de nombreux autres outils.

Par exemple, vous pouvez connecter les applications GitHub à GitHub ou Slack. Pour leProjet Knatif , nous avons une application GitHub qui gère les pull requests. Lorsqu'un PR est créé, il vérifie si l'utilisateur a accepté le CLA du projet et ajoute une étiquette indiquant l'état de ce contrôle. Il effectue quelques validations supplémentaires avant qu'un PR puisse être fusionné.

Créer votre première application GitHub

Vous pouvez créer des applications GitHub dans différents langages de programmation et les enregistrer sous votre compte personnel ou votre organisation. Je vais vous montrer comment créer une application GitHub en moins de cinq minutes, en utilisant leProbotscadre d'application.Probots est un framework pour créer des applications GitHub dans Node.js. Il vise à éliminer toute la corvée, comme la réception et la validation des webhooks et l'authentification, afin que vous puissiez vous concentrer sur les fonctionnalités que vous souhaitez créer.

Lecréer-probot-app est le meilleur moyen de commencer à créer une nouvelle application. Il générera une nouvelle application avec tout ce dont vous avez besoin pour démarrer et exécuter votre application en production. Pour commencer, ouvrez votre application en ligne de commande et exécutez la commande suivante :

npx créer-probot-app mon-github-app

Une série de questions vous sera posée. Répondez-y comme bon vous semble, mais pour la questionQuel modèle souhaitez-vous utiliser ?choisirbasic-js(ou vous êtes libre de choisirbasic-ts si tu veux). Les fichiers et packages nécessaires seront téléchargés et installés. La liste ci-dessous décrit certains des fichiers importants du projet :

1. index.js: C'est le point d'entrée dans l'application.
2. app.yml: Il s'agit du manifeste d'application GitHub utilisé lors de l'initialisation de l'application.
3. Fichier Docker: Un Dockerfile qui peut être utilisé pour conteneuriser et déployer l'application.

L'événement par défaut activé pour l'application lors de son démarrage est uniquement lequestions un événement. Vous écrirez plus tard du code pour vérifier les commentaires dans les tickets. Pour cela, vous devrez activer leissue_comment un événement. Ouvrirapp.yaml , allez à la ligne 25 et décommentez-la. Leévénements_par_défautsection du manifeste devrait ressembler à ce que vous voyez ci-dessous.

événements_par_défaut:









-issue_comment-questions

Inspectons le fichier index.js. Le code ci-dessous est le contenu du fichier.

module.exportations = (application) => {application.Journal.Info("Yay, l'application a été chargée !");application.sur("problèmes.ouverts", asynchrone (le contexte) => {
    constanteproblèmeCommentaire=le contexte.publier({corps: "Merci d'avoir ouvert ce problème !",
    });
    retournerle contexte.octokit.questions.créer un commentaire(problèmeCommentaire);
  });
};

Leapplicationle paramètre est une instance deProbotset vous donne accès à tous les avantages de GitHub.app.on est utilisé pour s'abonner aux événements déclenchés par GitHub. Vous devez spécifier le nom de l'événement et une fonction pour gérer l'événement.

Lele contextepassé au gestionnaire d'événements inclut tout ce qui concerne l'événement qui a été déclenché, ainsi que certaines propriétés utiles pour faire quelque chose d'utile en réponse à l'événement.contexte.octokitest un client GitHub authentifié qui peut être utilisé pour effectuer des appels API REST et GraphQL vers GitHub, et il vous permet de faire presque tout ce que vous pouvez faire par programmation via un navigateur Web sur GitHub.

Dans l'exemple de code,contexte.octokit est utilisé pour créer un commentaire de problème. Leapplicationetle contexteles objets ont tous deux unJournalobjet qui peut être utilisé pour consigner des informations dans le flux de sortie standard.

Enregistrement de l'application GitHub

Avec le code d'application prêt, vous pouvez maintenant l'enregistrer sur GitHub. Suivez les instructions ci-dessous pour le faire.

1. Exécutez l'application en exécutantdébut npmdans votre borne.
2. Accédez à http://localhost:3000 dans votre navigateur.
3. Vous devriez voir une page Web avec des boutons pour enregistrer l'application ou en utiliser une existante. Allez-y et cliquez sur leEnregistrer une application GitHubbouton.
4. Ensuite, vous devrez choisir un nom d'application qui n'est pas déjà pris. (Remarque : si vous voyez un message"Le nom est déjà utilisé"bien qu'aucune application de ce type n'existe, cela signifie qu'une organisation GitHub portant ce nom existe et ne peut pas être utilisée comme nom d'application.)
5. Après avoir enregistré votre application GitHub, vous serez redirigé pour installer l'application sur tous les référentiels de vos référentiels de choix. Sélectionnez un référentiel pour l'essayer. Vous pouvez également vérifier votre local.envet notez qu'il sera rempli avec les valeurs renvoyées par GitHub au cours de cette redirection.
6. Redémarrez le serveur dans votre terminal (appuyez surCTRL/CMD + Cpour arrêter le serveur).

Maintenant que l'application est enregistrée et installée dans un référentiel, accédez à la page des problèmes du référentiel et ouvrez un nouveau problème. Vous devriez remarquer que l'application GitHub laisse un commentaire lorsqu'un nouveau problème est créé.

Extension de l'application avec Probot-Commands

Probot n'a pas d'API d'extensions officielles, mais certains utilitaires réutilisables ont été extraits d'applications existantes.

L'un de ces utilitaires s'appellecommandes-probot . C'est une extension qui ajoute des commandes slash à GitHub. Les commandes slash sont des lignes qui commencent par"/” dans les commentaires sur les problèmes ou les demandes d'extraction qui permettent aux utilisateurs d'interagir directement avec votre application. Nous l'utiliserons pour ajouter des étiquettes aux problèmes afin de pouvoir filtrer les problèmes soitinsecteou alorsfonctionnalitéÉtiquettes.

Pour utiliser cet utilitaire, ouvrez le terminal et exécuteznpm install --save probot-commands . Ensuite, ouvrez index.js et ajoutez l'instruction de code ci-dessous.

commandes(application, "type", (le contexte,commande) => {
  constanteÉtiquettes=commande.arguments.divisé(/, */);
  retournerle contexte.octokit.questions.addLabels(le contexte.publier({Étiquettes}));
});

Le code obtient la valeur transmise par GitHub et l'utilise pour ajouter des étiquettes en appelantcontext.octokit.issues.addLabels(context.issue({ labels })).

Essayons les nouveaux changements. Redémarrez le serveur et ajoutez un commentaire commençant par/type au problème que vous avez ouvert dans la section précédente de cet article. Par exemple, entrez/genre boguecomme un nouveau commentaire sur la question.

Déploiement de l'application

Jusqu'à présent, vous avez exécuté l'application localement. Vous pouvez le déployer sur n'importe quel fournisseur de cloud et l'exécuter en tant qu'application Node.js. Le fichier Docker inclus peut être utilisé pour le conditionner et le déployer en tant qu'application conteneurisée.

Je vais utiliser la plate-forme DigitalOcean App en tant que fournisseur d'hébergement. Vous pouvez trouver plus de détails sur les autres options d'hébergement dans leDocumentation.

Pour commencer, validez vos modifications sur Git et créez un référentiel GitHub (ou GitLab), puis transférez-y vos modifications.

Si vous avez un compte DigitalOcean, connectez-vous et rendez-vous surapplications page . Si vous n'avez pas de compte, vous pouvezen créer un en utilisant mon lien de parrainagequi vous donne 100 $ pour essayer différentes choses sur DigitalOcean (etj'aurai du créditsi vous devenez un utilisateur actif).

Après avoir créé un nouveau compte, allez dans les applicationspageet cliquezLancez votre application bouton. Vous serez redirigé vers une page où vous préciserez la source de l'application. ChoisirGitHub(ou GitLab si c'est ce que vous utilisez).

Vous serez redirigé vers GitHub pour autoriser et installer l'application DigitalOcean GitHub (oui, ils utilisent également l'application GitHub !). Sélectionnez l'utilisateur ou l'organisation et les référentiels auxquels lui donner accès. Vous pouvez choisir de l'autoriser uniquement pour le référentiel que vous souhaitez déployer.

Après l'installation et l'autorisation, vous serez redirigé vers DigitalOcean. SélectionnerGitHub et choisissez le référentiel que vous souhaitez déployer dans la liste déroulante et sélectionnez une branche. Cliquez ensuite sur leSuivantbouton pour continuer.

Vous serez redirigé vers une page pour configurer l'application. Cliquez surModifierà côté de laVariables d'environnement pour ajouter des variables d'environnement. Vous avez besoin de trois variables d'environnement :

1. APP_ID: l'ID de l'application, que vous pouvez obtenir à partir de la page des paramètres de l'application
2. WEBHOOK_SECRET: le Webhook Secret que vous avez généré lors de la création de l'application
3. Et l'un des suivants :
   • CLÉ PRIVÉE: le contenu de la clé privée que vous avez téléchargée après la création de l'application, OU…
   • PRIVATE_KEY_PATH: le chemin vers un fichier de clé privée (CLÉ PRIVÉEprime surPRIVATE_KEY_PATH)

Copiez ces valeurs du.env fichier dans votre dossier de projet. (Remarque : cela a été généré lorsque vous avez enregistré l'application sur GitHub.) Cliquez ensuite surSuivant.

Choisissez un nom et une région pour l'application et cliquez surSuivant . Vous serez redirigé vers la dernière page où vous devrez choisir un plan pour exécuter l'application. À des fins de prototype, utilisez leBasiqueplan et untaille du conteneur qui coûte 5 $/mois. Faites défiler vers le bas de la page et cliquez sur leDémarrer l'applicationbouton.

La création de l'application prendra un certain temps. Une fois terminé, vous obtiendrez un domaine que vous pourrez ensuite utiliser pour l'application GitHub. Allez à laApplications GitHubpage des paramètres et cliquez sur leModifierbouton pour mettre à jour l'application.

Faites défiler jusqu'àWebhooksection et modifier laURL du webhook au nouveau domaine de DigitalOcean. Clique leSauvegarder les modificationsbouton pour enregistrer les modifications.

Avec l'application déployée sur DigitalOcean et l'URL Webhook mise à jour, chaque nouvel événement sera envoyé à la nouvelle URL.

Et après?

Vous avez appris à automatiser votre flux de travail et à vous intégrer à GitHub à l'aide des applications GitHub. C'est la méthode officiellement recommandée pour s'intégrer à GitHub, car ils offrent des autorisations beaucoup plus granulaires pour accéder aux données.

Les applications GitHub peuvent être installées directement sur les organisations et les comptes d'utilisateurs et se voir accorder l'accès à des référentiels spécifiques. Vous avez vu comment utiliser Probot pour créer une application Node.js GitHub et comment déployer l'application dans le cloud.

L'application que vous avez enregistrée en suivant les instructions de cet article est publique, mais elle n'est pas détectable par les autres utilisateurs de GitHub. Vous pouvez également partager ou vendre des applications dansPlace de marché GitHub . Pour savoir comment répertorier une application sur GitHub Marketplace, consultez la documentation GitHub "Premiers pas avec GitHub Marketplace.”

Si vous avez besoin que votre application fasse plus de choses que les autorisations activées lors de l'enregistrement de l'application, vous pouvez ajouter plus d'autorisations via la page des paramètres de l'application GitHub. Pour plus de détails, voir "Modification des autorisations d'une application GitHub.”

Vous pouvez obtenir le code source de l'exemple d'application surGitHub . Si vous voulez voir plus de façons de créer des applications GitHub, consultez monebook sur la création d'une plate-forme d'applications sans serveuren intégrant GitHub, Kubernetes et d'autres outils Cloud Native.