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.
- Enterprise-Berechtigungen ermöglichen es der App, ein Unternehmen zu verwalten, wenn sie auf einem Unternehmenskonto 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.
Jeder Benutzer, jede Organisation oder jedes Unternehmen kann eine App mithilfe eines der Berechtigungstypen erstellen. Eine App mit Unternehmensberechtigungen muss public oder internal sein, damit sie in einem Enterprise-Konto installiert werden kann. Eine public App kann von jedem Unternehmen installiert werden, während eine internal App nur vom Unternehmen installiert werden kann, das die App oder das Unternehmen der Organisation besitzt, die die App besitzt. Es gibt keine zusätzlichen Einschränkungen, auf denen Organisationen oder persönliche Konten installiert werden können, auf denen eine App installiert werden kann.
Es gibt eine Ausnahme beim Installieren einer App in Unternehmen. Wenn eine App die Berechtigungen "Enterprise-Organisationsinstallationen" oder "Installationsrepositorys der Enterprise-Organisation" anfordert, ist das einzige Unternehmen, das sie installieren kann, der besitzer der App ist. Sie können die App nicht in einem anderen Unternehmen installieren, und Sie können einer App, die bereits in einem anderen Unternehmen installiert ist, als der Berechtigung, die sie besitzt, nicht hinzufügen.
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. Wenn sie es in ihrem Unternehmen installieren, sehen und erteilen sie nur die Enterprise-Berechtigungen, 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