Verwenden der GitHub-API in deiner App

Einführung

Dieser Leitfaden unterstützt dich dabei, eine GitHub-App zu erstellen und auf einem Server auszuführen. Mit der von Ihnen erstellten App wird allen neuen Issues, die im Repository geöffnet werden, in dem die App installiert ist, eine Bezeichnung hinzugefügt.

In diesem Projekt wirst du durch die folgenden Schritte geführt:

• Programmieren der App zum Überwachen von Ereignissen
• Verwenden der Octokit.rb-Bibliothek zum Ausführen von REST-API-Vorgängen

Nachdem du die Schritte durchgearbeitet hast, kannst du andere Arten von Integrationen mithilfe der vollständigen Suite der GitHub-APIs entwickeln. Du kannst erfolgreiche Beispiele für Apps auf GitHub Marketplace und Works with GitHub auschecken.

Voraussetzungen

Du dürftest es als hilfreich empfinden, ein grundlegendes Verständnis von Folgendem zu haben:

• GitHub Apps
• Webhooks
• Programmiersprache Ruby
• REST-APIs
• Sinatra

Du kannst die Schritte jedoch mit jedem Kenntnisstand nachverfolgen. Auf während des Durcharbeitens benötigte Informationen wird jeweils mit einem Link verwiesen.

Bevor du beginnst, musst du folgende Aufgaben durchführen:

1. Klone das Repository Using the GitHub API in your app (Verwenden der GitHub-API in deiner App).

   $ git clone https://github.com/github-developer/using-the-github-api-in-your-app.git

   In dem Verzeichnis befindet sich die Datei template_server.rb mit dem Vorlagencode, den du bei diesem Schnellstart verwendest, und die Datei server.rb mit dem gesamten Projektcode.

2. Gehe wie im Schnellstart Einrichten der Entwicklungsumgebung beschrieben vor, um den template_server.rb-App-Server zu konfigurieren und auszuführen. Wenn du zuvor einen anderen GitHub-App-Schnellstart als das Einrichten der Entwicklungsumgebung abgeschlossen hast, solltest du eine neue GitHub-App registrieren und einen neuen Smee-Kanal starten, der mit dieser Schnellstartanleitung verwendet werden soll.

   Diese Schnellstartanleitung enthält denselben template_server.rb-Code wie die Schnellstartanleitung Einrichten der Entwicklungsumgebung. Hinweis: Wenn du die Schnellstartanleitung Einrichten der Entwicklungsumgebung durcharbeitest, achte darauf, dass du die Projektdateien verwendest, die im Repository Using the GitHub API in your app (Verwenden der GitHub-API in deiner App) enthalten sind.

   Bei Problemen beim Einrichten der GitHub-App-Vorlage findest du im Abschnitt zur Problembehandlung weitere Informationen.

Erstellen der App

Nachdem du nun mit dem template_server.rb-Code vertraut bist, erstelle Code, mit dem die Bezeichnung needs-response automatisch allen geöffneten Issues im Repository hinzugefügt wird, in dem die App installiert ist.

Die Datei template_server.rb enthält App-Vorlagencode, der noch nicht angepasst wurde. In dieser Datei wird Platzhaltercode zum Verarbeiten von Webhookereignissen und anderer Code zum Initialisieren eines Octokit.rb-Clients angezeigt.

Dies sind die Schritte, die du ausführst, um deine erste GitHub-App zu erstellen:

1. Aktualisieren von App-Berechtigungen
2. Hinzufügen von Ereignisbehandlung
3. Erstellen einer neuen Bezeichnung
4. Hinzufügen von Bezeichnungsbehandlung

Schritt 1: Aktualisieren von App-Berechtigungen

Bei der ersten Registrierung der App hast du die Standardberechtigungen übernommen, was bedeutet, dass die App auf die meisten Ressourcen keinen Zugriff hat. In diesem Beispiel benötigt die App die Berechtigung zum Lesen von Issues und Schreiben von Bezeichnungen.

So aktualisierst du die Berechtigungen deiner App:

