Migrieren von OAuth-Apps zu GitHub-Apps

Hier erfährst du, welche Vorteile die Migration deiner OAuth app zu einer GitHub App hat und wie du eine OAuth app migrierst.

In diesem Artikel

Vorteile der Migration von OAuth apps zu GitHub Apps

Es wird empfohlen, GitHub Apps für die Integration in GitHub zu verwenden. GitHub Apps bieten viele Vorteile gegenüber OAuth apps, einschließlich:

  • verbesserte Sicherheitsfeatures, z. B. differenzierte Berechtigungen, Optionen für den Repositoryzugriff und kurzlebige Token
  • die Möglichkeit, unabhängig von oder im Namen eines Benutzers oder einer Benutzerin zu handeln
  • skalierbare Ratenlimits
  • integrierte Webhooks

Weitere Informationen findest du unter Informationen zum Erstellen von GitHub-Apps.

Konvertieren einer OAuth app in eine GitHub App

Die folgenden Schritte stellen einen Überblick über die Migration von einer OAuth app zu einer GitHub App dar. Die genauen Schritte hängen von deiner App ab.

1. Überprüfen der OAuth app

Sieh dir den Code für deine OAuth app noch einmal genau an. Die API-Anforderungen, die deine OAuth app tätigt, helfen dir bei der Entscheidung, welche Berechtigungen für deine GitHub App ausgewählt werden sollten.

Darüber hinaus gibt es einige REST-API-Endpunkte, die für OAuth apps nicht verfügbar sind. Im Artikel Für GitHub-App-Installationszugriffstoken verfügbare Endpunkte findest du Informationen dazu, welche REST-Endpunkte für GitHub Apps verfügbar sind.

2. Registrieren einer GitHub App

Registriere eine neue GitHub App. Weitere Informationen findest du unter Registrieren einer GitHub-App.

Im Vergleich zu einer OAuth app hast du bei einer GitHub App mehr Kontrolle über die Einstellungen. Weitere wichtige Vorteile sind:

  • Im Gegensatz zu einer OAuth app, der immer im Namen eines Benutzers oder einer Benutzerin handelt, kann eine GitHub App eigenständig oder im Namen eines Benutzers oder einer Benutzerin handeln. Wenn deine neue GitHub App nicht im Namen eines Benutzers oder einer Benutzerin handeln soll, kannst du die Einstellungen „Benutzer*innen identifizieren und autorisieren“ überspringen. Weitere Informationen findest du unter Informationen zur Authentifizierung mit einer GitHub-App.

  • Du kannst Webhooks verwenden, um deine GitHub App zu benachrichtigen, wenn bestimmte Ereignisse auftreten. Im Gegensatz zu Webhooks für OAuth apps, die du über die API für jedes Repository oder jede Organisation konfigurieren musst, sind Webhooks in GitHub Apps integriert. Wenn du deine GitHub App registrierst, kannst du die Webhookereignisse auswählen, die du empfangen möchtest. Wenn deine OAuth app derzeit mithilfe von Abrufen ermittelt, ob ein Ereignis aufgetreten ist, solltest du stattdessen Webhooks abonnieren, damit deine GitHub App innerhalb des Ratenlimits bleibt. Weitere Informationen findest du unter Verwenden von Webhooks mit GitHub-Apps.

  • Bei einer OAuth app werden Bereiche angefordert, wenn eine Benutzerin deine App autorisiert. Bei einer GitHub App gibst du Berechtigungen in den App-Einstellungen an. Diese Berechtigungen sind präziser als Bereiche und ermöglichen es dir, nur die Berechtigungen auszuwählen, die deine App benötigt. Darüber hinaus werden diese Berechtigungen REST-API-Endpunkten und Webhookereignissen zugeordnet, sodass du leicht bestimmen kannst, welche Berechtigungen deine GitHub App benötigt, um auf einen bestimmten REST-API-Endpunkt zuzugreifen oder einen bestimmten Webhook zu abonnieren. Die Berechtigungen für GraphQL-Anforderungen sind derzeit nicht dokumentiert. Weitere Informationen findest du unter Auswählen von Berechtigungen für eine GitHub-App.

3. Anpassen des Codes für deine App

Nachdem du eine GitHub App registriert hast, musst du den Code der alten OAuth app anpassen, damit diese mit der neuen GitHub App kompatibel ist.

Aktualisieren der Authentifizierung

