Registrieren einer GitHub App aus einem Manifest

Informationen zu GitHub App-Manifeste

Benutzerinnen, die eine GitHub App über ein Manifest registrieren möchten, müssen nur einer URL folgen und die App benennen. Das Manifest enthält die Berechtigungen, Ereignisse und die Webhook-URL, die für die automatische Registrierung der App erforderlich sind. Der Manifest-Fluss erstellt die Registrierung der GitHub App und generiert das Webhook-Geheimnis, den privaten Schlüssel (PEM-Datei), das Client-Geheimnis und die ID der GitHub App. Die Person, die die GitHub App-Registrierung über das Manifest erstellt, ist Besitzerin der GitHub App-Registrierung und kann die Einstellungen der Registrierung bearbeiten sowie die Registrierung löschen oder an eine anderen Person auf GitHub übertragen.

Mithilfe von Probot können Sie die ersten Schritte mit GitHub App Manifesten beginnen oder eine Beispielimplementierung anschauen. Weitere Informationen findest du unter Verwenden von Probot zur Implementierung des GitHub App-Manifestflows.

In den folgenden Szenarien können Sie GitHub App-Manifeste verwenden, um vorkonfigurierte Apps zu registrieren:

• Helfen Sie neuen Teammitgliedern, sich bei der Entwicklung von GitHub Apps schnell zurechtzufinden.
• Erlauben Sie anderen, eine GitHub App mit den GitHub APIs zu erweitern, ohne dass sie eine App konfigurieren müssen.
• Erstellen Sie GitHub App-Referenzdesigns, um sie mit der GitHub Community zu teilen.
• Stellen Sie sicher, dass Sie GitHub Apps in Entwicklungs- und Produktionsumgebungen mit der gleichen Konfiguration bereitstellen.
• Verfolgen von Revisionen an einer GitHub App Konfiguration

Implementierung des GitHub App Manifestflows

Der GitHub App Manifestflow verwendet einen Handshake-Prozess ähnlich dem OAuth-Flow. Der Flow verwendet ein Manifest, um eine GitHub App zu registrieren und erhält einen temporären Token, der zum Abrufen des privaten Schlüssels der App, des Webhook-Geheimnisses und der ID verwendet wird.

Folgen Sie diesen Schritten, um den Manifestflow für GitHub App zu implementieren:

1. Sie leiten Personen zu GitHub um, um eine neue GitHub App zu registrieren.
2. GitHub leitet Personen zurück zu Ihrer Website.
3. Du tauschst den temporären Code zum Abrufen der App-Konfiguration aus.

1. Sie leiten Personen zu GitHub um, um eine neue GitHub App zu registrieren.

Um Personen zur Registrierung einer neuen GitHub App umzuleiten, stellen Sie ihnen einen Link zur Verfügung, der eine Anfrage für ein persönliches Konto oder ein Organisationskonto sendet, wobei GitHub App durch den Namen des Organisationskontos ersetzt wird, in dem die App registriert werden soll.

Sie müssen die Manifestparameter für GitHub App als JSON-kodierte Zeichenfolge in einem Parameter namens . einschließen. Für zusätzliche Sicherheit kannst du auch den Parameter einschließen.

Die Person, die die App registriert, wird auf eine GitHub-Seite mit einem Eingabefeld umgeleitet, in dem der Name der App, den Sie im -Parameter angegeben haben, bearbeitet werden kann. Wenn Sie im -Parameter keinen -Wert einfügen, können Benutzer in diesem Feld ihren eigenen Namen für die App festlegen.

Manifestparameter für GitHub App

