Schnellstartanleitung zum Erstellen von -Apps

Mit Apps kannst du Prozesse automatisieren oder andere Plattformen in integrieren. Weitere Informationen findest du unter Informationen zum Erstellen von -Apps.

In dieser Schnellstartanleitung wird beschrieben, wie du schnell eine App erstellst. Wenn ein Pull Request in einem Repository geöffnet wird, auf das der App Zugriff gewährt wurde, fügt die App einen Kommentar zum Pull Request hinzu.

In dieser Schnellstartanleitung wird vorab geschriebener Code verwendet, um dir den Einstieg zu erleichtern. Ein ausführlicheres Tutorial als Unterstützung beim Schreiben des Codes findest du unter Erstellen einer -App, die auf Webhookereignisse reagiert.

Dein Computer oder Codespace muss die Node.js-Version 12 oder höher verwenden. Weitere Informationen findest du unter Node.js.

Um dir den Einstieg zu erleichtern, haben wir Code geschrieben, den du verwenden kannst. Weitere Informationen dazu, wie du den Code selbst schreibst, findest du unter Erstellen einer -App, die auf Webhookereignisse reagiert.

1. Klone das Repository /-app-js-sample. Weitere Informationen finden Sie unter Ein Repository klonen. Du kannst einen lokalen Klon oder Codespaces verwenden.
2. Navigiere in einem Terminalfenster zu dem Verzeichnis, in dem dein Klon gespeichert ist.
3. Führe npm install aus, um die Abhängigkeiten zu installieren.

Um deine App lokal zu entwickeln, kannst du eine Webhook-Proxy-URL verwenden, um Webhooks von an deinen Computer oder Codespace weiterzuleiten. In dieser Schnellstartanleitung wird „Smee.io“ verwendet, um eine Webhook-Proxy-URL bereitzustellen und Webhooks weiterzuleiten.

1. Navigiere im Browser zu https://smee.io/.
2. Klicke auf Neuen Kanal starten.
3. Kopiere die vollständige URL unter „Webhook-Proxy-URL“. Du verwendest diese URL in einem späteren Schritt.

Die folgenden Schritte führen dich durch die Konfiguration der App-Einstellungen, die für diese Schnellstartanleitung erforderlich sind. Weitere Informationen zu den Einstellungen findest du unter Registrieren einer -App.

1. Klicke auf in der oberen rechten Ecke einer beliebigen Seite auf dein Profilfoto.
2. Navigieren Sie zu den Einstellungen für Ihr Konto.
   • Klicken Sie bei einer App, die zu einem persönlichen Konto gehört, auf Einstellungen.
   • Für eine App im Besitz einer Organisation:
     1. Klicke Sie auf Ihre Organisationen.
     2. Klicke dann rechts neben der Organisation auf Einstellungen.
3. Klicke auf der linken Seitenleiste auf Entwicklereinstellungen.
4. Klicke auf der linken Randleiste auf Apps .
5. Klicken Sie auf Neue App.
6. Geben Sie unter „Name der App“ einen Namen für Ihre App ein. Beispielsweise USERNAME-quickstart-app, wobei USERNAME dein -Benutzername ist.
7. Gibt unter „Homepage-URL“ Folgendes ein: https://.com//-app-js-sample#readme.
8. Überspringe für diesen Schnellstart die Abschnitte „Identifizieren und Autorisieren von Benutzern“ und „Nach der Installation“. Weitere Informationen zu diesen Einstellungen findest du unter Registrieren einer -App.
9. Stelle sicher, dass unter „Webhooks“ die Option Aktiv ausgewählt ist.
10. Gib unter „Webhook-URL“ deine Webhook-Proxy-URL von früher ein. Weitere Informationen findest du unter Schritt 2: Abrufen einer Webhookproxy-URL.
11. Gib unter „Webhookgeheimnis“ eine zufällige Zeichenfolge ein. Du wirst diese Zeichenfolge später noch verwenden.
12. Wähle unter „Repositoryberechtigungen“ neben „Pull Requests“ die Option Lesen & Schreiben aus.
13. Wähle unter „Ereignisse abonnieren“ die Option Pull Request aus.
14. Wählen Sie unter „Wo kann diese App installiert werden?“ die Option Nur in diesem Konto aus.
15. Klicken Sie auf App erstellen.

In dieser Schnellstartanleitung speicherst du die Informationen deiner App für Identifizierung und Anmeldung als Umgebungsvariablen in einer .env-Datei. Wenn du deine App bereitstellst, musst du die Art und Weise ändern, in der die Anmeldeinformationen gespeichert werden. Weitere Informationen findest du unter Bereitstellen deiner App.

