Verwenden der REST-API zur Interaktion mit Überprüfungen

Übersicht

Anstelle binärer Buildstatus des Typs „Erfolg“ oder „Fehler“ können GitHub Apps umfangreiche Status melden, Codezeilen mit detaillierten Informationen kommentieren und Tests wiederholen. Die REST-API zum Verwalten von Überprüfungen ist exklusiv für deine GitHub-Apps verfügbar.

Unter Erstellen von CI-Überprüfungen mit einer GitHub-App findest du ein Beispiel für die Verwendung der REST-API mit einer GitHub App.

Durch die Verwendung dieser Status mit geschützten Branches kann verhindert werden, dass Pull Requests vorzeitig zusammengeführt werden. Weitere Informationen findest du unter Informationen zu geschützten Branches.

Informationen zu Überprüfungssammlungen

Wenn Code in ein Repository gepusht wird, erstellt GitHub eine Überprüfungssammlung für den letzten Commit. Eine Überprüfungssammlung ist eine Sammlung von Überprüfungsausführungen, die von einer einzelnen GitHub-App für einen bestimmten Commit erstellt wurde. Überprüfungssammlungen fassen den Status und das Ergebnis der Überprüfungsausführungen zusammen, die in einer Sammlung enthalten sind.

Die status können queued, in_progress, requested, waiting, pending oder completed lauten. Nur GitHub Actions können den Status als requested, waiting oder pending festlegen.

Der Status completed lässt folgende Schlussfolgerungen zu:

action_required
cancelled
timed_out
failure
neutral
skipped
stale
startup_failure
success

Die Überprüfungssammlung meldet die conclusion der Überprüfungsausführung mit der höchsten Priorität in der conclusion der Überprüfungssammlung. Wenn beispielsweise drei Überprüfungen die Ergebnisse timed_out, success und neutral haben, ist das Ergebnis der Überprüfungssammlung timed_out.

Wenn Code in das Repository gepusht wird, erstellt GitHub immer automatisch eine Überprüfungssammlung. Dieser Standardflow sendet das check_suite-Ereignis (mit der requested-Aktion) an alle GitHub-Apps, die über die Berechtigung checks:write verfügen. Wenn deine GitHub-App das Ereignis check_suite empfängt, kann sie neue Überprüfungsausführungen für den letzten Commit erstellen. GitHub fügt abhängig vom Repository und dem SHA-Wert der Überprüfungsausführung automatisch neue Überprüfungsausführungen zur richtigen Überprüfungssammlung hinzu.

Wenn du den automatischen Standardflow nicht verwenden möchtest, kannst du dies beim Erstellen der Überprüfungssammlungen festlegen. Verwende zum Ändern der Standardeinstellungen für die Erstellung von Überprüfungssammlungen den Endpunkt Aktualisieren von Repositoryeinstellungen für Überprüfungssammlungen. Alle Änderungen an den Einstellungen von automatischen Flows werden im Überwachungsprotokoll des Repositorys aufgezeichnet. Wenn du den automatischen Flow deaktiviert hast, kannst du eine Überprüfungssammlung mithilfe des Endpunkts Erstellen einer Überprüfungssammlung erstellen. Du solltest weiterhin den Endpunkt Erstellen einer Überprüfungsausführung verwenden, um Feedback zu einem Commit bereitzustellen.

Schreibberechtigungen für die REST-API zur Interaktion mit Überprüfungen sind nur für GitHub Apps verfügbar. OAuth apps und authentifizierte Benutzer können die Überprüfungsausführungen und Überprüfungssammlungen anzeigen, aber nicht erstellen. Wenn Sie keine GitHub App erstellent, könnten Sie die Verwendung der REST-API zur Interaktion mit Commitstatus interessieren.

Um die Endpunkte zur Verwaltung von Überprüfungssammlungen zu nutzen, muss die GitHub App die Berechtigung checks:write haben und kann auch den Webhook check_suite abonnieren.

Weitere Informationen zum Authentifizieren als GitHub-App findest du unter Informationen zur Authentifizierung mit einer GitHub-App.

Informationen zu Überprüfungsausführungen

Eine Überprüfungsausführung ist ein einzelner Test, der Teil einer Überprüfungssammlung ist. Jede Ausführung enthält einen Status und ein Ergebnis.

Die status können queued, in_progress, requested, waiting, pending oder completed lauten. Nur GitHub Actions können den Status als requested, waiting oder pending festlegen.

Der Status completed lässt folgende Schlussfolgerungen zu:

action_required
cancelled
timed_out
failure
neutral
skipped
success

