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. REST-API zum Verwalten von Prüfungen ist ausschließlich für Ihre GitHub Apps verfügbar.

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

Sie können Status mit geschützten Branches verwenden, um zu verhindern, dass Pull Requests vorzeitig zusammengeführt werden. Weitere Informationen finden Sie unter Informationen zu geschützten Branches.

Informationen zu Überprüfungssammlungen

Wenn jemand Code an ein Repository überträgt, erstellt GitHub eine Prüfsuite für den letzten Commit. Eine Prüfsuite ist eine Sammlung der check-Ausführungen, die von einer einzelnen "GitHub App" für einen bestimmten Commit erstellt wurden. Ü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.

Standardmäßig erstellt GitHub automatisch eine Prüfsuite, wenn Code an das Repository übertragen wird. Dieser Standardfluss sendet das check_suite-Ereignis (mit requested-Aktion) an alle GitHub Apps mit der Berechtigung checks:write. Wenn Ihre GitHub App das ereignis check_suite empfängt, kann sie neue Überprüfungsläufe für den neuesten 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, hast du die Möglichkeit, beim Erstellen von Prüf-Suites zu steuern. 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 automatischer Abläufe werden im Audit-Log 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üfungssuites zu nutzen, muss die GitHub App die Berechtigungen checks:write besitzen 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 Prüfläufen

Ein Testlauf ist ein einzelner Test, der Teil einer Testreihe 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 deinem Prüflauf 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 finden Sie unter REST-API-Endpunkte für Überprüfungsausführungen.

Eine Überprüfung kann auch manuell auf der benutzeroberfläche GitHub erneut ausgeführt werden. Weitere Informationen findest du unter Informationen zu Statuschecks. Wenn das geschieht, erhält die GitHub App, die die Überprüfungsausführung 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üfungsläufe 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 des Prüflaufs 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-Prü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.