Name	Typ	BESCHREIBUNG
name	string	Der Name der GitHub App.
url	string	Erforderlich. Dies ist die Homepage deiner GitHub App.
hook_attributes	object	Die Konfiguration des GitHub App-Webhooks
redirect_url	string	Dies ist die vollständige URL, an die Benutzer*innen umgeleitet werden, nachdem sie die Registrierung einer GitHub App über ein Manifest initiiert haben.
callback_urls	array of strings	Vollständige URL, an die Benutzer*innen nach der Autorisierung einer Installation umgeleitet werden. Du kannst bis zu zehn Rückruf-URLs bereitstellen.
setup_url	string	Dies ist die vollständige URL, an die Benutzer*innen nach der Installation der GitHub App umgeleitet werden, wenn eine zusätzliche Einrichtung erforderlich ist.
description	string	Eine Beschreibung der GitHub App.
public	boolean	Lege diesen Parameter auf fest, wenn deine GitHub App öffentlich verfügbar sein soll, oder auf , wenn nur der Besitzer der App darauf zugreifen darf.
default_events	array	Dies ist die Liste der Ereignisse, die die GitHub App abonniert.
default_permissions	object	Der Satz von Berechtigungen, die von der GitHub App benötigt werden. Das Format des Objekts verwendet den Berechtigungsnamen für den Schlüssel (z. B. ) und den Zugriffstyp für den Wert (z. B. ). Weitere Informationen finden Sie unter AUTOTITLE. Eine Liste der verfügbaren Berechtigungen und deren parametrisierte Namen findest du unter AUTOTITLE.
request_oauth_on_install	boolean	Muss auf festgelegt werden, um Benutzer*innen aufzufordern, die GitHub App nach der Installation zu autorisieren
setup_on_update	boolean	Muss auf festgelegt werden, um Benutzer*innen zur umzuleiten, nachdem sie die Installation deiner GitHub App aktualisiert haben

Das -Objekt verfügt über die folgenden Schlüssel.

Name	Typ	BESCHREIBUNG
url	string	Erforderlich. URL des Servers, an den die -Anforderungen des Webhooks gesendet werden.
active	boolean	Stellt Ereignisdetails bereit, wenn dieser Hook ausgelöst wird. Der Standardwert lautet TRUE.

Parameter

Name	Typ	BESCHREIBUNG
state	string	Eine nicht erratbare zufällige Zeichenfolge. Sie wird verwendet, um vor websiteübergreifenden Anforderungsfälschungen zu schützen.

Beispiele

In diesem Beispiel wird ein Formular auf einer Webseite mit einer Schaltfläche verwendet, die die -Anforderung für ein persönliches Konto auslöst:

<form action="https://github.com/settings/apps/new?state=abc123" method="post">
 Register a GitHub App Manifest: <input type="text" name="manifest" id="manifest"><br>
 <input type="submit" value="Submit">
</form>

<script>
 input = document.getElementById("manifest")
 input.value = JSON.stringify({
   "name": "Octoapp",
   "url": "https://www.example.com",
   "hook_attributes": {
     "url": "https://example.com/github/events",
   },
   "redirect_url": "https://example.com/redirect",
   "callback_urls": [
     "https://example.com/callback"
   ],
   "public": true,
   "default_permissions": {
     "issues": "write",
     "checks": "write"
   },
   "default_events": [
     "issues",
     "issue_comment",
     "check_suite",
     "check_run"
   ]
 })
</script>

In diesem Beispiel wird ein Formular auf einer Webseite mit einer Schaltfläche verwendet, die die -Anforderung für ein Organisationskonto auslöst. Ersetze durch den Namen des Organisationskontos, in dem du die App registrieren möchtest.

<form action="https://github.com/organizations/ORGANIZATION/settings/apps/new?state=abc123" method="post">
 register a GitHub App Manifest: <input type="text" name="manifest" id="manifest"><br>
 <input type="submit" value="Submit">
</form>

<script>
 input = document.getElementById("manifest")
 input.value = JSON.stringify({
   "name": "Octoapp",
   "url": "https://www.example.com",
   "hook_attributes": {
     "url": "https://example.com/github/events",
   },
   "redirect_url": "https://example.com/redirect",
   "callback_urls": [
     "https://example.com/callback"
   ],
   "public": true,
   "default_permissions": {
     "issues": "write",
     "checks": "write"
   },
   "default_events": [
     "issues",
     "issue_comment",
     "check_suite",
     "check_run"
   ]
 })
