Informationen zu GitHub Apps
Eine GitHub App ist eine Art von Integration, die du erstellen kannst, um mit GitHub zu interagieren und die Funktionalität des Diensts zu erweitern. Du kannst eine GitHub App erstellen, um den Ablauf deiner Prozesse flexibler und reibungsloser zu gestalten, ohne einen Benutzer anmelden oder ein Dienstkonto erstellen zu müssen.
Zu den gängigen Anwendungsfällen von GitHub Apps gehören:
- Automatisieren von Aufgaben oder Hintergrundprozessen
- Unterstützung von „Anmelden mit GitHub“, wodurch Benutzer*innen sich mit ihrem GitHub-Konto anmelden können, um ihre Identität in deinem Ökosystem anzugeben
- Anwendung als Entwicklertool, mit dem Benutzer*innen mit GitHub arbeiten können, indem sie sich bei deiner GitHub App anmelden, die dann in ihrem Namen handeln kann
- Integration deines Tools oder externen Diensts mit GitHub
GitHub Apps sind unabhängige Akteure innerhalb von GitHub. Eine GitHub App agiert selbstständig. Dies bedeutet, dass du kein Bot- oder Dienstkonto als separaten Benutzer benötigst. Sie können sich auch als Benutzer authentifizieren und im Namen des Benutzers handeln, indem sie die ihm erteilten Berechtigungen verwenden.
Wenn deine App auf Ereignisse auf GitHub reagieren soll, muss deine App Webhooks abonnieren. Das kann beispielsweise notwendig sein, wenn deine App einen Kommentar schreiben soll, wenn ein Pull Request erstellt wird. Weitere Informationen findest du unter Verwenden von Webhooks mit GitHub-Apps.
Während der Entwicklung kannst du deine App lokal ausführen. Sobald die App für die Verwendung in der Produktion bereit ist, solltest du deine App auf einem dedizierten Server bereitstellen. Du kannst beispielsweise Azure App Service nutzen.
Berechtigungen und Sichtbarkeit für GitHub Apps
Du kannst GitHub Apps direkt in Organisationen und persönlichen Konten installieren und ihnen Zugriff auf bestimmte Repositorys gewähren. Diese Apps verfügen über integrierte Webhooks und restriktive, spezifische Berechtigungen. Beim Einrichten deiner GitHub App kannst du die spezifischen Berechtigungen für deine App auswählen. Diese Berechtigung bestimmen, was die App über die GitHub-API tun kann, was sie im Namen eines angemeldeten Benutzers tun kann und welche Webhooks die App empfangen kann. Wenn die App dann auf einem Benutzer- oder Organisationskonto installiert wird, entscheidet die Person, die die App installiert, auf welche Repositorys die App unter diesem Konto zugreifen kann. Weitere Informationen findest du unter Auswählen von Berechtigungen für eine GitHub-App.
Standardmäßig können die Einstellungen von GitHub Apps in einer Organisation nur von Organisationsbesitzern verwaltet werden. Um weiteren Benutzern das Ändern der Entwicklereinstellungen von GitHub Apps im Besitz der Organisation zu erlauben, kann ein Benutzer Berechtigungen als GitHub App-Manager erteilen. GitHub App-Manager können keine Drittanbieteranwendungen verwalten. Weitere Informationen zum Hinzufügen und Entfernen von GitHub App-Manager*innen in deiner Organisation findest du unter Rollen in einer Organisation.
Du kannst die Sichtbarkeit deiner App festlegen, um zu steuern, wer sie installieren kann. Du kannst sie öffentlich machen, damit andere GitHub-Benutzer oder Organisationen die App installieren können, oder sie als private App konfigurieren, sodass sie nur unter dem Konto installiert werden kann, dem die App gehört. Weitere Informationen findest du unter Öffentlich- oder Privatmachen einer GitHub-App.
Anwendungsfälle von GitHub Apps
Beim Erstellen einer Integration solltest du in Betracht ziehen, in den folgenden Szenarios eine GitHub App anstelle einer OAuth App, eines personal access token oder anstelle von GitHub Actions zu verwenden.
Verwenden einer GitHub App anstelle einer OAuth App
Im Allgemeinen wird eine GitHub App häufiger als eine OAuth App verwendet.
Weitere Informationen findest du unter Unterschiede zwischen GitHub-Apps und OAuth-Apps.
Informationen zum Migrieren einer vorhandenen OAuth App zu einer GitHub App findest du unter Migrating OAuth Apps to GitHub Apps.
Eine GitHub App bietet erhöhte Sicherheit
Eine GitHub App bietet mehr Kontrolle darüber, was die App tun kann. Anstelle des breiten Spektrums der Bereiche von OAuth App verwendet GitHub App differenzierte Berechtigungen. Wenn deine App beispielsweise den Inhalt eines Repositorys lesen muss, erfordert eine OAuth App den repo-Bereich, mit dem die App auch den Inhalt und die Einstellungen des Repositorys bearbeiten könnte. Eine GitHub App kann schreibgeschützten Zugriff auf Repositoryinhalte anfordern, wodurch die App keine privilegierteren Aktionen wie das Ändern der Repositoryinhalte oder -einstellungen durchführen kann.
Eine GitHub App bietet auch mehr Kontrolle über den Repositoryzugriff. Mit einer GitHub App kann derdie Besitzerin oder Organisationsbesitzerin, derdie die App installiert hat, entscheiden, auf welche Repositorys die App zugreifen kann. Umgekehrt kann eine OAuth App auf jedes Repository zugreifen, auf das derdie Benutzerin, der*die die App autorisiert hat, zugreifen kann.
Eine GitHub App verwendet kurzlebige Token. Wenn das Token kompromittiert wird, ist das Token für einen kürzeren Zeitraum gültig, wodurch der Schaden verringert wird, der angerichtet werden kann. Umgekehrt laufen OAuth App-Token nicht ab, bis die Person, die die OAuth App autorisiert hat, das Token widerruft.
Diese Sicherheitsfeatures helfen dabei, die Sicherheit deiner GitHub App zu härten, indem sie den Schaden begrenzen, der aus dem Kompromittieren der Anmeldeinformationen für deine App entstehen könnte. Darüber hinaus können Organisationen mit strengeren Sicherheitsrichtlinien deine App verwenden.
Eine GitHub App kann unabhängig von oder im Namen des Benutzers bzw. der Benutzerin handeln.
Eine GitHub App kann unabhängig von demder Benutzerin agieren. Dies ist von Vorteil für Automatisierungen, die keine Benutzereingabe erfordern.
Ähnlich wie eine OAuth App kann eine GitHub App weiterhin Aktionen im Namen eines Benutzers bzw. einer Benutzerin ausführen. Anders als eine OAuth App, die nicht anzeigt, dass die Aktion von der App ausgeführt wurde, gibt eine GitHub App an, dass die Aktion im Namen des Benutzers bzw. der Benutzerin ausgeführt wurde.
Eine GitHub App ist nicht an ein Benutzerkonto gebunden und nutzt keinen Platz auf GitHub Enterprise Server. Eine GitHub App bleibt auch dann installiert, wenn die Person, die die App ursprünglich installiert hat, die Organisation verlässt. Auf diese Weise können deine Integrationen auch dann weiterhin funktionieren, wenn Personen dein Team verlassen.
Eine GitHub App hat skalierbare Ratenlimits
Das Ratenlimit für eine GitHub App, die ein Installationszugriffstoken verwendet, wird mit der Anzahl der Repositorys und der Anzahl der Organisationsbenutzer skaliert. Umgekehrt weisen OAuth Apps niedrigere Ratenlimits auf und sind nicht skalierbar. Weitere Informationen findest du unter Rate limits for GitHub Apps (Ratenbegrenzungen für GitHub-Apps).
Eine GitHub App verfügt über integrierte Webhooks
Eine GitHub App verfügt über integrierte, zentralisierte Webhooks. Eine GitHub App kann Webhookereignisse für alle Repositorys und Organisationen empfangen, auf die die App zugreifen kann. Umgekehrt muss eine OAuth App Webhooks einzeln für jedes Repository und jede Organisation konfigurieren.
Der API-Zugriff unterscheidet sich geringfügig
Im Allgemeinen können eine GitHub App und eine OAuth App die gleichen API-Anforderungen ausführen. Es gibt aber einige Unterschiede:
- Die REST-API zum Verwalten von Überprüfungsausführungen und Überprüfungssammlungen ist nur für GitHub App verfügbar.
- Unternehmensressourcen sind nur für eine OAuth App verfügbar.
- Einige Anforderungen geben möglicherweise unvollständige Daten zurück, abhängig von den Berechtigungen und dem Repositoryzugriff, die einer GitHub App gewährt wurde. Wenn deine App beispielsweise eine Anforderung sendet, um alle Repositorys abzurufen, auf die eine Benutzerin zugreifen kann, enthält die Antwort nur die Repositorys, auf die der App ebenfalls Zugriff gewährt wurden.
Weitere Informationen zu den REST-API-Endpunkten für eine GitHub App findest du unter Für GitHub-Apps verfügbare Endpunkte.
Auswählen zwischen einer GitHub App oder einem personal access token
Wenn du im Namen eines Benutzers bzw. einer Benutzerin oder in einer Organisation auf GitHub-Ressourcen zugreifen möchtest oder eine langlebige Integration planst, empfiehlt es sich, eine GitHub App zu erstellen.
Du kannst personal access tokens für API-Tests oder kurzlebige Skripts verwenden. Da ein personal access token einem bzw. einer Benutzerin zugeordnet ist, kann deine Automatisierung unterbrochen werden, wenn die Benutzerinnen keinen Zugriff mehr auf die benötigten Ressourcen haben. Eine GitHub App, die in einer Organisation installiert ist, ist nicht von einemeiner Benutzerin abhängig. Darüber hinaus nutzt eine GitHub App im Gegensatz zu Benutzer*innen keinen GitHub-Arbeitsplatz.
GitHub unterstützt zwei Arten von personal access tokens, empfiehlt jedoch, nach Möglichkeit ein fine-grained personal access token anstelle von personal access tokens zu verwenden. Weitere Informationen zu personal access tokens findest du unter Managing your personal access tokens.
Auswählen zwischen einer GitHub App oder GitHub Actions
GitHub Apps und GitHub Actions bieten beide Möglichkeiten zum Erstellen von Automatisierungs- und Workflowtools.
GitHub Actions bieten Automatisierung, mit der Aufgaben wie Continuous Integration, Bereitstellungsaufgaben und das Projektmanagement in einem Repository ausgeführt werden können. Sie werden direkt auf mit GitHub gehosteten Runnercomputern ausgeführt, die deine Administratorin eingerichtet hat. GitHub Actions werden nicht dauerhaft ausgeführt. Sie werden als Reaktion auf Ereignisse ausgeführt, die in deinem Repository auftreten, und haben nur Zugriff auf die Ressourcen des Repositorys, für das sie eingerichtet sind. Sie können jedoch für mehrere Repositorys und Organisationen freigegeben werden, sodass Entwickler*innen vorhandene Aktionen wiederverwenden und ändern können, um ihre Anforderungen zu erfüllen. GitHub Actions verfügen auch über eine integrierte Geheimnisverwaltung, mit der du sicher mit Drittanbieterdiensten interagieren und Bereitstellungsschlüssel sicher verwalten kannst.
GitHub Apps werden dauerhaft auf einem Server oder in einer Computeinfrastruktur ausgeführt, die du bereitstellst, und sie reagieren auf Webhookereignisse sowie Ereignisse von außerhalb des GitHub-Ökosystems. Sie sind eine gute Option für Vorgänge, die mehrere Repositorys oder Organisationen umfassen, oder für die Bereitstellung gehosteter Dienste für andere Organisationen. Eine GitHub App ist die beste Wahl, wenn ein Tool mit Funktionen erstellt wird, die hauptsächlich außerhalb von GitHub verwendet werden oder mehr Zeit benötigen, als für die Ausführung einer Aktion vorgesehen ist.
Weitere Informationen zum Vergleichen von GitHub Actions mit GitHub Apps findest du unter Informationen zu benutzerdefinierten Aktionen.
Du kannst eine GitHub App zum Authentifizieren in einem GitHub Actions-Workflow verwenden, wenn das integrierte GITHUB_TOKEN nicht über ausreichende Berechtigungen verfügt. Weitere Informationen findest du unter Authentifizierte API-Anforderungen mit einer GitHub-App in einem GitHub Actions-Workflow.
Entscheiden, welche Art von GitHub App erstellt werden soll
Es gibt mehrere Möglichkeiten, eine GitHub App zu entwerfen, die du in Abhängigkeit von der gewünschten Funktionalität der App in Betracht ziehen solltest.
GitHub Apps, die im Namen des Benutzers bzw. der Benutzerin handeln
Wenn deine App Aktionen im Namen eines Benutzers bzw. einer Benutzerin ausführen soll, solltest du ein Benutzerzugriffstoken für die Authentifizierung verwenden. Diese Art von Anforderung wird manchmal als „Benutzer-zu-Server-Anforderung“ bezeichnet, was bedeutet, dass die App durch die Berechtigungen, die der App erteilt wurden, sowie die Berechtigung des Benutzers bzw. der Benutzerin beschränkt wird. Bei diesem Muster muss derdie Benutzerin die App autorisieren, bevor die App Maßnahmen ergreifen kann. Weitere Informationen findest du unter Authentifizieren mit einer GitHub-App im Namen von Benutzer*innen.
Zu den Automatisierungen, die du mit einer GitHub App erstellen kannst, bei der die App im Namen eines Benutzers bzw. einer Benutzerin handelt, gehören die Folgenden:
- Eine GitHub App, die GitHub als Identitätsanbieter für dein Ökosystem verwendet
- Eine GitHub App, die einen Diensts zusätzlich zur GitHub.com hinzufügt, der für einen GitHub-Benutzer nützlich sein kann Verfügbarmachen der App für andere Entwickler*innen über GitHub Marketplace oder indem du sie öffentlich machst
GitHub Apps, die eigenständig handeln
Wenn du möchtest, dass deine App Aktionen eigenständig und nicht im Namen eines Benutzers bzw. einer Benutzerin ausführt, solltest du ein Installationszugriffstoken für die Authentifizierung verwenden. Diese Art von Anforderung wird manchmal als „Server-zu-Server-Anforderung“ bezeichnet, was bedeutet, dass die App durch die Berechtigungen, die der App erteilt wurden, eingeschränkt wird. Weitere Informationen findest du unter Authentifizierung als GitHub-App-Installation.
Zu den Automatisierungen, die du mit einer GitHub App erstellen kannst, bei der die App eigenständig handelt, gehören die Folgenden:
- Eine GitHub App, die Webhooks verwendet, um unter Berücksichtigung bestimmter Kriterien auf ein Ereignis zu reagieren. Beispielsweise könntest du eine Automatisierung erstellen, die die REST-API-Endpunkte für Bezeichnungen verwendet, um jedem neuen Issue, das in einem Repository erstellt wird, unter Berücksichtigung bestimmter Kriterien eine Bezeichnung hinzuzufügen.
- Eine GitHub App, die Repositorymitwirkenden hilft. Beispielsweise könnte die App hilfreiche Ressourcen posten, nachdem eine Mitwirkender einen Pull Request erstellt oder einen Kommentar veröffentlicht.
- Eine GitHub App, die kurzlebige Token generiert, die an andere CI/CD-Tools übergeben werden oder Informationen aus einem Repository abrufen können.