Stelle sicher, dass du dich auf einem sicheren Computer befindest, bevor du diese Schritte ausführst, da du deine Anmeldeinformationen lokal speicherst.

Dein geklontes Repository enthält .env in der .gitignore-Datei. Dadurch verhinderst du, dass du versehentlich die Anmeldeinformationen deiner App committest. Weitere Informationen zu .gitignore-Dateien findest du unter Ignorieren von Dateien.

1. Navigiere zu dem Verzeichnis, in dem dein Klon von /-app-js-sample gespeichert ist.

2. Erstelle eine Datei namens .env auf der obersten Ebene dieses Verzeichnisses.

3. Füge der .env-Datei den folgenden Inhalt hinzu. Ersetze YOUR_HOSTNAME durch den Namen von Ihre Enterprise Server-Instance. Du aktualisierst die anderen Werte in einem späteren Schritt.

   Text

   APP_ID="YOUR_APP_ID"
   WEBHOOK_SECRET="YOUR_WEBHOOK_SECRET"
   PRIVATE_KEY_PATH="YOUR_PRIVATE_KEY_PATH"
   HOSTNAME="YOUR_HOSTNAME"
   

Wenn du die App-Einstellungen nach dem Erstellen der App verlassen hast, wechsle jetzt zur Einstellungsseite für deine App:

1. Klicke auf in der oberen rechten Ecke einer beliebigen Seite auf dein Profilfoto.

2. Navigieren Sie zu den Einstellungen für Ihr Konto.

   • Klicken Sie bei einer App, die zu einem persönlichen Konto gehört, auf Einstellungen.
   • Für eine App im Besitz einer Organisation:
     1. Klicke Sie auf Ihre Organisationen.
     2. Klicken Sie rechts neben der Organisation auf Einstellungen.
   • Für eine App im Besitz eines Unternehmens:
     1. Klicken Sie auf Enterprise-Einstellungen.

3. Klicke auf der linken Seitenleiste auf Entwicklereinstellungen.

4. Klicke auf der linken Randleiste auf Apps .

5. Klicke neben dem Namen deiner App auf Bearbeiten.

1. Suche auf der Einstellungenseite deiner App neben „App-ID“ die App-ID für deine App.
2. Ersetze in deiner .env-Datei YOUR_APP_ID durch die App-ID deiner App.
3. Klicke auf der Einstellungenseite deiner App unter „Private Schlüssel“ auf Privaten Schlüssel generieren. Es wird ein privater Schlüssel im PEM-Format auf deinen Computer heruntergeladen. Weitere Informationen finden Sie unter Verwalten privater Schlüssel für -Apps.
4. Wenn du einen Codespace verwendest, verschiebe die heruntergeladene PEM-Datei in deinen Codespace, damit dein Codespace auf die Datei zugreifen kann.
5. Ersetze in deiner .env-Datei YOUR_PRIVATE_KEY_PATH durch den vollständigen Pfad zu deinem privaten Schlüssel, einschließlich der .pem-Erweiterung.
6. Ersetze in deiner .env-Datei YOUR_WEBHOOK_SECRET durch das Webhookgeheimnis für deine App. Wenn du dein Webhookgeheimnis vergessen hast, klicke unter „Webhookgeheimnis (optional)“ auf Geheimnis ändern. Gib ein neues Geheimnis ein, und klicke dann auf Änderungen speichern.

Damit deine App einen Kommentar zu Pull Requests in einem Repository hinterlassen kann, muss sie in dem Konto installiert werden, das das Repository besitzt, und ihr muss Zugriff auf dieses Repository gewährt werden. Da deine App privat ist, kann sie nur auf dem Konto installiert werden, das Besitzer der App ist.

1. Erstelle in dem Konto, das Besitzer der von dir erstellten App ist, ein neues Repository zum Installieren der App. Weitere Informationen finden Sie unter Ein neues Repository erstellen.
2. Wenn du die App-Einstellungen nach dem Erstellen der App verlassen hast, wechsle jetzt zur Einstellungsseite für deine App. Weitere Informationen findest du unter Navigieren zu deinen App-Einstellungen.
3. Klicke auf Öffentliche Seite.
4. Klicke auf Installieren.
5. Wähle Nur Repositorys auswählen aus.
6. Wähle das Dropdownmenü Repositorys auswählen aus, und klicke auf das Repository, das du am Anfang dieses Abschnitts ausgewählt hast.
7. Klicke auf Installieren.

Zum Testen verwendest du deinen Computer oder Codespace als Server. Deine App ist nur dann aktiv, wenn dein Server ausgeführt wird.

1. Navigiere in einem Terminalfenster zu dem Verzeichnis, in dem dein Klon von /-app-js-sample gespeichert ist.