1. Wähle auf der Seite der App-Einstellungen die App aus, und klicke in der Seitenleiste auf Permissions & Webhooks (Berechtigungen und Webhooks).
2. Suche im Abschnitt „Permissions“ (Berechtigungen) nach „Issues“, und wähle im Dropdownmenü „Access“ (Zugriff) den Eintrag Read & Write (Lesen und Schreiben) aus. Die Beschreibung gibt an, dass mit dieser Option Zugriff sowohl auf Issues als auch auf Bezeichnungen gewährt wird. Dies ist genau das, was du benötigst.
3. Wähle im Abschnitt „Subscribe to events“ (Ereignisse abonnieren) die Option Issues zum Abonnieren des Ereignisses aus.
4. Klicke unten auf der Seite auf Änderungen speichern.
5. Wenn du die App in deinem Konto installiert hast, überprüfe deine E-Mail, und folge dem Link, um die neuen Berechtigungen zu akzeptieren. Wenn du die Berechtigungen oder Webhooks deiner App änderst, müssen Benutzer, die die App installiert haben (auch du selbst), die neuen Berechtigungen akzeptieren, bevor die Änderungen wirksam werden. Du kannst auch die neuen Berechtigungen akzeptieren, indem du zur Installationsseite navigierst und neben deiner App auf „Konfigurieren“ klickst. Oben auf der Seite wird ein Banner angezeigt, das dich informiert, dass die App andere Berechtigungen anfordert. Klicke auf „Details“ und dann auf „Neue Berechtigungen akzeptieren“.

Sehr gut! Deine App verfügt nun über die Berechtigung zum Ausführen der gewünschten Aufgaben. Jetzt kannst du den für die Funktion nötigen Code hinzufügen.

Schritt 2: Hinzufügen von Ereignisbehandlung

Die erste notwendige Aufgabe der App ist die Überwachung auf neue Issues, die geöffnet werden. Nachdem du das Ereignis Issues abonniert hast, erhältst du den issues-Webhook, der ausgelöst wird, wenn bestimmte mit Issues verbundene Aktionen auftreten. Du kannst diesen Ereignistyp nach der gewünschten Aktion im Code filtern.

GitHub sendet Webhooknutzdaten als POST-Anforderungen. Da du die Smee-Webhooknutzdaten an http://localhost/event_handler:3000 weitergeleitet hast, erhält der Server die POST-Anforderungsnutzdaten auf der post '/event_handler'-Route.

In der Datei template_server.rb, die du im Abschnitt mit den Voraussetzungen heruntergeladen hast, befindet sich bereits eine leere post '/event_handler'-Route. Die leere Route sieht wie folgt aus:

  post '/event_handler' do

    # # # # # # # # # # # #
    # ADD YOUR CODE HERE  #
    # # # # # # # # # # # #

    200 # success status
  end

Verwende diese Route zur Behandlung des Ereignisses issues, indem du den folgenden Code hinzufügst:

case request.env['HTTP_X_GITHUB_EVENT']
when 'issues'
  if @payload['action'] === 'opened'
    handle_issue_opened_event(@payload)
  end
end

Alle Ereignisse, die von GitHub gesendet werden, enthalten den Anforderungsheader HTTP_X_GITHUB_EVENT, der den Ereignistyp in der POST-Anforderung angibt. Jetzt bist du nur an issues-Ereignistypen interessiert. Alle Ereignisse enthalten ein zusätzliches action-Feld, das die Aktion angibt, durch die die Ereignisse ausgelöst wurden. Bei issues kann das action-Feld assigned, unassigned, labeled, unlabeled, opened, edited, milestoned, demilestoned, closed oder reopened angeben.

Versuche zum Testens des Ereignishandlers, eine temporäre Hilfsmethode hinzuzufügen. Du führst später eine Aktualisierung durch, wenn du die Bezeichnungsbehandlung hinzufügst. Füge jetzt den folgenden Code im helpers do-Abschnitt des Codes hinzu. Du kannst die neue Methode über oder unter einer der anderen Hilfsmethoden platzieren. Die Reihenfolge spielt keine Rolle.

