Migration d’applications OAuth vers des applications GitHub

Découvrez les avantages de la migration de votre OAuth app vers une GitHub App et apprenez à migrer votre OAuth app.

Dans cet article

Avantages de la migration des OAuth apps vers des GitHub Apps

Les GitHub Apps sont la méthode recommandée pour l’intégration à GitHub. Les GitHub Apps offrent de nombreux avantages par rapport aux OAuth apps, notamment :

  • fonctionnalités de sécurité améliorées, telles que les autorisations affinées, le choix de l’accès au dépôt et les jetons de courte durée
  • la possibilité d’agir indépendamment d’un utilisateur ou au nom de celui-ci
  • limites de débit évolutives
  • webhooks intégrés

Pour plus d’informations, consultez « À propos de la création d’applications GitHub ».

Conversion d’une OAuth app en une GitHub App

Les étapes suivantes fournissent une vue d’ensemble de la migration d’une OAuth app vers une GitHub App. Les étapes spécifiques dépendent de votre application.

1. Passer en revue votre OAuth app

Familiarisez-vous de nouveau avec le code de votre OAuth app. Les demandes d’API que fait votre OAuth app vous aideront à décider des autorisations à sélectionner pour votre GitHub App.

Par ailleurs, quelques points de terminaison d’API REST ne sont pas disponibles pour les OAuth apps. Vérifiez que tous les points de terminaison REST que vous utilisez sont disponibles pour les GitHub Apps en consultant « Points de terminaison disponibles pour les jetons d’accès d’installation d’application GitHub ».

2. Inscrire une GitHub App

Inscrivez une nouvelle GitHub App. Pour plus d’informations, consultez « Inscription d’une application GitHub ».

Par rapport à une OAuth app, vous avez un plus grand contrôle sur les paramètres d’une GitHub App. Voici quelques ajouts clés :

  • Contrairement à une OAuth app qui agit toujours au nom d’un utilisateur, vous pouvez faire en sorte que votre GitHub App effectuent des actions en son nom ou au nom d’un utilisateur. Si vous ne souhaitez pas que votre nouvelle GitHub App effectue des actions au nom d’un utilisateur, vous pouvez ignorer les paramètres « Identification et autorisation des utilisateurs ». Pour plus d’informations, consultez « À propos de l’authentification avec une application GitHub ».

  • Vous pouvez utiliser des webhooks pour notifier votre GitHub App lorsque des événements spécifiques se produisent. Contrairement aux webhooks pour les OAuth apps, que vous devez configurer via l’API pour chaque référentiel ou organisation, les webhooks sont intégrés aux GitHub Apps. Lorsque vous inscrivez votre GitHub App, vous pouvez sélectionner les événements de webhook que vous souhaitez recevoir. De plus, si votre OAuth app utilise actuellement l’interrogation pour déterminer si un événement s’est produit, envisagez plutôt de vous abonner à des webhooks pour aider votre GitHub App à rester dans la limite de débit. Pour plus d’informations, consultez « Utilisation de webhooks avec des applications GitHub ».

  • Avec une OAuth app, vous demandez des étendues lorsqu’un utilisateur autorise votre application. Avec une GitHub App, vous spécifiez des autorisations dans les paramètres de l’application. Ces autorisations sont plus affinées que les étendues et vous permettent de sélectionner uniquement les autorisations dont votre application a besoin. De plus, ces autorisations sont mappées à des points de terminaison d’API REST et à des événements de webhook, ce qui vous permet de déterminer facilement les autorisations dont votre GitHub App a besoin pour accéder à un point de terminaison d’API REST spécifique ou s’abonner à un webhook spécifique. Actuellement, les autorisations ne sont pas documentées pour les demandes GraphQL. Pour plus d’informations, consultez « Choix des autorisations pour une application GitHub ».

3. Modifier le code de votre application

Une fois que vous avez inscrit une GitHub App, adaptez le code de votre ancienne OAuth app pour utiliser votre nouvelle GitHub App.

Mettre à jour l’authentification