2. Führe npx smee -u WEBHOOK_PROXY_URL -t http://localhost:3000/api/webhook aus, um weitergeleitete Webhooks von „Smee.io“ zu empfangen. Ersetze WEBHOOK_PROXY_URL durch deine Webhook-Proxy-URL. Wenn du deine URL vergessen hast, findest du sie im Feld "Webhook-URL" auf der Einstellungenseite deiner App.

   Ungefähr folgende Ausgabe sollte angezeigt werden. WEBHOOK_PROXY_URL ist dabei deine Webhook-Proxy-URL:

   Forwarding WEBHOOK_PROXY_URL to http://localhost:3000/api/webhook
   Connected WEBHOOK_PROXY_URL
   

3. Navigiere in einem zweiten Terminalfenster zu dem Verzeichnis, in dem dein Klon von /-app-js-sample gespeichert ist.

4. npm run server ausführen. Auf deinem Terminal sollte Server is listening for events at: http://localhost:3000/api/webhook angezeigt werden.

Dein Server wird jetzt ausgeführt und empfängt weitergeleitete Webhookereignisse. Teste deine App, indem du einen Pull Request öffnest.

1. Öffne einen Pull Request für das Repository, das du in Schritt 5: Installieren der App erstellt hast. Weitere Informationen finden Sie unter Erstellen eines Pull Requests.
2. Navigiere zu deiner Webhook-Proxy-URL auf „smee.io“. Es sollte ein pull_request-Ereignis angezeigt werden. Dies zeigt, dass beim Erstellen eines Pull Requests erfolgreich ein Pull Request-Ereignis gesendet hat.
3. In dem Terminal, in dem du npm run server ausgeführt hast, sollte Ähnliches wie „Pull Request-Ereignis für #1 empfangen“ angezeigt werden, wobei die ganze Zahl nach # die Nummer des Pull Requests ist, den du geöffnet hast.
4. Auf der Zeitachse deines Pull Requests sollte ein Kommentar deiner App angezeigt werden. Der Kommentar verwendet den Inhalt der message.md-Datei in deinem geklonten Repository.
5. Gib in beiden Terminalfenstern STRG+C ein, um den Server zu beenden und nicht mehr auf weitergeleitete Webhooks zu lauschen.

Du verfügst jetzt über eine App. Als Nächstes kannst du den Code deiner App erweitern, die App bereitstellen und sie öffentlich machen.

Forke das Repository /-app-js-sample, und ändere den Code, um auf verschiedene Webhookereignisse zu reagieren oder verschiedene API-Anforderungen zu übermitteln. Weitere Informationen zum Code findest du unter Erstellen einer -App, die auf Webhookereignisse reagiert.

Denke daran, die Berechtigungen deiner App zu aktualisieren, wenn deine App zusätzliche Berechtigungen für die API-Anforderungen benötigt, die du erstellen möchtest, oder die Webhookereignisse, die du empfangen möchtest. Weitere Informationen finden Sie unter Auswählen von Berechtigungen für eine -App.

In diesem Tutorial wurde dein Computer oder Codespace als Server verwendet. Sobald die App für die Verwendung in der Produktion bereit ist, solltest du deine App auf einem dedizierten Server bereitstellen. Du kannst beispielsweise Azure App Service nutzen.

Wenn du über einen Server verfügst, aktualisiere die Webhook-URL in den Einstellungen deiner App. Du solltest „Smee.io“ nicht verwenden, um deine Webhooks in der Produktion weiterzuleiten.

Außerdem musst du die Konstanten port und host im Code aktualisieren. Weitere Informationen finden Sie unter Erstellen einer -App, die auf Webhookereignisse reagiert.

Du solltest niemals den privaten Schlüssel deiner App oder das Webhookgeheimnis veröffentlichen. In diesem Tutorial wurden die Anmeldeinformationen deiner App in einer von Git ignorierten .env-Datei gespeichert. Wenn du deine App bereitstellst, solltest du eine sichere Methode zum Speichern der Anmeldeinformationen auswählen und deinen Code aktualisieren, um den Wert entsprechend abzurufen. Du kannst die Anmeldeinformationen beispielsweise in einer Umgebungsvariable auf dem Server speichern, auf dem deine App bereitgestellt ist. Du kannst auch einen Geheimnisverwaltungsdienst wie Azure Key Vault verwenden.

Wenn du deine App für andere Benutzer und Organisationen freigeben möchtest, mache deine App öffentlich. Weitere Informationen finden Sie unter Öffentlich- oder Privatmachen einer -App.

Du solltest Best Practices für deine App befolgen. Weitere Informationen finden Sie unter Best Practices beim Erstellen einer -App.