def handle_issue_opened_event(payload)
  logger.debug 'An issue was opened!'
end

Diese Methode empfängt JSON-formatierte Ereignisnutzdaten als Argument. Dies bedeutet, dass du die Nutzdaten in der Methode analysieren und Detailinformationen für alle benötigten Daten anzeigen kannst. Du könntest es hilfreich finden, irgendwann die vollständigen Nutzdaten zu überprüfen: Versuche es mit einem Wechsel von logger.debug 'An issue was opened! zu logger.debug payload. Die Nutzdatenstruktur, die du siehst, sollte mit dem übereinstimmen, was in der issues-Webhook-Ereignisdokumentation angezeigt wird.

Sehr gut! Es ist an der Zeit, die Änderungen zu testen.

Rufe im Browser das Repository auf, in dem du die App installiert hast. Öffne ein neues Issue in diesem Repository. Das Issue kann einen beliebigen Inhalt aufweisen. Es wird nur zu Testzwecken verwendet.

Wenn du wieder auf dein Terminal blickst, solltest du eine Meldung in der Ausgabe sehen, die besagt: An issue was opened! Gut gemacht. Du hast der App einen Ereignishandler hinzugefügt. 💪

Schritt 3: Erstellen einer neuen Bezeichnung

Gut. Von der App kann festgestellt werden, wann Issues geöffnet werden. Nun möchtest du, dass die App einem neu geöffneten Issue in einem Repository, in dem die App installiert ist, die Bezeichnung needs-response hinzufügt.

Bevor die Bezeichnung irgendwo hinzugefügt werden kann, musst du die benutzerdefinierte Bezeichnung im Repository erstellen. Dies ist nur einmal erforderlich. Erstelle für die Zwecke dieser Anleitung die Bezeichnung manuell auf GitHub. Klicke im Repository auf Issues, dann auf Labels (Bezeichnungen), und klicke dann auf New label (Neue Bezeichnung). Benenne die neue Bezeichnung als needs-response.

Nachdem die Bezeichnung jetzt vorhanden ist, kannst du die App dafür programmieren, die REST-API dazu zu verwenden, die Bezeichnung jedem neu geöffneten Issue hinzuzufügen.

Schritt 4. Hinzufügen von Bezeichnungsbehandlung

Gut gemacht. Du hast es zum letzten Schritt geschafft: Hinzufügen der Bezeichnungshandhabung zu deiner App. Für diese Aufgabe verwendest du die Octokit.rb-Ruby-Bibliothek.

Suche in der Octokit.rb-Dokumentation nach der Liste der Bezeichnungsmethoden. Die zu verwendende Methode lautet add_labels_to_an_issue.

Suche wieder in template_server.rb nach der zuvor definierten Methode:

def handle_issue_opened_event(payload)
  logger.debug 'An issue was opened!'
end

Die add_labels_to_an_issue-Dokumentation zeigt, dass du drei Argumente an diese Methode übergeben musst:

• Repository (Zeichenfolge im "owner/name"-Format)
• Issuenummer (ganze Zahl)
• Bezeichnungen (Array)

Du kannst die Nutzdaten analysieren, um sowohl das Repository als auch die Issuenummer abzurufen. Da der Bezeichnungsname immer gleich ist (needs-response), kannst du ihn als hartcodierte Zeichenfolge im Beschriftungsarray übergeben. Wenn du diese Teile zusammensetzt, sieht die aktualisierte Methode möglicherweise wie folgt aus:

# When an issue is opened, add a label
def handle_issue_opened_event(payload)
  repo = payload['repository']['full_name']
  issue_number = payload['issue']['number']
  @installation_client.add_labels_to_an_issue(repo, issue_number, ['needs-response'])
end

Versuche, ein neues Issue im Testrepository zu öffnen, und achte darauf, was passiert. Wenn nicht sofort etwas passiert, versuche es mit einer Aktualisierung.

Es wird nicht viel im Terminal angezeigt, aber du solltest erkennen, dass ein Botbenutzer dem Issue eine Bezeichnung hinzugefügt hat.

