Migrieren von OAuth-Apps zu GitHub Apps

Erfahren Sie mehr über die Vorteile der Migration Ihres OAuth app zu einem GitHub App, und erfahren Sie, wie Sie Ihr OAuth app migrieren.

In diesem Artikel

Vorteile der Migration von OAuth apps zu GitHub Apps

GitHub Apps sind die empfohlene Möglichkeit zur Integration in GitHub. GitHub Apps bieten viele Vorteile gegenüber OAuth apps, einschließlich:

  • Verbesserte Sicherheitsfeatures (z. B. differenzierte Berechtigungen, Optionen für den Repositoryzugriff und kurzlebige Tokens)
  • Möglichkeit, unabhängig von oder im Namen von Benutzenden zu handeln
  • Skalierbare Ratenlimits
  • Integrierte Webhooks

Weitere Informationen finden Sie unter Informationen zum Erstellen von GitHub Apps.

Konvertieren einer OAuth app in eine GitHub App

Die folgenden Schritte bieten eine Übersicht über die Migration von einer OAuth app zu einer GitHub App. Die genauen Schritte hängen von deiner App ab.

1. Überprüfen Ihrer OAuth app

Machen Sie sich erneut mit dem Code für Ihr OAuth app vertraut. Die API-Anfragen, die Ihre OAuth app stellt, helfen Ihnen bei der Entscheidung, welche Berechtigungen Sie für Ihre GitHub App auswählen sollten.

Darüber hinaus gibt es einige REST-API-Endpunkte, die für OAuth appsnicht verfügbar sind. Stellen Sie sicher, dass alle von Ihnen verwendeten REST-Endpunkte für GitHub Apps verfügbar sind, indem Sie Für GitHub App-Installationszugriffstoken verfügbare Endpunkte überprüfen.

2. Registrieren einer GitHub App

Registrieren Sie ein neues GitHub App. Weitere Informationen finden Sie unter Registrieren einer GitHub-App.

Im Vergleich zu einem OAuth app, haben Sie mehr Kontrolle über GitHub App Einstellungen. Weitere wichtige Vorteile sind:

  • Im Gegensatz zu einem OAuth app, der immer im Namen eines Benutzers handelt, können Sie Ihr GitHub App veranlassen, im eigenen Namen oder im Namen eines Benutzers Aktionen auszuführen. Wenn Sie nicht möchten, dass Ihr Neues GitHub App Aktionen im Namen eines Benutzers ausführt, können Sie die Einstellungen "Identifizieren und Autorisieren von Benutzern" überspringen. Weitere Informationen finden Sie unter Informationen zur Authentifizierung mit einer GitHub-App.

  • Sie können Webhooks verwenden, um GitHub App zu benachrichtigen, wenn bestimmte Ereignisse eintreten. Im Gegensatz zu Webhooks für OAuth apps, die Sie über die API für jedes Repository oder jede Organisation konfigurieren müssen, sind Webhooks in GitHub Apps integriert. Wenn Sie Ihre GitHub AppRegistrierung durchführen, können Sie die Webhook-Ereignisse auswählen, die Sie empfangen möchten. Außerdem sollten Sie, wenn Ihr OAuth app derzeit Polling verwendet, um festzustellen, ob ein Ereignis eingetreten ist, stattdessen Webhooks abonnieren, damit Ihr GitHub App innerhalb des Ratenlimits bleibt. Weitere Informationen finden Sie unter Verwenden von Webhooks mit GitHub Apps.

  • Mit einem OAuth app fordern Sie Berechtigungsbereiche an, wenn ein Benutzer Ihre App autorisiert. Mit einem GitHub App, geben Sie 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 Webhook-Ereignissen zugeordnet, sodass Sie ganz einfach bestimmen können, welche Berechtigungen Sie GitHub App benötigen, 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 finden Sie unter Auswählen von Berechtigungen für eine GitHub App.

3. Anpassen des Codes für deine App

Nachdem Sie einen GitHub Appregistriert haben, passen Sie den Code von Ihrem alten OAuth app an, um mit Ihrem neuen GitHub Appzu arbeiten.

Aktualisieren der Authentifizierung

Sie müssen den Code Ihrer App aktualisieren, um die API-Authentifizierung für Ihre GitHub AppApp zu verarbeiten. Eine GitHub App kann auf drei Arten authentifiziert werden:

Wenn Sie die offizielle Octokit.js-Bibliothek verwenden GitHub, können Sie das integrierte App Objekt verwenden, um sich zu authentifizieren. Beispiele findest du unter Skripterstellung mit der REST-API und JavaScript und Erstellen einer GitHub-App, die auf Webhook-Ereignisse reagiert.

Überprüfen der Ratenlimits

Überprüfen Sie die Unterschiede bei den Ratenbegrenzungen zwischen OAuth apps und GitHub Apps. GitHub Apps Verwenden Sie Gleitregeln für Zinslimits, die basierend auf der Anzahl der Repositorys und der Anzahl der Benutzer in der Organisation erhöht werden können. Weitere Informationen finden Sie unter Preisbeschränkungen 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 Ihrem GitHub App finden Sie in Verwenden von Webhooks mit GitHub Apps und Erstellen einer GitHub-App, die auf Webhook-Ereignisse reagiert.

Testen des Codes

Testen Sie Das neue GitHub App , um sicherzustellen, dass Ihr Code wie erwartet funktioniert.