Wenn eine Überprüfungsausführung sich mehr als 14 Tage in einem unvollständigen Zustand befindet, ändert sich conclusion für die Überprüfungsausführung in stale und wird in GitHub als veraltet mit angezeigt. Nur GitHub kann Überprüfungsausführungen als stale markieren. Weitere Informationen zu den möglichen Ergebnissen einer Überprüfungsausführung findest du unter conclusion-Parameter.

Sobald du den check_suite-Webhook erhältst, kannst du die Überprüfungsausführung erstellen, auch wenn die Überprüfung nicht abgeschlossen ist. Du kannst den status der Überprüfungsausführung aktualisieren, sobald er mit den Werten queued, in_progress oder completed abgeschlossen ist, und du kannst den output aktualisieren, sobald weitere Details verfügbar sind. Eine Überprüfungsausführung kann Zeitstempel, einen Link zu weiteren Details auf deiner externen Website, detaillierte Anmerkungen zu bestimmten Codezeilen und Informationen zur durchgeführten Analyse enthalten.

Anmerkungen fügen bestimmten Codezeilen Informationen aus deiner Überprüfungsausführung hinzu. Jede Anmerkung enthält eine annotation_level-Eigenschaft, die notice, warning oder failure lauten kann. Die Anmerkung umfasst außerdem path, start_line und end_line, um anzugeben, auf welche Position sich die Anmerkung bezieht. Die Anmerkung umfasst eine message, um das Ergebnis zu beschreiben. Weitere Informationen findest du unter REST-API-Endpunkte für Überprüfungsausführungen.

Eine Überprüfung kann auch manuell mithilfe der GitHub-Benutzeroberfläche erneut ausgeführt werden. Weitere Informationen findest du unter Informationen zu Statuschecks. Wenn dies geschieht, erhält die GitHub-App, die die Überprüfung erstellt hat, den check_run-Webhook, der eine neue Überprüfungsausführung anfordert. Wenn du eine Überprüfungsausführung generierst, ohne eine Überprüfungssammlung zu erstellen, erstellt GitHub die Überprüfungssammlung automatisch.

Um die Endpunkte zur Verwaltung von Überprüfungsausführungen zu nutzen, muss die GitHub App die Berechtigung checks:write haben und kann auch den Webhook check_run abonnieren.

Überprüfungsausführungen und angeforderte Aktionen

Wenn du eine Überprüfungsausführung mit angeforderten Aktionen einrichtest (nicht zu verwechseln mit GitHub Actions), kannst du eine Schaltfläche in der Pull Request-Anzeige auf GitHub anzeigen, mit der Benutzer*innen deine GitHub App anfordern können, um zusätzliche Aufgaben auszuführen.

Beispielsweise könnte eine Codelinting-App angeforderte Aktionen verwenden, um eine Schaltfläche in einem Pull Request anzuzeigen, wodurch erkannte Syntaxfehler automatisch behoben werden können.

Verwende das actions-Objekt, wenn du eine Überprüfungsausführung erstellst, um eine Schaltfläche zu erstellen, die zusätzliche Aktionen von deiner App anfordern kann. Beispielsweise zeigt das folgende actions-Objekt eine Schaltfläche auf der Registerkarte Überprüfungen für einen Pull Request mit der Bezeichnung „Korrigieren“. Die Schaltfläche wird nach Abschluss der Überprüfungsausführung angezeigt.

"actions": [{
  "label": "Fix this",
  "description": "Let us fix that for you",
  "identifier": "fix_errors"
}]

Wenn eine Benutzerin auf die Schaltfläche klickt, sendet GitHub den check_run.requested_action-Webhook an deine App. Wenn deine App ein check_run.requested_action-Webhookereignis empfängt, kann sie in den Webhooknutzdaten nach dem requested_action.identifier-Schlüssel suchen, um zu ermitteln, welche Schaltfläche betätigt wurde, und die angeforderte Aufgabe ausführen.

Unter Erstellen von CI-Überprüfungen mit einer GitHub-App findest du ein detailliertes Beispiel für das Einrichten angeforderter Aktionen mit der REST-API.

Aufbewahrung von Überprüfungsdaten

Websiteadministrator*innen können die Aufbewahrungsrichtlinie für Überprüfungsdaten für Ihre GitHub Enterprise Server-Instance festlegen. Weitere Informationen finden Sie unter „Konfigurieren von Anwendungen“.

Um einen Pull Request mit Überprüfungen zusammenzuführen, die sowohl erforderlich als auch archiviert sind, musst du die Überprüfungen erneut ausführen.