À propos de GitHub Apps
Une GitHub App est un type d’intégration que vous pouvez créer pour interagir avec les fonctionnalités de GitHub et les étendre. Vous pouvez créer une GitHub App pour offrir de la flexibilité et réduire les frictions dans vos processus, sans avoir besoin de connecter un utilisateur ou de créer un compte de service.
Les cas d’usage courants pour les GitHub Apps sont les suivants :
- Automatisation des tâches ou des processus en arrière-plan
- Prise en charge de « Se connecter avec GitHub », qui permet aux utilisateurs de se connecter avec leur compte GitHub pour fournir leur identité dans votre écosystème
- Comme outil de développement, permettre aux utilisateurs d’utiliser GitHub en se connectant à votre GitHub App, laquelle peut ensuite agir en leur nom
- Intégration de votre outil ou service externe à GitHub
Les GitHub Apps sont des acteurs indépendants sur GitHub. Une GitHub App agit en son propre nom, ce qui signifie que vous n’avez pas besoin de gérer un bot ni un compte de service en tant qu’utilisateur distinct. Elles peuvent également s’authentifier en tant qu’utilisateur et agir au nom de l’utilisateur, à l’aide des autorisations qui lui sont accordées.
Un utilisateur ou une organisation peuvent avoir jusqu’à 100 GitHub Apps, mais il n’existe aucune limite quant au nombre pouvant être installé sur un compte.
Si vous souhaitez que votre application réponde aux événements sur GitHub, votre application doit s’abonner à des webhooks. Par exemple, vous voudrez peut-être que votre application laisse un commentaire lorsqu’une demande de tirage est ouverte. Pour plus d’informations, consultez « Utilisation de webhooks avec des applications GitHub ».
Pendant le développement, vous pouvez exécuter votre application localement. 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.
Autorisations et visibilité pour les GitHub Apps
GitHub Apps peut être installé directement sur les comptes d’organisations et les comptes personnels, et être autorisé à avoir accès à des référentiels spécifiques. Elles sont fournies avec des webhooks intégrés et des autorisations spécifiques et limitées. Quand vous configurez votre GitHub App, vous pouvez sélectionner des autorisations spécifiques pour elle. Ces autorisations déterminent ce que l’application peut faire via l’API GitHub, ce qu’elle peut faire au nom d’un utilisateur connecté et quels webhooks elle peut recevoir. Lorsque l’application est ensuite installée sur un compte d’utilisateur ou d’organisation, la personne qui installe l’application détermine les dépôts auxquels l’application peut accéder sous ce compte. Pour plus d’informations, consultez « Choix des autorisations pour une application GitHub ».
Par défaut, seuls les propriétaires d’organisation peuvent gérer les paramètres des applications GitHub dans une organisation. Pour permettre à d’autres utilisateurs de modifier les paramètres de développeur des applications GitHub appartenant à l’organisation, un propriétaire peut leur accorder des autorisations de gestionnaire d’applications GitHub. Les gestionnaires d’applications GitHub ne peuvent pas gérer les applications tierces. Pour plus d’informations sur l’ajout et la suppression de gestionnaires d’applications GitHub dans votre organisation, consultez « Rôles dans une organisation ».
Vous pouvez définir la visibilité de votre application pour contrôler qui peut l’installer. Vous pouvez la rendre publique afin que d’autres utilisateurs ou organisations GitHub puissent l’installer, ou la rendre privée afin que vous puissiez l’installer uniquement sur le compte propriétaire de l’application. Pour plus d’informations, consultez « Rendre une application GitHub publique ou privée ».
Quand utiliser les GitHub Apps
Lors de la création d’une intégration, envisagez d’utiliser une GitHub App dans les scénarios suivants au lieu d’une OAuth App, d’un personal access token ou de GitHub Actions.
Utilisation d’une GitHub App au lieu d’une OAuth App
En général, les GitHub App sont préférables aux OAuth App.
Pour plus d’informations, consultez « Différences entre les applications GitHub et les applications OAuth ».
Pour plus d’informations sur la migration d’une OAuth App existante vers une GitHub App, consultez « Migration d’applications OAuth vers des applications GitHub ».
Les GitHub App offrent une sécurité renforcée
Les GitHub App offrent un plus grand contrôle sur ce que l’application peut faire. Au lieu des vastes étendues qu’utilisent les OAuth App, les GitHub App utilisent des autorisations affinées. Par exemple, si votre application doit lire le contenu d’un dépôt, une OAuth App nécessite l’étendue repo, qui lui permet également de modifier le contenu et les paramètres du dépôt. Une GitHub App peut demander un accès en lecture seule au contenu du dépôt, ce qui ne lui permet pas d’effectuer des actions plus privilégiées comme la modification du contenu ou des paramètres du dépôt.
Les GitHub App offrent également un plus grand contrôle sur l’accès aux dépôts. Avec une GitHub App, l’utilisateur ou le propriétaire de l’organisation qui a installé l’application peut décider des dépôts auxquels l’application peut accéder. À l’inverse, une OAuth App peut accéder à chaque dépôt auquel l’utilisateur qui a autorisé l’application peut accéder.
Les GitHub App utilisent des jetons de courte durée. Si le jeton est divulgué, il reste valide pendant un laps de temps plus court, ce qui réduit les dommages qui peuvent être causés. À l’inverse, les jetons d’OAuth App n’expirent pas tant que la personne qui a autorisé l’OAuth App n’a pas révoqué le jeton.
Ces fonctionnalités de sécurité permettent de durcir la sécurité de votre GitHub App en limitant les dommages qui pourraient être causés si les informations d’identification de votre application fuitaient. De plus, cela permet aux organisations avec des stratégies de sécurité plus strictes d’utiliser votre application.
Les GitHub App peuvent agir indépendamment d’un utilisateur ou au nom de celui-ci
Les GitHub App peuvent agir indépendamment d’un utilisateur. C’est bien pour les automatisations qui ne nécessitent pas d’entrée utilisateur.
Comme les OAuth App, les GitHub App peuvent toujours effectuer des actions au nom d’un utilisateur. Contrairement aux OAuth App, qui n’indiquent pas que l’action a été effectuée par l’application, les GitHub App indiquent que l’action a été effectuée par l’application au nom de l’utilisateur.
Les GitHub App ne sont pas liées à un compte d’utilisateur et ne consomment pas de siège sur GitHub. Les GitHub App restent installées même lorsque la personne qui les a initialement installées quitte l’organisation. Cela permet à vos intégrations de continuer à fonctionner même si des personnes quittent votre équipe.
Les GitHub App ont des limites de débit évolutives
La limite de débit pour les GitHub App avec un jeton d’accès d’installation s’adapte au nombre de dépôts et le nombre d’utilisateurs dans l’organisation. À l’inverse, les OAuth Apps ont des limites de débit inférieures et ne sont pas évolutives. Pour plus d’informations, consultez « Limites de débit pour les applications GitHub ».
Les GitHub App ont des webhooks intégrés
Les GitHub App ont des webhooks intégrés centralisés. Les GitHub App peuvent recevoir des événements de webhook pour l’ensemble des dépôts et des organisations auxquels l’application peut accéder. À l’inverse, les OAuth App doivent configurer des webhooks individuellement pour chaque dépôt et organisation.
L’accès aux API diffère légèrement
En général, les GitHub App et les OAuth App peuvent effectuer les mêmes demandes d’API. Toutefois, il existe certaines différences entre ces deux éléments :
- L’API REST pour gérer les exécutions et les suites de vérifications est disponible dans les GitHub App uniquement.
- Les ressources d’entreprise sont disponibles dans les OAuth App uniquement.
- Certaines demandes peuvent retourner des données incomplètes en fonction des autorisations et de l’accès au dépôt accordé à une GitHub App. Par exemple, si votre application effectue une demande pour obtenir tous les dépôts auxquels un utilisateur peut accéder, la réponse inclut uniquement les dépôts auxquels l’application a également obtenu l’accès.
Pour plus d’informations sur les points de terminaison d’API REST disponibles pour les GitHub App, consultez « Points de terminaison disponibles pour les applications GitHub ».
Choix entre une GitHub App ou un personal access token
Si vous souhaitez accéder aux ressources GitHub au nom d’un utilisateur ou dans une organisation, ou si vous prévoyez une intégration longue durée, nous vous recommandons de créer une GitHub App.
Vous pouvez utiliser des personal access tokens pour les tests d’API ou les scripts de courte durée. Étant donné qu’un personal access token est associé à un utilisateur, votre automatisation peut s’interrompre si l’utilisateur n’a plus accès aux ressources dont vous avez besoin. Une GitHub App installée dans une organisation ne dépend pas d’un utilisateur. De plus, contrairement à un utilisateur, une GitHub App ne consomme pas de siège GitHub.
GitHub prend en charge deux types de personal access tokens, mais vous recommande d’utiliser des fine-grained personal access token à la place de personal access tokens (classic) autant que possible. Pour plus d’informations sur les personal access tokens, consultez « Création d’un jeton d’accès personnel ».
Choix entre une GitHub App ou des GitHub Actions
Les GitHub Apps et les GitHub Actions fournissent des moyens de créer des outils d’automatisation et de workflow.
Les GitHub Actions fournissent une automatisation qui peut effectuer des tâches telles que l’intégration continue, des tâches de déploiement et la gestion de projet dans un dépôt. Elles s’exécutent directement sur des machines d’exécuteur hébergé par GitHubou les exécuteurs auto-hébergés que votre administrateur configure. Les GitHub Actions ne s’exécutent pas de manière permanente. Elles s’exécutent en réponse aux événements qui se produisent dans leur dépôt et n’ont accès qu’aux ressources du dépôt pour lequel elles sont configurées. Toutefois, elles peuvent être partagées entre les dépôts et les organisations, ce qui permet aux développeurs de réutiliser et de modifier les actions existantes pour répondre à leurs besoins. Les GitHub Actions sont également fournies avec une gestion des secrets intégrée, que vous pouvez utiliser pour interagir avec des services tiers et gérer les clés de déploiement, le tout de façon sécurisée.
Les GitHub Apps s’exécutent en continu sur un serveur ou une infrastructure de calcul que vous fournissez, et elles réagissent aux événements de webhook ainsi qu’aux événements en dehors de l’écosystème GitHub. Elles constituent une bonne option pour les opérations qui s’étendent sur plusieurs dépôts ou organisations, ou pour fournir des services hébergés à d’autres organisations. Une GitHub App est le meilleur choix pour la création d’un outil avec des fonctions qui se produisent principalement en dehors de GitHub ou qui demandent plus de temps que quand une action est allouée à l’exécution.
Pour plus d’informations sur la comparaison entre les GitHub Actions et les GitHub Apps, consultez « À propos des actions personnalisées ».
Vous pouvez utiliser une GitHub App pour vous authentifier dans un workflow GitHub Actions si le GITHUB_TOKEN intégré n’a pas d’autorisations suffisantes. Pour plus d’informations, consultez « Effectuer des requêtes d’API authentifiées avec une application GitHub dans un workflow GitHub Actions ».
Présentation du type d’GitHub App à créer
Il existe plusieurs façons de concevoir une GitHub App selon les fonctionnalités que vous voulez que l’application ait.
GitHub Apps qui agissent au nom d’un utilisateur
Si vous souhaitez que votre application effectue des actions au nom d’un utilisateur, vous devez utiliser un jeton d’accès utilisateur pour l’authentification. Ce type de demande est parfois appelé « utilisateur à serveur », ce qui signifie que l’application est limitée par les autorisations qui lui ont été accordées et par l’autorisation de l’utilisateur. Avec ce modèle, l’utilisateur doit autoriser l’application avant que celle-ci ne puisse effectuer des actions. Pour plus d’informations, consultez « Authentification auprès d’une application GitHub pour le compte d’un utilisateur ».
Voici quelques exemples d’automatisations que vous pouvez créer avec une GitHub App, où l’application agit au nom d’un utilisateur :
- Une GitHub App qui utilise GitHub comme fournisseur d’identité pour votre écosystème
- Une GitHub App qui ajoute un service en plus de GitHub.com qui peut être utile à un utilisateur GitHub. Vous pouvez partager l’application avec d’autres développeurs via GitHub Marketplace ou en rendant l’application publique.
GitHub Apps qui agissent en leur nom
Si vous souhaitez que votre application effectue des actions en son nom, plutôt qu’au nom d’un utilisateur, vous devez utiliser un jeton d’accès d’installation pour l’authentification. Ce type de demande est parfois appelé « serveur à serveur », ce qui signifie que l’application est limitée par les autorisations qui lui ont été accordées. Pour plus d’informations, consultez « Installation de l’authentification en tant qu’application GitHub ».
Voici quelques exemples d’automatisations que vous pouvez créer avec une GitHub App, où l’application agit en son nom :
- Une GitHub App qui utilise des webhooks pour réagir à un événement en fonction d’un certain ensemble de critères. Par exemple, vous pouvez créer une automatisation autour des points de terminaison de l’API REST pour la révision des demandes pour un fine-grained personal access token qui approuve une demande en fonction d’une certaine stratégie
- Une GitHub App qui aide les contributeurs de dépôt. Par exemple, l’application peut publier des ressources utiles une fois qu’un contributeur a créé une demande de tirage ou fait un commentaire
- Une GitHub App qui génère des jetons de courte durée à donner à d’autres outils CI/CD ou pour tirer (pull) les informations d’un dépôt