4. Machen Sie Ihr neues GitHub App bekannt

Wenn Sie möchten, dass andere Konten Ihr neues GitHub AppKonto verwenden können, stellen Sie sicher, dass Ihre App öffentlich ist.Weitere Informationen finden Sie unter Erstellen einer GitHub App öffentlich oder privat.

5. Auffordern von Benutzer*innen zur Migration

Sobald Ihr neues GitHub App bereit ist, weisen Sie die Benutzer Ihres alten OAuth app an, auf Ihr neues GitHub App zu migrieren. Es gibt keine Möglichkeit, die Benutzer*innen automatisch zu migrieren. Jeder Benutzer muss Ihre GitHub App selbst installieren und/oder autorisieren.

Als App-Besitzer sollten Sie Handlungsaufrufe einbeziehen, um Ihre Benutzer aufzufordern, die neue GitHub App Autorisierung zu installieren/zu autorisieren und die Autorisierung für die alte OAuth appzu widerrufen. Auch die Dokumentation und Benutzeroberflächenelemente sollten entsprechend aktualisiert werden.

Benutzer dazu auffordern, Ihr GitHub App zu installieren

Wenn Sie möchten, dass Ihre GitHub App API-Anfragen in eigenem Namen stellt oder auf Organisations- oder Repository-Ressourcen zugreift, muss der Benutzer Ihre GitHub App installieren. Wenn ein Benutzer ein GitHub App in seinem Konto oder seiner Organisation installiert, wählt er aus, auf welche Repositorys die App zugreifen kann, und erteilt der App die von ihr angeforderten Organisations- und Repository-Berechtigungen.

Um Ihren Benutzern die Installation Ihres GitHub App zu erleichtern, können Sie auf der Webseite Ihrer App einen Link hinzufügen, über den Benutzer das GitHub App installieren können. Die Installations-URL hat folgendes Format: http(s)://HOSTNAME/github-apps/YOUR_APP_NAME/installations/new. Ersetzen Sie YOUR_APP_NAME durch den als Slug formatierten Namen Ihrer GitHub App, den Sie im Feld „Öffentlicher Link“ auf der Einstellungsseite für Ihre GitHub App finden.

Um beliebige Repositorys, auf die Ihr OAuth app Zugriff hatte, vorab auszuwählen, können Sie der Installations-URL /permissions und Abfrageparameter anhängen. Dies hilft Benutzern, Ihren GitHub App Zugriff auf Repositorys zu gewähren, auf die Ihr OAuth app bereits Zugriff hat. Die Abfrageparameter lauten:

  • suggested_target_id: Die ID des Benutzers oder der Organisation, der bzw. die Ihr 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. Um eine Liste von Repositories abzurufen, auf die OAuth app Zugriff hat, verwenden Sie die Endpunkte Repositories für den authentifizierten Benutzer auflisten und Organisations-Repositories auflisten.

Beispiel: http(s)://HOSTNAME/github-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 zur Installation GitHub Appsfinden Sie unter Installieren einer GitHub-App von einem Drittanbieter und Installieren Ihrer eigenen GitHub App.

Auffordern von Benutzer*innen zur Autorisierung der App

Wenn Ihr GitHub App API-Anfragen im Namen eines Benutzers senden soll, muss der Benutzer 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 Benutzer*in 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 finden Sie unter Generieren eines Benutzerzugriffstokens für eine GitHub App.

Weitere Informationen zur Autorisierung GitHub Appsfinden Sie unter Autorisieren von GitHub Apps.

Ermutigen Sie Ihre Nutzer, ihren Zugriff OAuth app zu widerrufen.

Sie sollten Ihre Benutzer auch dazu ermutigen, den Zugriff für Ihre alte OAuth app zu widerrufen. Dies wird Ihnen helfen, vollständig von Ihrem OAuth app zu migrieren, und dazu beitragen, die Daten Ihrer Nutzer sicher zu halten. Weitere Informationen finden Sie unter Überprüfen der autorisierten OAuth-Apps.

Aktualisieren von Benutzeroberflächen oder Dokumentationen

Sie sollten jede Benutzeroberfläche oder Dokumentation im Zusammenhang mit Ihrer App aktualisieren, um die Änderung von einem OAuth app zu einem GitHub App widerzuspiegeln.

6. Entfernen von Webhooks für Ihre alte OAuth app

Wenn ein Benutzer Ihre GitHub App installiert und Zugriff auf ein Repository gewährt, sollten Sie alle Webhooks für Ihre alte OAuth app entfernen. Wenn Ihre neue GitHub App und Ihre alte OAuth app auf Webhooks für dasselbe Ereignis reagieren, kann der Benutzer doppelte Reaktionen feststellen.

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

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

7. Löschen Sie Ihre alte OAuth app

Nachdem Ihre Benutzer zu Ihrem neuen GitHub Appmigriert haben, sollten Sie Die alte OAuth applöschen. Dadurch wird verhindert, dass die Anmeldeinformationen von OAuth app missbraucht werden. Mit dieser Aktion werden auch alle verbleibenden Autorisierungen von OAuth app widerrufen. Weitere Informationen finden Sie unter Löschen einer OAuth-App. Wenn Ihr OAuth app auf GitHub Marketplace aufgeführt ist, müssen Sie sich möglicherweise zuerst an GitHub-Support wenden, um Ihre App aus dem Marktplatz zu entfernen.