# Verwenden der REST-API zur Interaktion mit Überprüfungen Sie können die REST-API verwenden, um GitHub Apps zu erstellen, die leistungsstarke Prüfungen von Codeänderungen in einem Repository ausführen. Du kannst Apps erstellen, die Continuous Integration, Codelinting oder Codescandienste ausführen und detailliertes Feedback zu Commits bereitstellen. ## Übersicht Anstatt binärer Build-Status vom Typ „bestanden/nicht bestanden“ kann GitHub Apps detaillierte Statusinformationen liefern, Codezeilen mit detaillierten Informationen annotieren und Tests erneut ausführen. REST-API zum Verwalten von Prüfungen ist ausschließlich für Ihre GitHub Apps verfügbar. Ein Beispiel für die Verwendung der REST-API mit einer GitHub Appfinden Sie unter [Erstellen von CI-Prüfungen mit einer GitHub-App](/de/enterprise-server@3.22/apps/creating-github-apps/writing-code-for-a-github-app/building-ci-checks-with-a-github-app#step-26-automatically-fix-rubocop-errors). Sie können Status mit [geschützten Branches](/de/enterprise-server@3.22/rest/repos#branches) verwenden, um zu verhindern, dass Pull Requests vorzeitig zusammengeführt werden. Weitere Informationen finden Sie unter [Informationen zu geschützten Branches](/de/enterprise-server@3.22/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches#require-status-checks-before-merging). ## 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](/de/enterprise-server@3.22/rest/checks#check-runs), 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 kann den Status auf `requested`, `waiting` oder `pending` setzen. 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](/de/enterprise-server@3.22/rest/checks#check-suites) 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](/de/enterprise-server@3.22/rest/checks/suites#update-repository-preferences-for-check-suites). 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](/de/enterprise-server@3.22/rest/checks/suites#create-a-check-suite) erstellen. Du solltest weiterhin den Endpunkt [Erstellen einer Überprüfungsausführung](/de/enterprise-server@3.22/rest/checks/runs#create-a-check-run) 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](/de/enterprise-server@3.22/rest/commits#commit-statuses) interessieren. Um die Endpunkte zum Verwalten von Check-Suites zu verwenden, muss GitHub App über die Berechtigung `checks:write` verfügen und kann auch den [check\_suite](/de/enterprise-server@3.22/webhooks/webhook-events-and-payloads#check_suite)-Webhook abonnieren. Weitere Informationen zum Authentifizieren als GitHub-App findest du unter [Informationen zur Authentifizierung mit einer GitHub-App](/de/enterprise-server@3.22/apps/creating-github-apps/authenticating-with-a-github-app/about-authentication-with-a-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 kann den Status auf `requested`, `waiting` oder `pending` setzen. Der Status `completed` lässt folgende Schlussfolgerungen zu: * `action_required` * `cancelled` * `timed_out` * `failure` * `neutral` * `skipped` * `success` Wenn ein Prüflauf länger als 14 Tage im unvollständigen Zustand ist, wird aus dem `conclusion` der Prüfausführung `stale` und er erscheint auf GitHub als veraltet mit . Nur GitHub kann Check-Ausführungen als `stale` markieren. Weitere Informationen zu den möglichen Ergebnissen einer Überprüfungsausführung findest du unter [`conclusion`-Parameter](/de/enterprise-server@3.22/rest/checks#create-a-check-run--parameters). Sobald du den [`check_suite`](/de/enterprise-server@3.22/webhooks/webhook-events-and-payloads#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](/de/enterprise-server@3.22/rest/checks/runs). Eine Überprüfung kann auch manuell auf der benutzeroberfläche GitHub erneut ausgeführt werden. Weitere Informationen findest du unter [Statusüberprüfungen](/de/enterprise-server@3.22/pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/about-status-checks#checks). In diesem Fall empfängt das GitHub App, das die Überprüfungsausführung erstellt hat, den Webhook [`check_run`](/de/enterprise-server@3.22/webhooks/webhook-events-and-payloads#check_run), der eine neue Überprüfungsausführung anfordert. Wenn Sie eine Prüfausführung erstellen, ohne eine Prüfsuite zu erstellen, erstellt GitHub die Prüfsuite automatisch für Sie. 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](/de/enterprise-server@3.22/rest/commits#commit-statuses) interessieren. Um die Endpunkte zum Verwalten von Check Runs zu verwenden, muss GitHub App über die Berechtigung `checks:write` verfügen und kann außerdem den [check\_run](/de/enterprise-server@3.22/webhooks/webhook-events-and-payloads#check_run)-Webhook abonnieren. ## Überprüfungsläufe und angeforderte Aktionen Wenn Sie eine Überprüfungsausführung mit angeforderten Aktionen einrichten (nicht zu verwechseln mit GitHub Actions), können Sie in der Pull-Request-Ansicht auf GitHub eine Schaltfläche einblenden, mit der Benutzer Ihre GitHub App auffordern können, 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](/de/enterprise-server@3.22/rest/checks/runs#create-a-check-run--parameters), wenn du [eine Überprüfungsausführung erstellst](/de/enterprise-server@3.22/rest/checks#create-a-check-run), 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. ```json "actions": [{ "label": "Fix this", "description": "Let us fix that for you", "identifier": "fix_errors" }] ``` Wenn ein Benutzer auf die Schaltfläche klickt, sendet GitHub den [`check_run.requested_action` Webhook](/de/enterprise-server@3.22/webhooks/webhook-events-and-payloads#check_run) an Ihre 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](/de/enterprise-server@3.22/apps/creating-github-apps/writing-code-for-a-github-app/building-ci-checks-with-a-github-app) findest du ein detailliertes Beispiel für das Einrichten angeforderter Aktionen mit der REST-API. ## Aufbewahrung von Überprüfungsdaten Site-Administratoren können die Aufbewahrungsrichtlinie für Prüfdaten auf Ihre GitHub Enterprise Server-Instance steuern. Weitere Informationen finden Sie unter [Konfigurieren von Anwendungen](/de/enterprise-server@3.22/admin/configuring-settings/configuring-user-applications-for-your-enterprise/configuring-applications#enabling-retention-policy-for-checks). Um einen Pull Request mit Überprüfungen zusammenzuführen, die sowohl erforderlich als auch archiviert sind, musst du die Überprüfungen erneut ausführen.