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 Ihrem Workflow: es wird nichts von Ihrem Code an unsere Server übertragen; die Analyse passiert wie bisher auf Ihrem 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 Sie aus jedem CI-System aufrufen können, siehe Checks aus beliebigem CI veröffentlichen.

Installation

1. Öffnen Sie github.com/apps/codecharter und installieren Sie die App auf Ihrer Organisation (oder ausgewählten Repositories).

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

2. Sie werden zurück ins Portal geleitet, das die Installation automatisch mit Ihrem CodeCharter-Konto verknüpft. Das funktioniert nur, solange Sie im selben Browser im Portal angemeldet sind. Den Status sehen Sie jederzeit auf der Seite GitHub in der Portal-Seitenleiste. Schlägt die Verknüpfung fehl, leitet das Portal Sie mit einer Fehlermeldung zurück: im Portal anmelden, die Seite GitHub öffnen und die Installation von dort erneut starten.
3. Nutzen Sie die Action weiter wie gewohnt. Beim nächsten Pull Request erscheinen der CodeCharter-Check und -Kommentar, und Sie können 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 Sie 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 Sie es zurücknehmen, und das fertige README-Markdown liegt hinter einem Aufklapper mit Kopier-Button pro Badge. Beide Abschnitte sagen Ihnen 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

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

Entfernen

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