À propos des GitHub App autorisations
GitHub Apps n’ont pas d’autorisations par défaut. Lorsque vous inscrivez un GitHub App, vous pouvez sélectionner des autorisations pour l’application. Les autorisations que vous sélectionnez déterminent ce que l’application peut faire avec GitHubles API de l’application et les webhooks auxquels l’application peut s’abonner. Vous devez sélectionner les autorisations minimales nécessaires pour l’application.
Bien qu’elles GitHub Apps n’aient 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, il GitHub App peut utiliser le jeton d’accès utilisateur résultant pour effectuer des demandes à l’API REST et à l’API GraphQL pour 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 classées en tant que référentiel, organisation, ou autorisations 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.
Lorsqu’un utilisateur installe une application sur son compte d’utilisateur ou son organisation, il voit et accorde les autorisations de dépôt et d’organisation demandées par l’application. Ils verront également la liste des autorisations de compte que l’application peut demander à 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.
Pour plus d’informations sur la spécification des autorisations lors GitHub App de l’inscription, consultez Inscription d’une application GitHub.
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.
À propos des modifications apportées aux autorisations
Vous pouvez modifier les autorisations des applications que vous possédez ou gérer à tout moment.
- Lorsqu’un propriétaire d’entreprise modifie les autorisations d’une application appartenant à un compte d’entreprise, les modifications sont automatiquement acceptées par les organisations de l’entreprise.
- Lorsqu’un gestionnaire d’applications d’entreprise modifie les autorisations d’une application appartenant à un compte d’entreprise, les modifications sont automatiquement acceptées par les organisations de l’entreprise où le gestionnaire d’applications est également propriétaire de l’organisation.
- Lorsque vous modifiez les autorisations d’une application appartenant à un utilisateur ou une organisation, le propriétaire de chaque compte sur lequel l’application a été 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.
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 .GitHub Apps Pour chaque webhook auquel vous souhaitez vous abonner, reportez-vous à la documentation du webhook pour voir les autorisations dont vous GitHub App avez besoin pour vous 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 ».
Sur votre GitHub App page d’inscription, les événements de webhook disponibles changeront à mesure que vous modifiez les autorisations de votre application. Si vous n’avez pas sélectionné suffisamment d’autorisations pour vous GitHub App abonner à un événement, l’événement n’apparaît pas en tant qu’option sur 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 pour 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 de l’API REST auxquels un GitHub App accès peut être associé à 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