Vous devez mettre à jour le code de votre application pour gérer l’authentification d’API pour votre GitHub App. Une GitHub App peut s’authentifier de trois manières :

Si vous utilisez la bibliothèque Octokit.js officielle de GitHub, vous pouvez utiliser l’objet App intégré pour vous authentifier. Pour obtenir des exemples, consultez « Écriture de scripts avec l’API REST et JavaScript » et « Génération d’une application GitHub qui répond aux événements de webhook ».

Passer en revue les limites de débit

Consultez les différences de limites de débit entre les OAuth apps et les GitHub Apps. Les GitHub Apps utilisent des règles adaptables pour les limites de débit qui peuvent augmenter en fonction du nombre de référentiels et du nombre d’utilisateurs dans l’organisation. Pour plus d’informations, consultez « Limites de débit pour les applications GitHub ».

Si possible, envisagez d’utiliser des demandes conditionnelles et de vous abonner à des webhooks plutôt que d’utiliser l’interrogation, afin de vous aider à rester dans les limites de débit. Pour plus d’informations sur les demandes conditionnelles, consultez « Meilleures pratiques pour utiliser l'API REST ». Pour plus d’informations sur l’utilisation de webhooks avec votre GitHub App, consultez « Utilisation de webhooks avec des applications GitHub » et « Génération d’une application GitHub qui répond aux événements de webhook ».

Tester votre code

Testez votre nouvelle GitHub App pour vous assurer que votre code fonctionne comme prévu.

4. Faire connaître votre nouvelle GitHub App

Si vous souhaitez que d’autres comptes puissent utiliser votre nouvelle GitHub App, assurez-vous que votre application est publique.Pour plus d’informations, consultez « Rendre une application GitHub publique ou privée ».

5. Demander à vos utilisateurs de procéder à la migration

Une fois que votre nouvelle GitHub App est prête, demandez aux utilisateurs de votre ancienne OAuth app de migrer vers votre nouvelle GitHub App. Il n’existe pas de moyen d’effectuer une migration automatique de vos utilisateurs. Chaque utilisateur doit installer et/ou autoriser votre GitHub App lui-même.

En tant que propriétaire de l’application, vous devez inclure des appels à l’action pour encourager vos utilisateurs à installer/autoriser la nouvelle GitHub App et à révoquer l’autorisation pour l’ancienne OAuth app. Vous devez également mettre à jour la documentation ou les éléments de l’interface utilisateur.

Inviter les utilisateurs à installer votre GitHub App

Si vous souhaitez que votre GitHub App effectue des demandes d’API en son nom ou accède aux ressources d’organisation ou de dépôt, l’utilisateur doit installer votre GitHub App. Lorsqu’un utilisateur installe une GitHub App sur son compte ou organisation, il choisit les dépôts auxquels l’application peut accéder et lui accorde les autorisations d’organisation et de dépôt qu’elle a demandées.

Pour aider vos utilisateurs à installer votre GitHub App, vous pouvez ajouter un lien vers la page web de votre application sur lequel les utilisateurs peuvent cliquer pour installer l’GitHub App. Le format de l’URL d’installation est http(s)://HOSTNAME/github-apps/YOUR_APP_NAME/installations/new. Remplacez YOUR_APP_NAME par le nom « slugifié » de votre GitHub App, que vous trouverez dans le champ « Lien public » de la page des paramètres de votre GitHub App.

Pour présélectionner les dépôts auxquels votre OAuth app avait accès, vous pouvez ajouter /permissions et les paramètres de requête à l’URL d’installation. Cela permet aux utilisateurs d’accorder à votre GitHub App l’accès aux dépôts auxquels votre OAuth app a déjà accès. Les paramètres de requête sont :

  • suggested_target_id : ID de l’utilisateur ou de l’organisation qui installe votre GitHub App. Ce paramètre est obligatoire.
  • repository_ids[] : ID de dépôt à sélectionner pour l’installation. En cas d’omission, tous les dépôts sont sélectionnés. Le nombre maximal de dépôts pouvant être pré-sélectionnés s’élève à 100. Pour obtenir la liste des dépôts auxquels votre OAuth app a accès, utilisez les points de terminaison Lister les dépôts de l’utilisateur authentifié et Lister les dépôts de l’organisation.