Du musst den Code deiner App aktualisieren, um die API-Authentifizierung für deine GitHub App zu verarbeiten. Eine GitHub App kann sich auf drei Arten authentifizieren:

Wenn du die offizielle Octokit.js-Bibliothek von GitHub nutzt, kannst du das integrierte App-Objekt zur Authentifizierung verwenden. Beispiele findest du unter Skripterstellung mit der REST-API und JavaScript und Erstellen einer GitHub-App, die auf Webhookereignisse reagiert.

Überprüfen der Ratenlimits

Überprüfe die Unterschiede der Ratenlimits zwischen OAuth apps und GitHub Apps. Für GitHub Apps werden Gleitregeln für Ratenlimits verwendet, die basierend auf der Anzahl der Repositorys und Benutzer*innen in der Organisation erhöht werden können. Weitere Informationen findest du unter Rate limits for GitHub Apps (Ratenbegrenzungen für GitHub-Apps).

Ziehe nach Möglichkeit die Verwendung bedingter Anforderungen und das Abonnieren von Webhooks anstelle von Abfragen in Betracht, damit die Ratenlimits nicht überschritten werden. Weitere Informationen zu bedingten Anforderungen findest du unter Bewährte Methoden für die Verwendung der REST-API. Weitere Informationen zur Verwendung von Webhooks mit deiner GitHub App findest du unter Verwenden von Webhooks mit GitHub-Apps und Erstellen einer GitHub-App, die auf Webhookereignisse reagiert.

Testen des Codes

Teste deine neue GitHub App, um dich zu vergewissern, dass der Code wie erwartet funktioniert.

4. Veröffentlichen der neuen GitHub App

Wenn die Verwendung der neuen GitHub App durch andere Konten möglich sein soll, muss deine App öffentlich sein. Damit deine GitHub App leichter gefunden werden kann, kannst du sie im GitHub Marketplace listen. Weitere Informationen findest du unter Informationen zu GitHub Marketplace für Apps und Öffentlich- oder Privatmachen einer GitHub-App.

5. Auffordern von Benutzer*innen zur Migration

Sobald deine neue GitHub App bereit ist, weise die Benutzerinnen der alten OAuth app an, zur neuen GitHub App zu migrieren. Es gibt keine Möglichkeit, die Benutzerinnen automatisch zu migrieren. Jeder Benutzerin muss die GitHub App selbst installieren und/oder autorisieren.

Als App-Besitzerin solltest du Handlungsaufrufe einrichten, um die Benutzerinnen dazu zu ermutigen, die neue GitHub App zu installieren und zu autorisieren und die Autorisierung für die alte OAuth app zu widerrufen. Auch die Dokumentation und Benutzeroberflächenelemente sollten entsprechend aktualisiert werden.

Auffordern der Benutzer*innen zur Installation der GitHub App

Wenn deine GitHub App eigenständig API-Anforderungen tätigen oder auf Organisations- oder Repositoryressourcen zugreifen soll, muss der oder die Benutzerin deine GitHub App installieren. Wenn eine Benutzerin eine GitHub App für ein Konto oder eine Organisation installiert, wählt dieser aus, auf welche Repositorys die App zugreifen kann, und erteilt der App die angeforderten Organisations- und Repositoryberechtigungen.

Um Benutzer*innen bei der Installation deiner GitHub App zu unterstützen, kannst du einen Link zur Website der App hinzufügen, den diese auswählen können, um die GitHub App zu installieren. Die Installations-URL hat folgendes Format: https://github.com/apps/YOUR_APP_NAME/installations/new. Ersetze YOUR_APP_NAME durch den Platzhalternamen deiner GitHub App. Diesen findest du im Feld „Öffentlicher Link“ auf der Einstellungsseite für deine GitHub App.

Um die Repositorys vorab auszuwählen, auf die deine OAuth app Zugriff hatte, kannst du /permissions und Abfrageparameter an die Installations-URL anfügen. Dadurch können die Benutzer*innen der GitHub App leichter Zugriff auf die Repositorys erteilen, auf die deine OAuth app bereits Zugriff hatte. Die Abfrageparameter lauten:

  • suggested_target_id: Die ID des Benutzers bzw. der Benutzerin oder der Organisation, die deine GitHub App installiert. Dieser Parameter ist erforderlich.
  • repository_ids[]: Die Repository-IDs, die für die Installation ausgewählt werden sollen. Wenn keine angegeben werden, werden alle Repositorys ausgewählt. Die maximale Anzahl von Repositorys, die vorab ausgewählt werden können, beträgt 100. Verwende die Endpunkte Repositorys für den authentifizierten Benutzer auflisten und Organisationsrepositorys auflisten, um eine Liste der Repositorys abzurufen, auf die deine OAuth app Zugriff hat.