</script>

2. GitHub leitet Personen zurück zu Ihrer Website.

Wenn die Person auf „GitHub App erstellen“ klickt, leitet GitHub zurück zur vorherigen Seite mit einem temporären Codeparameter. Zum Beispiel:

https://example.com/redirect?code=a180b1a3d263c81bc6441d7b990bae27d4c10679

Wenn Sie einen Parameter bereitgestellt haben, wird dieser auch darin angezeigt. Zum Beispiel:

https://example.com/redirect?code=a180b1a3d263c81bc6441d7b990bae27d4c10679&state=abc123

3. Austauschen des temporären Codes zum Abrufen der App-Konfiguration

Um den Handshake-Prozess abzuschließen, senden Sie das temporäre Token in einer Anfrage an den Endpunkt „Create a GitHub App from a manifest“. Die Antwort enthält die (GitHub App ID), (privater Schlüssel) und . GitHub erstellt automatisch ein Webhook-Geheimnis für die App. Du kannst diese Werte in Umgebungsvariablen auf dem Server der App speichern. Wenn deine App dotenv verwendet, um Umgebungsvariablen zu speichern, speicherst du die Variablen in der dotenv-Datei deiner App.

Dieser Schritt des Manifestflows für GitHub App muss innerhalb einer Stunde abgeschlossen werden.

POST /app-manifests/{code}/conversions

Weitere Informationen zur Antwort des Endpunkts finden Sie unter Erstellen einer GitHub App aus einem Manifest.

Sobald der letzte Schritt des Manifestflows abgeschlossen ist, befindet sich die Person, die die App über den Flow registriert hat, im Besitz einer registrierten GitHub App und kann diese in einem ihrer Konten installieren. Sie kann die App mithilfe der GitHub-APIs erweitern, den Besitz an eine andere Person übertragen oder die App jederzeit löschen.

Implementieren des GitHub App Manifestflows mithilfe von Probot

Probot ist ein Framework basierend auf Node.js, das eine Vielzahl der von allen GitHub Apps benötigten Aufgaben ausführt, wie etwa die Überprüfung von Webhooks oder die Ausführung von Authentifizierungen. Probot implementiert den GitHub App-Manifestfluss und erleichtert so die Erstellung und Freigabe von GitHub App Referenzdesigns für die GitHub Community.

Führe die folgenden Schritte aus, um eine Probot-App zu erstellen, die Sie teilen können:

1. Erstellen Sie eine neue GitHub App.
2. Öffne das erstellte Projekt, und passe die Einstellungen in der Datei an. Probot verwendet die Einstellungen in als Manifestparameter für GitHub App.
3. Füge den benutzerdefinierten Code deiner Anwendung hinzu.
4. Führen Sie die GitHub App lokal aus, oder hosten Sie sie, wo immer Sie wollen. Unter der URL der gehosteten App befindet sich eine Webseite mit der Schaltfläche GitHub App registrieren, auf die Benutzer*innen klicken können, um eine vorkonfigurierte App zu registrieren.

Mithilfe von dotenv erstellt Probot eine und legt die Umgebungsvariablen , und auf die Werte fest, die aus der App-Konfiguration abgerufen wurden.

Hosten deiner App mit Glitch

Sie können eine Beispiel-Probot-App sehen, die Glitch verwendet, um die App zu hosten und freizugeben. Im Beispiel wird die API für Überprüfungen verwendet, und die erforderlichen Ereignisse und Berechtigungen der Überprüfungs-API werden in der Datei ausgewählt. Glitch ist ein Tool, mit dem du deine eigenen Apps „Neu mischen“ kannst. Das Remixen einer App erstellt eine Kopie der App, die von Glitch gehostet und bereitgestellt wird. Um mehr über das Remixen von Glitch-Apps zu erfahren, siehe Über Glitch.