Par exemple : http(s)://HOSTNAME/github-apps/YOUR_APP_NAME/installations/new/permissions?suggested_target_id=ID_OF_USER_OR_ORG&repository_ids[]=REPO_A_ID&repository_ids[]=REPO_B_ID.

Pour plus d’informations sur l’installation de GitHub Apps, consultez « Installation d’une application GitHub à partir d’un tiers » et « Installation de votre propre application GitHub ».

Inviter les utilisateurs à autoriser votre application

Si vous souhaitez que votre GitHub App effectue des demandes d’API au nom d’un utilisateur, celui-ci doit autoriser l’application. Quand un utilisateur autorise une application, il lui accorde l’autorisation d’agir en son nom et il accorde les autorisations de compte demandées par l’application. Si l’application est installée sur un compte d’organisation, chaque utilisateur de cette organisation doit autoriser l’application pour qu’elle agisse en son nom.

Pour inviter les utilisateurs à autoriser votre application, guidez-les à travers le flux d’application web ou le flux d’appareil. Pour plus d’informations, consultez « Génération d’un jeton d’accès utilisateur pour une application GitHub ».

Pour plus d’informations sur l’autorisation des GitHub Apps, consultez « Autorisation des applications GitHub ».

Encourager vos utilisateurs à révoquer l’accès à l’OAuth app

Vous devez également encourager vos utilisateurs à révoquer l’accès à votre ancienne OAuth app. Cela vous permet de finaliser la transition de votre OAuth app et de garder les données de vos utilisateurs en sécurité. Pour plus d’informations, consultez « Examen de vos applications autorisées OAuth ».

Mettre à jour l’interface ou la documentation

Vous devez mettre à jour l’interface utilisateur ou la documentation relative à votre application pour refléter le remplacement d’une OAuth app par une GitHub App.

6. Supprimer les webhooks de votre ancienne OAuth app

Lorsqu’un utilisateur installe votre GitHub App et lui accorde l’accès à un dépôt, vous devez supprimer tous les webhooks de votre ancienne OAuth app. Si votre nouvelle GitHub App et votre ancienne OAuth app répondent aux webhooks pour le même événement, l’utilisateur peut observer un comportement en double.

Pour supprimer des webhooks de dépôt, vous pouvez écouter le webhook installation_repositories avec l’action added. Lorsque votre GitHub App reçoit cet événement, vous pouvez utiliser l’API REST pour supprimer le webhook sur ces dépôts pour votre OAuth app. Pour plus d’informations, consultez « Événements et charges utiles du webhook » et « Points de terminaison d’API REST pour les webhooks du référentiel ».

De même, pour supprimer des webhooks d’organisation, vous pouvez écouter le webhook installation avec l’action created. Lorsque votre GitHub App reçoit cet événement pour une organisation, vous pouvez utiliser l’API REST pour supprimer le webhook sur cette organisation et les dépôts correspondants pour votre OAuth app. Pour plus d’informations, consultez « Événements et charges utiles du webhook », « Points de terminaison d’API REST pour les webhooks de l’organisation » et « Points de terminaison d’API REST pour les webhooks du référentiel ».

7. Supprimer votre ancienne OAuth app

Une fois que vos utilisateurs ont migré vers votre nouvelle GitHub App, vous devez supprimer votre ancienne OAuth app. Cela permet d’éviter une mauvaise utilisation des informations d’identification de l’OAuth app. Cette action révoque également toutes les autorisations restantes de l’OAuth app. Pour plus d’informations, consultez « Suppression d’une application OAuth ». Si votre OAuth app est référencée sur GitHub Marketplace, vous devrez peut-être contacter le Support GitHub pour supprimer d’abord votre application de la Place de marché.