Registrieren einer GitHub-App über ein Manifest

Informationen zu Manifesten für GitHub-Apps

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 kannst du erste Erfahrungen mit Manifesten für GitHub-Apps sammeln oder eine Beispielimplementierung anzeigen. Weitere Informationen findest du unter Implementieren des Manifestflows für GitHub-Apps mithilfe von Probot.

In den folgenden Szenarios können Manifeste für GitHub-Apps zum Registrieren von vorkonfigurierten Apps nützlich sein:

• Du möchtest neuen Teammitgliedern den Einstieg in die Entwicklung von GitHub-Apps erleichtern.
• Du möchtest anderen Personen die Erweiterung einer GitHub-App mithilfe von GitHub-APIs ermöglichen, ohne dass diese die App konfigurieren müssen.
• Du möchtest Referenzentwürfe für GitHub-Apps erstellen und diese für die GitHub-Community freigeben.
• Du möchtest sicherstellen, dass die in Entwicklungs- und Produktionsumgebungen bereitgestellten GitHub-Apps dieselbe Konfiguration aufweisen.
• Du möchtest Bearbeitungen von Konfigurationen einer GitHub-App nachverfolgen.

Implementieren des Manifestflows für GitHub-Apps

Der Manifestflow für GitHub-Apps verwendet ähnlich wie der OAuth-Flow einen Handshake-Prozess. Der Flow verwendet ein Manifest zur Registrierung einer GitHub-App und erhält einen temporären code-Parameter, um den privaten Schlüssel, das Webhookgeheimnis und die ID der App abzurufen.

Führe die folgenden Schritte aus, um den Manifestflow für GitHub-Apps zu implementieren:

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

1. Leite Personen zu GitHub um, damit diese eine neue GitHub-App registrieren.

Stelle Personen, die du zum Registrieren einer neuen GitHub-App weiterleiten möchtest, einen Link bereit, der eine POST-Anforderung für ein persönliches Konto an https://github.com/settings/apps/new bzw. für ein Organisationskonto an https://github.com/organizations/ORGANIZATION/settings/apps/new sendet. Ersetze ORGANIZATION durch den Namen des Organisationskontos, in dem die App registriert werden soll.

Stelle die Manifestparameter für GitHub-Apps als JSON-Zeichenfolge in einem Parameter mit dem Namen manifest bereit. 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 du im manifest-Parameter bereitgestellt hast, bearbeitet werden kann. Enthält der manifest-Parameter keinen name-Wert, kann in diesem Feld ein beliebiger Name eingetragen werden.

Manifestparameter für GitHub-Apps

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	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 findest du 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 die Benutzer*innen zurück zu deiner Website

Durch Klicken auf GitHub-App erstellen wird die Person von GitHub wieder zu redirect_url mit einem temporären code-Parameter in einem Codeparameter zurückgeleitet. 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

Sende den temporären code-Parameter in einer POST-Anforderung an den Endpunkt Erstellen einer GitHub-App aus einem Manifest, um den Handshake-Prozess abzuschließen. Die Antwort enthält id (die ID der GitHub-App), pem (den privaten Schlüssel) und webhook_secret. GitHub erstellt automatisch ein 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-Apps muss innerhalb von einer Stunde abgeschlossen werden.

POST /app-manifests/{code}/conversions

Weitere Informationen zur Antwort des Endpunkts findest du 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 Manifestflows für GitHub-Apps 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 Manifestflow für GitHub-Apps und erleichtert die Erstellung von Referenzentwürfen für GitHub-Apps und ihre Freigabe für die GitHub-Community.

Führe die folgenden Schritte aus, um eine Probot-App zur Freigabe zu erstellen:

1. Erstelle eine neue GitHub-App.
2. Öffne das erstellte Projekt, und passe die Einstellungen in der Datei app.yml an. Diese Einstellungen in app.yml verwendet Probot als Manifestparameter für GitHub-Apps.
3. Füge den benutzerdefinierten Code deiner Anwendung hinzu.
4. Führe die GitHub-App lokal aus, oder hoste sie an einem beliebigen Standort. 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.