Automatische PR-Checks mit der CodeCharter GitHub App

CodeCharter ist der Name von CodeCharters GitHub-App-Identität. Wer auf GitHub nach ihr sucht, findet sie unter "CodeCharter" (das ist die App, kein separates Produkt).

Die CodeCharter GitHub App ist der empfohlene Weg, CodeCharter-Ergebnisse auf GitHub zu veröffentlichen. Ist sie installiert, postet die Action über das Portal einen gebrandeten CodeCharter-Check-Run und einen PR-Zusammenfassungs-Kommentar unter der Identität der App.

Vorteile gegenüber der reinen Action:

• Ein gebrandeter CodeCharter-Check (mit stabilem Check-Namen für die Branch-Protection) statt eines github-actions[bot]-Kommentars.
• Kein GitHub-Token auf dem Runner und kein pull-requests: write im Workflow (die App bringt die Berechtigungen mit).

Die App entfernt nicht alle Secrets aus dem Workflow: Zum Veröffentlichen benötigt die Action weiterhin den API-Key des Portals (Input api-key, abgelegt als Secret CODECHARTER_API_KEY) sowie ein aktives Abo. Nur das GitHub-Token wird überflüssig. Da dieser API-Key ein Repository-Secret ist und GitHub Secrets in Workflows aus Fork-Pull-Requests nicht bereitstellt, funktioniert das Veröffentlichen über die App bei Fork-PR-Builds nicht. Außerdem zeigt der Check-Run höchstens 50 Inline-Annotationen pro Veröffentlichung.

Die App ersetzt die Action nicht

CodeCharter läuft weiterhin in eurem Workflow: es wird nichts von eurem Code an unsere Server übertragen; die Analyse passiert wie bisher auf eurem Runner. Die App ändert nur, wie die Ergebnisse veröffentlicht werden: statt über das Workflow-Token übergibt die Action das Ergebnis dem Portal, das es als CodeCharter postet. Ist die App nicht installiert, fällt die Action automatisch auf den Workflow-Token-Kommentar zurück, es bricht also nichts. Den Workflow-Aufbau beschreibt GitHub Actions.

Die Action ist außerdem nicht der einzige Weg, über die App zu veröffentlichen: der zugrunde liegende Portal-Endpunkt ist eine dokumentierte API, die ihr aus jedem CI-System aufrufen könnt, siehe Checks aus beliebigem CI veröffentlichen.

Installation

1. Öffnet github.com/apps/codecharter und installiert die App auf eurer Organisation (oder ausgewählten Repositories).

   Falls GitHub keinen Install-Button anzeigt, stellt sicher, dass ihr mit dem Account eingeloggt seid, der die Organisation besitzt. Bei mehreren GitHub-Accounts erst im GitHub-Header auf den richtigen wechseln, bevor ihr den Link öffnet.

2. Ihr werdet zurück ins Portal geleitet, das die Installation automatisch mit eurem CodeCharter-Konto verknüpft. Das funktioniert nur, solange ihr im selben Browser im Portal angemeldet seid. Den Status seht ihr jederzeit auf der Seite GitHub in der Portal-Seitenleiste. Schlägt die Verknüpfung fehl, leitet das Portal euch mit einer Fehlermeldung zurück: im Portal anmelden, die Seite GitHub öffnen und die Installation von dort erneut starten.
3. Nutzt die Action weiter wie gewohnt. Beim nächsten Pull Request erscheinen der CodeCharter-Check und -Kommentar, und ihr könnt pull-requests: write aus dem Workflow entfernen.

Die GitHub-Seite im Portal

Die Seite GitHub in der Portal-Seitenleiste besteht aus zwei Abschnitten. Der erste zeigt auf einen Blick, ob die App verbunden ist, und lässt euch eine weitere Installation hinzufügen. Der zweite zeigt eine Karte pro meldendem Repository mit den letzten Coverage-, Test- und Finding-Zahlen, dem Branch, auf dem sie gemessen wurden, und dem Zeitpunkt der letzten Meldung. Jede Karte trägt den Badge-Publish-Schalter neben einer kurzen Erklärung, was das Veröffentlichen bewirkt und wie ihr es zurücknehmt, und das fertige README-Markdown liegt hinter einem Aufklapper mit Kopier-Button pro Badge. Beide Abschnitte sagen euch im leeren Zustand, was als Nächstes zu tun ist, inklusive des Workflow-Snippets, das das Badge-Reporting einschaltet. Wie die Zahlen dorthin kommen, beschreibt GitHub Actions.

Branch-Protection

Tragt den CodeCharter-Check als Pflicht in eure Branch-Protection-Regel ein (Settings → Branches → Require status checks). Der Check-Name ist stabil, das Gate funktioniert also auch nach Workflow-Umbenennungen weiter.

Entfernen

Deinstalliert die App jederzeit in den Settings eurer GitHub-Organisation. CodeCharter fällt dann automatisch auf den Workflow-Token-Kommentar zurück. Damit dieser Fallback-Kommentar funktioniert, müsst ihr pull-requests: write wieder in die Workflow-Permissions aufnehmen (siehe Permissions).