Skip to content

Checks aus beliebigem CI veröffentlichen

Über POST /api/v1/ci/checks einen CodeCharter-Check-Run und PR-Kommentar auf GitHub aus jedem CI-System veröffentlichen.

Aktualisiert am 2026-06-10

Der Portal-Endpunkt POST /api/v1/ci/checks veröffentlicht ein Analyseergebnis als gebrandeten CodeCharter-Check-Run und optional als persistenten Pull-Request-Kommentar auf einem GitHub-Repository. Die GitHub Action nutzt diesen Endpunkt intern, er ist aber eine reguläre, per API-Schlüssel authentifizierte API: Sie können ihn genauso aus Jenkins, TeamCity, Azure DevOps, GitLab oder einem einfachen Shell-Skript aufrufen.

Zwei Dinge sind dabei zu trennen:

  • Wo der Code gebaut wird, kann jedes CI-System sein.
  • Wo der Check erscheint, ist immer GitHub: der Endpunkt postet über die CodeCharter App einen Check-Run auf ein GitHub-Repository. Liegt Ihr Repository nicht auf GitHub, gibt es nichts, worauf der Endpunkt posten könnte.

Voraussetzungen

  1. Die CodeCharter GitHub App ist auf dem GitHub-Account oder der Organisation installiert, der das Repository gehört, und die Installation ist mit Ihrem Portal-Konto verknüpft.
  2. Ein Portal-API-Schlüssel (erzeugen Sie ihn unter API Keys und legen Sie ihn als Secret ab, siehe API-Keys in Secrets).
  3. Ein aktives Abonnement auf dem Konto, dem der API-Schlüssel gehört.

Request

POST https://codecharter.tools/api/v1/ci/checks
Authorization: Bearer <Ihr API-Schlüssel>
Content-Type: application/json
Feld Typ Pflicht Beschreibung
repository string ja Vollständiger Repository-Name in der Form owner/repo.
headSha string ja Commit-SHA, gegen den der Check-Run gemeldet wird.
checkName string nein Anzeigename des Check-Runs. Standard ist CodeCharter. Darf nicht leer sein, wenn Sie ihn setzen.
conclusion string nein success, failure oder neutral (Standard). Jeder andere Wert wird als neutral behandelt.
title string nein Titel der Check-Run-Ausgabe.
summary string nein Markdown-Text, der sowohl als Check-Zusammenfassung als auch als PR-Kommentar verwendet wird.
annotations array nein Inline-Annotationen, siehe unten.
pullNumber number nein Pull-Request-Nummer für den Kommentar. Bei Push-Builds weglassen.
comment boolean nein true, um einen persistenten PR-Kommentar zu posten oder zu aktualisieren. Standard false; ohne positive pullNumber wirkungslos.
commentKey string nein Unterscheidungsmerkmal für den persistenten Kommentar, siehe unten.

Jeder Eintrag in annotations entspricht GitHubs Check-Annotation-Form:

Feld Typ Beschreibung
path string Repository-relativer Dateipfad.
startLine number Erste Zeile des annotierten Bereichs (1-basiert).
endLine number Letzte Zeile des annotierten Bereichs (1-basiert).
level string failure, warning oder notice (Standard). Jeder andere Wert wird als notice behandelt.
title string Kurzer Titel, typischerweise der Regelname.
message string Lesbare Beschreibung des Findings.

Beispiel

curl -X POST https://codecharter.tools/api/v1/ci/checks \
  -H "Authorization: Bearer $CODECHARTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "repository": "acme/acme-web",
    "headSha": "0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b",
    "pullNumber": 42,
    "conclusion": "failure",
    "title": "3 Findings (1 Error)",
    "summary": "## CodeCharter\n\n| Regel | Schweregrad | Anzahl |\n|---|---|---|\n| no-console-write | error | 1 |",
    "comment": true,
    "commentKey": "acme-web-main",
    "annotations": [
      {
        "path": "src/Web/Program.cs",
        "startLine": 12,
        "endLine": 12,
        "level": "failure",
        "title": "no-console-write",
        "message": "Console.WriteLine ist in Produktionscode nicht erlaubt."
      }
    ]
  }'

Antworten

Status Bedeutung
200 Veröffentlicht. Body: {"status":"published"}.
400 Validierung fehlgeschlagen: repository (in der Form owner/repo), headSha und checkName sind Pflicht und dürfen nicht leer sein.
401 API-Schlüssel fehlt, ist ungültig oder abgelaufen.
402 Ihr Abonnement ist nicht aktiv.
409 Die CodeCharter GitHub App ist auf dem Account des Repository-Besitzers nicht installiert, oder die Installation ist nicht mit Ihrem Portal-Konto verknüpft.
502 Das Portal konnte den Check nicht an GitHub übermitteln. Versuchen Sie es später erneut; tritt der Fehler dauerhaft auf, prüfen Sie die App-Installation auf GitHub.

Fehlerantworten (400, 402, 409, 502) enthalten einen Problem-Details-JSON-Body, dessen Feld detail die Ursache beschreibt.

Verhalten

  • Check-Runs werden per Upsert gepflegt. Existiert auf demselben Commit bereits ein Check-Run mit demselben checkName, wird er aktualisiert statt dupliziert. Der veröffentlichte Check-Run ist immer im Zustand completed.
  • Höchstens 50 Annotationen werden pro Veröffentlichung angehängt; weitere Einträge werden stillschweigend verworfen. Packen Sie die vollständige Finding-Liste in summary, wenn Sie sie brauchen.
  • Der PR-Kommentar ist persistent. Ist comment auf true gesetzt und pullNumber angegeben, sucht das Portal nach einem bestehenden Kommentar mit einem versteckten, aus commentKey abgeleiteten Marker und aktualisiert ihn; sonst wird ein neuer angelegt. Aufrufe mit demselben commentKey aktualisieren also immer denselben Kommentar, verschiedene Keys pflegen getrennte Kommentare (nützlich, wenn mehrere Jobs in denselben Pull Request berichten). Ohne commentKey gilt ein gemeinsamer Standard-Key.

Siehe auch