Informationen zu GitHub App-Berechtigungen
GitHub Apps verfügen standardmäßig über keine Berechtigungen. Beim Registrieren einer GitHub App kannst du Berechtigungen für die App auswählen. Die von dir ausgewählten Berechtigungen bestimmen, was die App mit den APIs von GitHub tun und welche Webhooks die App abonnieren kann. Du solltest die erforderlichen Mindestberechtigungen für deine App auswählen.
Obwohl GitHub Apps standardmäßig über keine Berechtigungen verfügen, verfügen sie über implizite Berechtigungen zum Lesen öffentlicher Ressourcen, wenn sie im Namen von Benutzerinnen handeln. Wenn eine Benutzer*in die App autorisiert, in seinem bzw. ihrem Namen zu handeln, kann die GitHub App das resultierende Benutzerzugriffstoken verwenden, um Anforderungen an die REST-API und die GraphQL-API zu senden, um öffentliche Ressourcen zu lesen. Weitere Informationen zum Handeln im Namen von Benutzern bzw. Benutzerinnen findest du unter Authentifizieren mit einer GitHub-App im Namen von Benutzer*innen.
App-Berechtigungen werden als Repository-, Organisations- 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 von Benutzer*innen.
Wenn Benutzerinnen eine App in ihrem Konto oder ihrer Organisation installieren, zeigen sie das Repository an und gewähren ihm die Repository- und Organisationsberechtigungen, die die App angefordert hat. Ihnen wird auch eine Liste der Kontoberechtigungen angezeigt, die die App für einzelne Benutzerinnen anfordern kann. Wenn Benutzer*innen eine App autorisieren, in ihrem Namen zu handeln, gewähren sie die Kontoberechtigung, 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.
Du kannst die Berechtigungen für deine App jederzeit ändern. Wenn du die Berechtigungen änderst, werden die Besitzerinnen aller Konten, unter denen die App installiert wurde, aufgefordert, die neuen Berechtigungen zu genehmigen. Wenn Kontobesitzerinnen die neuen Berechtigungen nicht genehmigen, werden in ihrer Installation weiterhin die alten Berechtigungen verwendet.
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.
Weitere Informationen zum Angeben von Berechtigungen während der GitHub App-Registrierung findest du unter Registrieren einer GitHub-App. Weitere Informationen zum Ändern von Berechtigungen findest du unter Ändern einer GitHub-App-Registrierung.
Auswählen von Berechtigungen für den Webhookzugriff
In der Webhookdokumentation ist angegeben, ob die einzelnen Webhooks für GitHub Apps verfügbar sind. Informationen zu den einzelnen Webhooks, die du abonnieren möchtest, findest du in der Webhookdokumentation. Dort ist angegeben, welche Berechtigungen eine GitHub App benötigt, um den jeweiligen Webhook zu abonnieren. Weitere Informationen findest du unter Webhook-Ereignisse und -Nutzlasten.
Wenn deine App beispielsweise team-Ereignisse abonnieren soll, muss die App über die Organisationsberechtigung vom Typ „Mitglied“ verfügen.
Auf der Seite mit der GitHub App-Registrierung ändern sich die verfügbaren Webhookereignisse, wenn du die Berechtigungen deiner App änderst. Wenn du nicht ausreichende Berechtigungen für deine GitHub App ausgewählt hast, um ein Ereignis zu abonnieren, wird das Ereignis nicht als Option auf der Seite mit der App-Registrierung angezeigt.
Auswählen von Berechtigungen für den REST-API-Zugriff
Die REST-API-Referenzdokumentation für jeden Endpunkt gibt an, ob der Endpunkt zusammen 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 eine GitHub App mit der jeweiligen Berechtigung zugreifen kann, sind unter „Für GitHub-Apps erforderliche Berechtigungen“ zu finden.
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 findest du 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