Registrieren einer GitHub App aus einem Manifest

Informationen zu GitHub App Manifesten

Wenn jemand ein GitHub App Manifest registriert, muss er 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 Manifestfluss erstellt die GitHub App Registrierung und generiert den geheimen Webhook-Schlüssel, den privaten Schlüssel (PEM-Datei), den geheimen Clientschlüssel und die GitHub App ID der App. Die Person, die die GitHub App Registrierung aus dem Manifest erstellt, besitzt die GitHub App Registrierung und kann entscheiden, die Einstellungen der Registrierung zu bearbeiten, sie zu löschen oder an eine andere Person GitHubzu übertragen.

Sie können Probot verwenden, um mit GitHub App Manifesten zu beginnen oder eine Beispielimplementierung anzuzeigen. Siehe Verwendung von Probot zur Implementierung des GitHub App Manifest-Flows, um mehr zu erfahren.

Hier sind einige Szenarien, in denen Sie Manifeste verwenden GitHub App können, um vorkonfigurierte Apps zu registrieren:

• Helfen Sie neuen Teammitgliedern, sich schnell in die Entwicklung von GitHub Apps einzuarbeiten.
• Ermöglichen Sie es anderen, ein GitHub App mit den GitHub APIs zu erweitern, ohne dass eine App konfiguriert werden muss.
• 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 derselben Konfiguration bereitstellen.
• Verfolgen von Überarbeitungen in der GitHub App Konfiguration.

Implementierung des GitHub App Manifest-Flows

Der GitHub App Manifestflow verwendet einen Handshake-Prozess ähnlich dem OAuth-Flow. Der Fluss verwendet ein Manifest, um sich zu registrieren GitHub App und erhält ein temporäres code, das verwendet wird, um den privaten Schlüssel, das Webhook-Geheimnis und die ID der App abzurufen.

Führen Sie die folgenden Schritte aus, um den GitHub App Manifestfluss zu implementieren:

1. Personen werden dorthin umgeleitet, um GitHub ein neues 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.

Sie leiten Personen um zu GitHub, um ein neues GitHub App zu registrieren.

Um Personen zur Registrierung eines neuen GitHub AppWeiterzuleiten, stellen Sie einen Link bereit, über den sie klicken können. Dadurch wird 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 gesendet, indem Sie den Namen des Organisationskontos ORGANIZATION ersetzen, bei dem die App registriert wird.

Sie müssen die GitHub App Manifestparameter als JSON-enkodierte Zeichenfolge in einem Parameter mit dem Namen manifest einschließen. Für zusätzliche Sicherheit kannst du auch einen stateParameter einschließen.

Die Person, die die App registriert, wird zu einer GitHub Seite umgeleitet, auf der sie in einem Eingabefeld den Namen der App bearbeiten kann, die im manifest-Parameter enthalten ist. Enthält der name-Parameter keinen manifest-Wert, kann in diesem Feld ein beliebiger Name eingetragen werden.

          GitHub App Manifest-Parameter

Name	Typ	BESCHREIBUNG
name	string	Der Name des GitHub App.
url	string

          **Erforderlich.** Die Homepage Ihrer GitHub App.

hook_attributes | object | Die Konfiguration des GitHub App-Webhooks. redirect_url | string | Die vollständige URL, zu der umgeleitet werden soll, nachdem ein Benutzer die Registrierung eines GitHub App aus einem Manifest initiiert hat. 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 | Eine vollständige URL, um Benutzer nach der Installation Ihrer GitHub App weiterzuleiten, falls ein zusätzliches Setup erforderlich ist. description | string | Eine Beschreibung des GitHub App. public | boolean | Legen Sie fest, true wann Ihre GitHub App App für die Öffentlichkeit verfügbar ist oder false wenn sie nur für den Besitzer der App zugänglich ist. default_events | array | Die Liste der Ereignisse, die GitHub App abonniert werden. default_permissions | object | Die Berechtigungen, die für die GitHub App erforderlich sind. 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. Eine Liste der verfügbaren Berechtigungen und deren parametrisierte Namen findest du unter Verwalten deiner persönlichen Zugriffstoken. request_oauth_on_install | boolean | Setzen Sie auf true, um den Benutzer aufzufordern, das GitHub App zu autorisieren, nachdem das GitHub App installiert wurde. setup_on_update | boolean | Stellen Sie true ein, um Benutzer nach dem Aktualisieren Ihrer Installation GitHub App an setup_url umzuleiten.

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 ErstellenGitHub App klickt, leitet GitHub zurück zu 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. Zum Beispiel:

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

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

Um den Handshake abzuschließen, senden Sie den temporären code in einer POST-Anforderung an den Create a GitHub App from a manifest-Endpunkt. Die Antwort enthält die id (GitHub App-ID), pem (privaten Schlüssel) und webhook_secret. GitHub erstellt automatisch einen Webhook-Geheimschlüssel 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.

Sie müssen diesen Schritt des GitHub App Manifest-Prozesses innerhalb einer Stunde ausführen.

POST /app-manifests/{code}/conversions

Weitere Informationen zur Antwort des Endpunkts finden Sie unter Ein GitHub App aus einem Manifest erstellen.

Wenn der letzte Schritt im Manifestablauf abgeschlossen ist, ist die Person, die die App aus dem Fluss registriert, ein Besitzer eines registrierten GitHub App Kontos, das sie auf einem ihrer Konten installieren können. Sie können die App mithilfe der GitHub APIs erweitern, den Besitz an eine andere Person übertragen oder jederzeit löschen.

Verwendung von Probot zur Implementierung des GitHub App-Manifestflusses

          [Probot](https://probot.github.io/) ist ein Framework, das mit [Node.js](https://nodejs.org/) erstellt wurde, die viele der aufgaben ausführt, die von allen GitHub Appsbenötigt werden, z. B. das Überprüfen von Webhooks und die Authentifizierung. Probot implementiert den [GitHub App Manifestprozess](#implementing-the-github-app-manifest-flow) und erleichtert das Erstellen und Teilen GitHub App von Referenzdesigns mit der GitHub Community.

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

1.        [Generieren Sie ein neues GitHub App](https://probot.github.io/docs/development/#generating-a-new-app).
   

2. Öffne das erstellte Projekt, und passe die Einstellungen in der Datei app.yml an. Probot verwendet die Einstellungen in app.yml als die GitHub App Manifestparameter.
3. Füge den benutzerdefinierten Code deiner Anwendung hinzu.

4.        [Führen Sie GitHub App lokal aus](https://probot.github.io/docs/development/#running-the-app-locally) oder hosten Sie es, wo immer Sie möchten. Wenn Sie zur URL der gehosteten App navigieren, finden Sie eine Webseite mit einer Schaltfläche " **Registrieren GitHub App** ", auf die Benutzer 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 Werte fest, die aus der App-Konfiguration abgerufen wurden.