Informationen zu GitHub App-Manifeste
Note
GitHub App-Manifeste sind für unternehmenseigene GitHub Apps nicht verfügbar.
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 finden Sie unter „Implementieren des GitHub App Manifestflows mithilfe von Probot“.
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.
Note
Alle drei Schritte des Manifestflows für GitHub App müssen innerhalb von einer Stunde abgeschlossen werden.
Folgen Sie diesen Schritten, um den Manifestflow für GitHub App zu implementieren:
- Sie leiten Personen zu GitHub um, um eine neue GitHub App zu registrieren.
- GitHub leitet Personen zurück zu Ihrer Website.
- 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 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 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.
Hinweis: Dieser Endpunkt weist eine Ratenbegrenzung auf. Weitere Informationen zum Abrufen des Status deiner Ratenbegrenzung findest du unter Ratenbegrenzungen.
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:
- Generieren Sie eine neue GitHub App.
- Öffne das erstellte Projekt, und passe die Einstellungen in der Datei
app.yml
an. Probot verwendet die Einstellungen inapp.yml
als Manifestparameter für GitHub App. - Füge den benutzerdefinierten Code deiner Anwendung hinzu.
- 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.