Registrieren einer GitHub-App über ein 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 Manifestflow erstellt die Registrierung der GitHub App und generiert das Webhookgeheimnis, den privaten Schlüssel (PEM-Datei), den geheimen Clientschlüssel 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 einer GitHub App zu registrieren, und erhält einen temporären code, der zum Abrufen des privaten Schlüssels der App, des Webhookgeheimnisses 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 POST Anforderung an https://github.com/settings/apps/new für ein persönliches Konto oder an https://github.com/organizations/ORGANIZATION/settings/apps/new für ein Organisationskonto sendet, wobei ORGANIZATION 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-Zeichenfolge in einem Parameter mit dem Namen manifest einschließen. Für zusätzliche Sicherheit kannst du auch den Parameter state 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 manifest-Parameter angegeben haben, bearbeitet werden kann. Enthält der manifest-Parameter keinen name-Wert, kann in diesem Feld ein beliebiger Name eingetragen werden.

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 true fest, wenn deine GitHub App öffentlich verfügbar sein soll, oder auf false, 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. issues) und den Zugriffstyp für den Wert (z. B. write). Weitere Informationen finden Sie unter Auswählen von Berechtigungen für eine GitHub-App.
request_oauth_on_install	boolean	Muss auf true festgelegt werden, um Benutzer*innen aufzufordern, die GitHub App nach der Installation zu autorisieren
setup_on_update	boolean	Muss auf true festgelegt werden, um Benutzer*innen zur setup_url umzuleiten, nachdem sie die Installation deiner GitHub App aktualisiert haben

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

Name	Typ	BESCHREIBUNG
url	string	Erforderlich. URL des Servers, an den die POST-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 POST-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 POST-Anforderung für ein Organisationskonto auslöst. Ersetze ORGANIZATION 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 redirect_url mit einem temporären code in einem Codeparameter. Zum Beispiel:

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

Wenn du einen state-Parameter bereitgestellt hast, wird dieser auch in redirect_url angezeigt. 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 den temporären code in einer POST-Anforderung an den Erstellen einer GitHub App aus einem Manifest Endpunkt. Die Antwort enthält die id (GitHub App ID), pem (privater Schlüssel) und webhook_secret. GitHub erstellt automatisch einen Webhookgeheimnis für die App. Du kannst diese Werte in Umgebungsvariablen auf dem Server der App speichern. Verwendet deine App zum Speichern der Umgebungsvariablen z. B. dotenv, speicherst du die Variablen in der .env-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, ist die Person, die die App über das Manifest registriert hat, der Besitzer bzw. die Besitzerin einer registrierten GitHub App und kann diese in einem beliebigen persönlichen Repository 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 zur Freigabe zu erstellen:

1. Generieren Sie eine neue GitHub App.
2. Öffne das erstellte Projekt, und passe die Einstellungen in der Datei app.yml an. Probot verwendet die Einstellungen in app.yml 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 .env-Datei und legt die Umgebungsvariablen APP_ID, PRIVATE_KEY und WEBHOOK_SECRET auf die Wert fest, die aus der App-Konfiguration abgerufen wurden.

Hosten deiner App mit Glitch

In der Probot-Beispiel-App wird die App mit Glitch gehostet und freigegeben. Im Beispiel wird die API für Überprüfungen verwendet, und die erforderlichen Ereignisse und Berechtigungen der Überprüfungs-API werden in der Datei app.yml ausgewählt. Glitch ist ein Tool, mit dem du deine eigenen Apps „Neu mischen“ kannst. Dabei wird eine Kopie der App erstellt, die Glitch hostet und bereitstellt. Weitere Informationen zu den Funktionen von Glitch-Apps findest du unter Informationen zu Glitch.