Wenn ja, gut gemacht. Du hast erfolgreich eine funktionierende App erstellt. 🎉

Du kannst den endgültigen Code in server.rb im App-Vorlagenrepository sehen.

Weitere Informationen dazu, wie du von dieser Stelle aus fortfahren kannst, findest du unter Nächste Schritte.

Problembehandlung

Im Folgenden werden einige häufige Probleme beschrieben und entsprechende Lösungen vorgeschlagen. Wenn du auf andere Probleme stößt, erhältst du im Diskussionen zu APIs und Integrationen in der GitHub-Community Unterstützung oder Beratung.

• F: Mein Server überwacht keine Ereignisse. Der Smee-Client wird in einem Terminalfenster ausgeführt, und ich sende Ereignisse auf GitHub.com, indem ich neue Issues öffne, aber ich sehe keine Ausgabe im Terminalfenster, in dem ich den Server ausführe.

  A: Möglicherweise verfügst du nicht über die richtige Smee-Domäne in den App-Einstellungen. Besuche die Seite „App-Einstellungen“, und überprüfe die in Einrichten der Entwicklungsumgebung zum Erstellen einer GitHub-App angezeigten Felder. Vergewissere dich, dass die Domäne in diesen Feldern mit der Domäne übereinstimmt, die du im Befehl smee -u <unique_channel> unter Einrichten der Entwicklungsumgebung zum Erstellen einer GitHub-App verwendet hast.

• F: Meine App funktioniert nicht. Ich habe ein neues Issue geöffnet, aber auch nach dem Aktualisieren wurde ihm keine Bezeichnung hinzugefügt.

  A: Vergewissere dich, dass alle folgenden Punkte zutreffen:

  • Du hast die App in dem Repository installiert, in dem du das Issue öffnest.
  • Die Ausführung des Smee-Clients erfolgt in einem Terminalfenster.
  • Die Ausführung des Webservers erfolgt ohne Fehler in einem anderen Terminalfenster.
  • Die App verfügt über Lese- und Schreibberechtigungen für Issues und hat Issueereignisse abonniert.
  • Du hast deine E-Mails nach dem Aktualisieren der Berechtigungen überprüft und die neuen Berechtigungen akzeptiert.

Schlussbemerkung

Nachdem du diesen Leitfaden durchgearbeitet hast, bist du nun mit den grundlegenden Bausteinen für die Entwicklung von GitHub-Apps vertraut. Du hast folgende Schritte durchgeführt:

• Programmieren der App zum Überwachen von Ereignissen
• Verwenden der Octokit.rb-Bibliothek zum Ausführen von REST-API-Vorgängen

Nächste Schritte

Hier einige Ideen, was du als Nächstes tun kannst:

• Schreibe die App mit GraphQL neu.
• Schreibe die App in Node.js mit Probot neu.
• Lass von der App überprüfen, ob die needs-response-Bezeichnung bereits für das Issue vorhanden ist, und, falls nicht, füge sie hinzu.
• Wenn der Bot die Bezeichnung erfolgreich hinzufügt, zeige eine Nachricht im Terminal an. (Hinweis: Vergleiche die needs-response-Bezeichnungs-ID mit der ID der Bezeichnung in den Nutzdaten als Bedingung für die Nachricht, sodass die Nachricht nur angezeigt wird, wenn die relevante Bezeichnung hinzugefügt wird, und nicht, wenn eine andere Bezeichnung hinzugefügt wird.)
• Füge der App eine Landing Page hinzu, und verbinde eine Sinatra-Route dafür.
• Verschiebe den Code auf einen gehosteten Server (z. B. Heroku). Denke daran, die App-Einstellungen mit der neuen Domäne zu aktualisieren.
• Teile dein Projekt in den Diskussionen zu APIs und Integrationen in der GitHub-Community, oder bitte dort um Rat.
• Hast du eine ganz neue App erstellt, von der du glaubst, dass andere sie hilfreich finden? Füge die App dem GitHub Marketplace hinzu.