API-Keys sind die Bearer-Tokens, mit denen Ihre CI und der GitHub-Action-Wrapper sich gegen das Portal authentifizieren. Jeder Key gehört zu einem Benutzer, gilt unabhängig vom Login-Cookie und kann unabhängig widerrufen werden.
Key erzeugen
Auf /api-keys:
- Name vergeben, frei wählbar (bis zu 120 Zeichen). Empfehlung: was der
Key tut bzw. wo er liegt, z.B.
acme-web-ci. Den Namen sehen Sie später in der Übersicht und beim Audit. - Laufzeit wählen: 30 Tage, 90 Tage, 1 Jahr oder unbegrenzt. 1 Jahr ist vorausgewählt. Kürzere Laufzeiten sind sicherer, brauchen aber häufigeren Austausch.
- Key erzeugen klicken.
Jeder Key trägt den Scope read:rules. Er deckt das Lesen Ihrer Regeln und
Profile sowie das Herunterladen von Bundles ab. Setzen Sie zusätzlich
write:rules, damit der Key mit codecharter push Entwürfe hochladen darf;
lassen Sie ihn für reine Lese-Keys in CI weg. Administratoren können einem Key
zusätzlich den Scope register:engines für Release-Automatisierung geben. Die
Scopes jedes Keys werden in der Key-Liste angezeigt.
Hinweis: Die meisten CLI-Befehle brauchen gar keinen API-Key mehr. analyze,
restore, update und verify authentifizieren sich über die installierte
codecharter.license, und push greift ebenfalls darauf zurück. Ein API-Key ist
nur nötig, wenn keine Lizenz auf den Runner gelangt (dann braucht push einen
Key mit write:rules).
Den Klartext-Wert kopieren
Direkt nach der Erzeugung zeigt das Portal einmal den vollen Klartext des Keys, in einem Warnhinweis auf der Seite. Kopieren Sie ihn sofort: wir speichern nur einen Hash, und der Klartext ist weg, sobald Sie die Seite verlassen oder neu laden.
Keys beginnen mit cgk_, und die Key-Liste zeigt die ersten 12 Zeichen
jedes Keys. So können Sie ein gespeichertes Secret später dem passenden
Listeneintrag zuordnen.
Wenn Sie den Wert verloren haben: einfach einen neuen Key erzeugen und den alten widerrufen. Wir können Ihnen den Wert nachträglich nicht zeigen.
Key in Ihrer CI hinterlegen
Speichern Sie den kopierten Wert als Secret in Ihrem CI-System. Details pro CI-System unter API-Keys in Secrets.
GitHub Actions Schnellanleitung:
Repo → Settings → Secrets and variables → Actions → New repository secret
Name: CODECHARTER_API_KEY
Value: <der Klartext-Wert>
Im Workflow:
- uses: bochmann-software/codeguard@v1
with:
api-key: ${{ secrets.CODECHARTER_API_KEY }}
Key widerrufen
Im Portal in der API-Key-Liste neben dem Eintrag Widerrufen klicken und im Bestätigungsdialog bestätigen. Ab dem nächsten CI-Aufruf bekommt der Key 401 Unauthorized.
Ein Widerruf lässt sich nicht rückgängig machen. Wenn Sie sich vertan haben, erzeugen Sie einfach einen neuen Key.
Key austauschen
Wenn ein Key kompromittiert ist oder ein Team-Mitglied geht, das den Klartext gesehen haben könnte, ersetzen Sie ihn so:
- Neuen Key erzeugen im Portal.
- Im CI-System den neuen Wert in dieselbe Secret-Variable
(
CODECHARTER_API_KEY) schreiben. - Einen CI-Lauf auslösen, um zu bestätigen, dass der neue Key funktioniert.
- Alten Key widerrufen.
Mehrere Keys dürfen gleichzeitig aktiv sein. Der neue Key ist sofort nutzbar, während der alte noch gilt. Das ergibt ein sauberes Wechselfenster ohne Ausfallzeit, bevor Sie den alten Key widerrufen.
Was ein Key kann
Ein Key authentifiziert die Portal-Aufrufe der CLI: das Abrufen und Erneuern
der kurzlebigen Lizenz, das Herunterladen von CLI-Release-Archiven, die
Befehle update und push, verify mit --against-portal sowie den
CI-Checks-Endpunkt. restore braucht keinen API-Key, der Befehl
authentifiziert sich mit der kurzlebigen Lizenz selbst. analyze läuft
lokal und nimmt keinen API-Key entgegen.
Ist CODECHARTER_API_KEY in der Umgebung gesetzt, holt und erneuert die CLI
die kurzlebige Lizenz automatisch vom Portal. Die Befehle update, push
und verify --against-portal nehmen den Key stattdessen über ihre Option
--api-key entgegen.
API-Keys können keine Regeln oder Profile veröffentlichen oder als Entwurf anlegen: Entwürfe erstellen oder bearbeiten, Versionen veröffentlichen und Archivieren geht ausschließlich in einer eingeloggten Browser-Sitzung im Portal. In Bezug auf Ihre Regel- und Profilinhalte ist ein Key strikt lesend.
Rate-Limits
API-Anfragen ans Portal sind pro Identität limitiert. Jeder API-Key hat sein eigenes Kontingent; Anfragen aus einer eingeloggten Browser-Sitzung zählen stattdessen auf das Benutzerkonto. Die Standardwerte:
- 60 GET-Anfragen pro Minute
- 10 Schreib-Anfragen pro Minute (POST, PUT, PATCH, DELETE)
Lese- und Schreibzugriffe haben getrennte Kontingente. Das Fenster sind feste 60 Sekunden ab der ersten Anfrage; am Ende des Fensters steht wieder das volle Kontingent zur Verfügung. Downloads der CLI-Release-Archive und der Endpunkt für die kurzlebige Lizenz sind nicht limitiert.
Ist ein Kontingent aufgebraucht, antwortet das Portal mit
429 Too Many Requests. Die Antwort enthält einen Retry-After-Header
mit der Anzahl Sekunden bis zum Zurücksetzen des Fensters sowie einen
JSON-Body, der den Wert im Feld retryAfter wiederholt. Warten Sie so
lange und versuchen Sie es erneut.
In der Praxis bleibt ein CI-Lauf weit unter diesen Limits, restore macht
nur eine Handvoll Anfragen. Wenn Sie doch 429 sehen, sind meist viele
parallele Jobs mit demselben Key die Ursache. Cachen Sie das
heruntergeladene CLI-Archiv, statt es in jedem Job neu zu laden, und cachen
Sie das Bundle-Verzeichnis (.codecharter/cache/) mit dem Lockfile als
Cache-Key, damit wiederholte Läufe gar keine Portal-Aufrufe machen, siehe
Portal-Profile im CI verwenden. Da jeder Key
sein eigenes Kontingent hat, verhindern getrennte Keys für unabhängige
Pipelines außerdem, dass diese sich gegenseitig ausbremsen.
Was passiert beim Trial-Ende
Wenn Ihre Subscription abgelaufen ist, geben Keys ab dem nächsten Aufruf 402 Payment Required zurück. Der Key bleibt aktiv, aber unbrauchbar. Sobald die Subscription wieder läuft, funktioniert der Key wieder ohne Änderung.
Audit
In der API-Key-Liste sehen Sie pro Key:
- Name und Key-Präfix (die ersten 12 Zeichen)
- Wann erzeugt
- Wann zuletzt benutzt
- Wann er abläuft
- Aktueller Status (aktiv / widerrufen / abgelaufen)
- Seine Scopes
Sie können einen Key direkt in der Liste über das Stift-Symbol umbenennen (bis zu 120 Zeichen). Ein abgelaufener Key wird mit 401 abgelehnt, genau wie ein widerrufener.
Wird ein Key nie benutzt, ist das ein Signal, ihn zu widerrufen. Zeigt "zuletzt benutzt" Aktivität, die Sie nicht erwarten, schauen Sie genauer hin, wo der Key im Einsatz ist.
Mehrere Keys parallel
Sinnvoll, wenn Sie unterschiedliche CI-Setups haben, z.B. einen Key für die Haupt-CI und einen separaten für einen Build-Server in einer isolierten Umgebung. So können Sie einen widerrufen, ohne den anderen zu treffen.
Es gibt derzeit kein hartes Limit für Keys pro Account.