Beispiel: https://github.com/apps/YOUR_APP_NAME/installations/new/permissions?suggested_target_id=ID_OF_USER_OR_ORG&repository_ids[]=REPO_A_ID&repository_ids[]=REPO_B_ID

Weitere Informationen zum Installieren von GitHub Apps findest du unter Installieren einer GitHub-App aus dem GitHub Marketplace für dein persönliches Konto, Installieren einer GitHub-App aus dem GitHub Marketplace für deine Organisationen, Installieren einer GitHub-App von einem Drittanbieter und Installieren einer eigenen GitHub-App.

Auffordern von Benutzer*innen zur Autorisierung der App

Wenn deine GitHub App API-Anforderungen im Namen eines Benutzers oder einer Benutzerin tätigen sollen, muss der oder die Benutzerin die App autorisieren. Wenn Benutzerinnen eine App autorisieren, gewähren sie der App die Berechtigung, in ihrem Namen zu handeln, sowie die von der App angeforderten Kontoberechtigungen. Wenn die App in einem Organisationskonto installiert ist, muss jeder Benutzerin innerhalb dieser Organisation die App autorisieren, damit die App in dessen oder deren Namen handeln kann.

Führe die Benutzer*innen durch den Webanwendungs- oder Geräteablauf zur Autorisierung deiner App. Weitere Informationen findest du unter Generieren eines Benutzerzugriffstokens für eine GitHub-App.

Weitere Informationen zur Autorisierung von GitHub Apps findest du unter Autorisieren von GitHub-Apps.

Auffordern von Benutzer*innen zum Widerrufen der Zugriffsberechtigungen von OAuth app

Du solltest deinen Benutzerinnen empfehlen, die Zugriffsberechtigungen der alten OAuth app zu widerrufen. Dadurch wird ein vollständiger Umstieg von der OAuth app erreicht, und die Daten der Benutzerinnen bleiben geschützt. Weitere Informationen findest du unter Überprüfen der autorisierten OAuth-Apps.

Aktualisieren von Benutzeroberflächen oder Dokumentationen

Du solltest alle Benutzeroberflächen oder Dokumentationen im Zusammenhang mit deiner App aktualisieren, um die Änderung von OAuth app in GitHub App widerzuspiegeln.

6. Entfernen der Webhooks für die alte OAuth app

Wenn eine Benutzerin deine GitHub App installiert und Zugriff auf ein Repository gewährt, solltest du alle Webhooks für die alte OAuth app entfernen. Andernfalls reagieren deine neue GitHub App und deine alte OAuth app auf Webhooks für dasselbe Ereignis.

Um Repositorywebhooks zu entfernen, kannst du dem installation_repositories-Webhook mit der added-Aktion lauschen. Wenn deine GitHub App dieses Ereignis empfängt, kannst du die REST-API verwenden, um den Webhook für diese Repositorys für deine OAuth app zu löschen. Weitere Informationen findest du unter Webhook-Ereignisse und -Nutzlasten und unter REST-API-Endpunkte für Repository-Webhooks.

Um Organisationswebhooks zu entfernen, kannst du dem installation-Webhook mit der created-Aktion lauschen. Wenn deine GitHub App dieses Ereignis für eine Organisation empfängt, kannst du die REST-API verwenden, um den Webhook für diese Organisation und die zugehörigen Repositorys für deine OAuth app zu löschen. Weitere Informationen findest du unter Webhook-Ereignisse und -Nutzlasten, REST-API-Endpunkte für Organisationswebhooks und REST-API-Endpunkte für Repository-Webhooks.

7. Löschen der alten OAuth app

Nachdem deine Benutzer*innen zur neuen GitHub App migriert sind, solltest du die alte OAuth app löschen. Dadurch wird der Missbrauch der Anmeldeinformationen für die OAuth app vermieden. Außerdem werden alle verbleibenden Autorisierungen der OAuth app widerrufen. Weitere Informationen findest du unter Löschen einer OAuth-App. Wenn deine OAuth app auf GitHub Marketplace gelistet ist, musst du dich möglicherweise an den GitHub-Support wenden, um deine App zuerst aus dem Marketplace zu entfernen.