Informationen zu GitHub App Berechtigungen
GitHub Apps sie besitzen standardmäßig keine Berechtigungen. Wenn Sie eine GitHub AppRegistrierung durchführen, können Sie Berechtigungen für die App auswählen. Die von Ihnen ausgewählten Berechtigungen bestimmen, was die App mit GitHubden APIs tun kann und welche Webhooks die App abonnieren kann. Du solltest die erforderlichen Mindestberechtigungen für deine App auswählen.
Obwohl GitHub Apps sie standardmäßig keine Berechtigungen besitzen, verfügen sie über implizite Berechtigungen, um öffentliche Ressourcen zu lesen, wenn sie im Namen eines Benutzers handeln. Wenn ein Benutzer die App autorisiert, in ihrem Auftrag zu handeln, kann der GitHub App resultierende Benutzerzugriffstoken verwenden, um Anforderungen an die REST-API und die GraphQL-API zum Lesen öffentlicher Ressourcen zu stellen. Weitere Informationen zum Handeln im Namen von Benutzern findest du unter Authentifizieren mit einer GitHub App im Namen eines Benutzers.
App-Berechtigungen werden als Repository-, Organisations-, Unternehmens- oder Kontoberechtigungen klassifiziert.
- Repositoryberechtigungen ermöglichen deiner App den Zugriff auf Ressourcen im Zusammenhang mit Repositorys im Besitz des Kontos, unter dem die App installiert ist.
- Organisationsberechtigungen ermöglichen deiner App den Zugriff auf Ressourcen im Zusammenhang mit der Organisation, in der die App installiert ist, sofern sie in einem Organisationskonto installiert ist.
- Kontoberechtigungen ermöglichen deiner App den Zugriff auf Ressourcen im Zusammenhang mit Benutzer*innen, wenn diese auch deine App autorisiert haben. Weitere Informationen zur Benutzerautorisierung von Apps findest du unter Authentifizieren mit einer GitHub App im Namen eines Benutzers.
Wenn ein Benutzer eine App auf ihrem Benutzerkonto oder seiner Organisation installiert, wird das Repository und die Organisation berechtigungen angezeigt und erteilt, die die App angefordert hat. Außerdem wird eine Liste der Kontoberechtigungen angezeigt, die von der App für einzelne Benutzer angefordert werden können. Wenn Benutzer*innen eine App autorisieren, in ihrem Namen zu handeln, sehen und gewähren sie die Kontoberechtigungen, die von der App angefordert wurden.
Der Erfolg einer API-Anforderung mit einem Benutzerzugriffstoken hängt sowohl von den Berechtigungen der Benutzerinnen als auch von den Berechtigungen der App ab. Wenn der App beispielsweise die Berechtigung zum Schreiben des Inhalts eines Repositorys erteilt wurde, die Benutzerinnen jedoch nur den Inhalt lesen können, erhält das Benutzerzugriffstoken nur die Berechtigung zum Lesen des Inhalts. Der Erfolg einer API-Anforderung mit einem Installationszugriffstoken hängt nur von den Berechtigungen der App ab.
Weitere Informationen zum Angeben von Berechtigungen während der GitHub App Registrierung finden Sie unter Registrieren einer GitHub-App.
Für einige Webhooks und den API-Zugriff sind Verwaltungsberechtigungen erforderlich. Wenn für deine App Verwaltungsberechtigungen erforderlich sind, solltest du diese Anforderung ggf. auf der Startseite deiner App erläutern. Dadurch können Benutzer*innen besser verstehen, warum deine App Berechtigungen auf hoher Ebene benötigt.
Informationen zu Änderungen an Berechtigungen
Sie können die Berechtigungen für Apps ändern, die Sie besitzen oder jederzeit verwalten.
- Wenn ein Unternehmensbesitzer die Berechtigungen einer App im Besitz eines Unternehmenskontos ändert, werden die Änderungen automatisch von Organisationen im Unternehmen akzeptiert.
- Wenn ein Unternehmens-App-Manager die Berechtigungen einer App im Besitz eines Unternehmenskontos ändert, werden die Änderungen automatisch von Organisationen im Unternehmen akzeptiert, in denen der App-Manager auch ein Organisationsbesitzer ist.
- Wenn Sie die Berechtigungen einer App ändern, die einem Benutzer oder einer Organisation gehört, die neuen Berechtigungen zu genehmigen. Wenn Kontobesitzer*innen die neuen Berechtigungen nicht genehmigen, werden in ihrer Installation weiterhin die alten Berechtigungen verwendet.
Weitere Informationen zum Ändern von Berechtigungen findest du unter Ändern einer GitHub App-Registrierung.
Auswählen von Berechtigungen für den Webhookzugriff
Die Webhook-Dokumentation gibt an, ob jeder Webhook verfügbar GitHub Appsist. Für jeden Webhook, den Sie abonnieren möchten, lesen Sie die Webhook-Dokumentation, um zu sehen, welche Berechtigungen ein GitHub App Abonnement für diesen Webhook erforderlich ist. Weitere Informationen finden Sie unter Webhook-Ereignisse und Webhook-Nutzlasten.
Wenn deine App beispielsweise team-Ereignisse abonnieren soll, muss die App über die Organisationsberechtigung vom Typ „Mitglied“ verfügen.
Auf Ihrer GitHub App Registrierungsseite ändern sich die verfügbaren Webhook-Ereignisse, wenn Sie die Berechtigungen Ihrer App ändern. Wenn Sie keine ausreichenden Berechtigungen für Das GitHub App Abonnieren eines Ereignisses ausgewählt haben, wird das Ereignis nicht als Option auf der App-Registrierungsseite angezeigt.
Auswählen von Berechtigungen für den REST-API-Zugriff
Die REST-API-Referenzdokumentation zu jedem Endpunkt gibt an, ob der Endpunkt mit GitHub Apps funktioniert und welche Berechtigungen erforderlich sind, damit die App den Endpunkt verwenden kann. Einige Endpunkte erfordern möglicherweise mehrere Berechtigungen und einige möglicherweise eine von mehreren Berechtigungen. Eine Übersicht, auf welche REST-API-Endpunkte mit GitHub App jeder Berechtigung zugreifen können, finden Sie unter Erforderliche Berechtigungen für GitHub Apps.
Um beispielsweise den Endpunkt GET /orgs/{org}/dependabot/secrets zu verwenden, muss deine App mindestens über Berechtigung auf Leseebene für die Berechtigung „Dependabot-Geheimnisse für Organisationen“ verfügen.
Wenn deine App eine REST-API-Anforderung mit unzureichenden Berechtigungen sendet, gibt die API eine Antwort vom Typ 403 zurück.
Sie erhalten den X-Accepted-GitHub-Permissions-Header in der REST-API-Antwort, damit Sie die richtigen Berechtigungen auswählen können. Der Header teilt Ihnen mit, welche Berechtigungen erforderlich sind, um auf den Endpunkt zuzugreifen. Weitere Informationen finden Sie unter Problembehandlung der REST-API.
Auswählen von Berechtigungen für den GraphQL-API-Zugriff
Bei GraphQL-Anforderungen solltest du deine App testen, um sicherzustellen, dass sie über die erforderlichen Berechtigungen für die GraphQL-Abfragen und -Mutationen verfügt, die du vornehmen möchtest.
Wenn deine App eine GraphQL-API-Anforderung oder Mutation mit unzureichenden Berechtigungen sendet, gibt die API eine Antwort vom Typ 401 zurück.
Auswählen von Berechtigungen für den Git-Zugriff
Wenn deine App ein Installationszugriffstoken oder Benutzerzugriffstoken für die Authentifizierung für den HTTP-basierten Git-Zugriff verwenden soll, musst du die Repositoryberechtigung „Inhalt“ anfordern. Wenn deine App speziell auf Actions-Dateien im .github/workflows-Verzeichnis zugreifen oder diese bearbeiten muss, fordere die Repositoryberechtigung „Workflows“ an.
Anschließend kannst du das Zugriffstoken als HTTP-Kennwort verwenden. Ersetze TOKEN durch dein Zugriffstoken.
git clone https://x-access-token:TOKEN@github.com/owner/repo.git