À propos des autorisations de GitHub App
Les GitHub Apps n’ont aucune autorisation par défaut. Quand vous inscrivez votre GitHub App, vous pouvez sélectionner des autorisations pour elle. Les autorisations sélectionnées déterminent ce que l’application peut faire avec les API de GitHub et les webhooks auxquels l’application peut s’abonner. Vous devez sélectionner les autorisations minimales nécessaires pour l’application.
Même si les GitHub Apps n’ont pas d’autorisations par défaut, elles disposent d’autorisations implicites pour lire les ressources publiques lorsqu’elles agissent pour le compte d’un utilisateur. Lorsqu’un utilisateur autorise l’application à agir en son nom, l’GitHub App peut utiliser le jeton d’accès utilisateur résultant pour effectuer des requêtes à l’API REST et à l’API GraphQL afin de lire les ressources publiques. Pour en savoir plus sur la façon d’agir au nom d’un utilisateur, consultez « Authentification auprès d’une application GitHub pour le compte d’un utilisateur ».
Les autorisations d’application sont classifiées en tant qu’autorisations de référentiel, d’organisation ou de compte. Les autorisations de référentiel permettent à votre application d’accéder aux ressources liées aux référentiels dont le compte où l’application est installée est propriétaire. Les autorisations d’organisation permettent à votre application d’accéder aux ressources liées à organisation où l’application est installée si celle-ci est installée sur un compte organisation. Les autorisations de compte permettent à votre application d’accéder aux ressources liées à un utilisateur si l’utilisateur a également autorisé votre application. Pour plus d’informations sur les autorisations utilisateur des applications, consultez « Authentification auprès d’une application GitHub pour le compte d’un utilisateur ».
Quand un utilisateur installe une application sur son compte ou son organisation, il peut afficher et accorder les autorisations demandées par l’application au référentiel et à l’organisation. L’utilisateur voit également la liste des autorisations de compte que l’application peut demander pour des utilisateurs individuels. Quand un utilisateur autorise une application à agir en son nom, il affiche et accorde les autorisations de compte demandées par l’application.
La réussite d’une demande d’API avec un jeton d’accès utilisateur dépend des autorisations de l’utilisateur, ainsi que des autorisations de l’application. Par exemple, si l’application a reçu l’autorisation d’écrire le contenu d’un dépôt, mais que l’utilisateur peut uniquement lire le contenu, le jeton d’accès utilisateur peut uniquement lire le contenu. La réussite d’une demande d’API avec un jeton d’accès d’installation dépend uniquement des autorisations de l’application.
Vous pouvez modifier les autorisations de votre application à tout moment. Quand vous modifiez les autorisations, le propriétaire de chaque compte sur lequel l’application est installée est invité à approuver les nouvelles autorisations. Si le propriétaire du compte n’approuve pas les nouvelles autorisations, son installation continue d’utiliser les anciennes autorisations.
Certains accès aux API et webhooks nécessitent des autorisations « Administration ». Si votre application nécessite des autorisations « Administration », envisagez d’expliquer cette exigence sur la page d’accueil de votre application. Cela aidera les utilisateurs à comprendre pourquoi votre application a besoin d’une autorisation de haut niveau.
Pour plus d’informations sur la spécification d’autorisations lors d’une inscription d’GitHub App d’agir, consultez « Inscription d’une application GitHub ». Pour plus d’informations sur la modification des autorisations, consultez « Modification d’une inscription d’application GitHub ».
Choix des autorisations pour l’accès au webhook
La documentation du webhook indique si chaque webhook est disponible pour GitHub Apps. Pour chaque webhook auquel vous souhaitez vous abonner, reportez-vous à la documentation du webhook pour consulter les autorisations dont une GitHub App a besoin pour s’abonner à ce webhook. Pour plus d’informations, consultez « Événements et charges utiles du webhook ».
Par exemple, si vous souhaitez que votre application s’abonne aux événements team, elle doit disposer de l’autorisation d’organisation « Membres ».
Dans la page de votre inscription d’GitHub App, les événements webhook disponibles changent à mesure que vous modifiez les autorisations de votre application. Si vous n’avez pas sélectionné suffisamment d’autorisations pour l’abonnement à un événement de votre GitHub App, l’événement n’apparaîtra pas en tant qu’option dans la page d’inscription de votre application.
Choix des autorisations pour l’accès à l’API REST
La documentation de référence de l’API REST de chaque point de terminaison indique si le point de terminaison fonctionne avec GitHub Apps et indique les autorisations requises pour que l’application utilise le point de terminaison. Certains points de terminaison peuvent nécessiter plusieurs autorisations, et certains points de terminaison peuvent nécessiter une autorisation parmi des autorisations multiples. Pour obtenir une vue d’ensemble des points de terminaison d’API auxquels GitHub App peut accéder avec chaque autorisation, consultez « Autorisations requises pour les applications GitHub ».
Pour utiliser le point de terminaison GET /orgs/{org}/dependabot/secrets par exemple, votre application doit disposer au moins d’une autorisation de niveau lecture pour l’autorisation « Secrets Dependabot de l’organisation ».
Si votre application effectue une demande d’API REST en ayant des autorisations insuffisantes, l’API retourne une réponse 403.
Pour vous aider à choisir les autorisations appropriées, vous recevrez l’en-tête X-Accepted-GitHub-Permissions dans la réponse de l’API REST. L’en-tête vous indique les autorisations requises pour accéder au point de terminaison. Pour plus d’informations, consultez « Résolution des problèmes de l’API REST ».
Choix des autorisations pour l’accès à l’API Graph
Pour les requêtes GraphQL, vous devez tester votre application pour vous assurer qu’elle dispose des autorisations requises pour les requêtes GraphQL et les mutations que vous souhaitez effectuer.
Si votre application effectue une requête d’API Graph ou une mutation avec des autorisations insuffisantes, l’API retourne une réponse 401.
Choix des autorisations pour l’accès à Git
Si vous souhaitez que votre application utilise un jeton d’accès d’installation ou d’utilisateur afin de s’authentifier pour l’accès à Git basé sur HTTP, vous devez demander l’autorisation de dépôt « Contenu ». Si votre application a spécialement besoin d’accéder ou de modifier les fichiers Actions dans le répertoire .github/workflows, demandez l’autorisation de dépôt « Workflows ».
Vous pouvez ensuite utiliser le jeton d’accès en tant que mot de passe HTTP. Remplacez TOKEN par le jeton d’accès :
git clone https://x-access-token:TOKEN@github.com/owner/repo.git