Die CLI braucht eine gültige Lizenz, um zu laufen, und sie kann sich diese aus zwei verschiedenen Credentials selbst besorgen: einem API-Key oder einem Device-Token aus einer Browser-Anmeldung. Diese Seite erklärt, was wohin gehört, und was passiert, wenn eine Maschine beides hat.
Welches Credential für welche Maschine
| Situation | Mittel | Warum |
|---|---|---|
| Entwickler-Workstation, Laptop | codecharter login |
Kein Secret zum Herumkopieren, pro Maschine im Portal widerrufbar |
| CI-Runner, Build-Agent, Container | API-Key als CODECHARTER_API_KEY |
Unbeaufsichtigt, kein Browser, ein Secret für alle Jobs der Pipeline |
| Maschine ohne Netzzugang | Heruntergeladene Lizenzdatei | Es gibt keine Gegenstelle, bei der erneuert werden kann |
Kurz gesagt: Eine Browser-Anmeldung weist eine Person auf einer Maschine aus, ein API-Key weist eine Pipeline aus. Ein Device-Token gehört der Person, die es bestätigt hat, und lässt sich widerrufen, ohne jemand anderen zu treffen. Ein API-Key ist ein geteiltes, langlebiges Secret, das einzelne Jobs überdauert, genau das, was ein Runner braucht und genau das, was Sie nicht auf einem Laptop liegen haben wollen.
Ein API-Key darf mehr als ein Device-Token, das ist der zweite Grund, beides
nicht zu vermischen. Ein Key trägt read:rules und optional write:rules, kann
Ihre Regeln und Profile also lesen und, sofern erteilt, Entwürfe hochladen. Ein
Device-Token kann ausschließlich eine Lizenz erneuern, siehe
Browser-Anmeldung.
Welches Credential die Lizenz erneuert
Wenn die CLI eine frische Lizenz braucht, löst sie das Credential in dieser Reihenfolge auf:
- Die Umgebungsvariable
CODECHARTER_API_KEY, sofern sie gesetzt und nicht leer ist. - Das von
codecharter logingespeicherte Device-Token, sofern diese Maschine angemeldet ist.
Der erste Treffer gewinnt. Ist keines von beidem vorhanden, erneuert die CLI nicht und fällt auf die Lizenzdatei zurück, die sie findet; ohne eine gültige beendet sie sich mit Exit-Code 6.
Warum die Umgebungsvariable gewinnt
Diese Reihenfolge ist Absicht. Ein CI-Job, der CODECHARTER_API_KEY auf einer
Maschine setzt, auf der sich einmal jemand angemeldet hat, muss das
CI-Credential verwenden und nicht stillschweigend die Identität dieser Person
übernehmen. Die Variable zu setzen ist eine ausdrückliche Entscheidung pro
Aufruf, ein gespeichertes Device-Token dagegen Zustand von irgendeinem früheren
Tag. Deshalb gewinnt die ausdrückliche Entscheidung.
Praktisch heißt das: Sie müssen sich nie abmelden, bevor Sie einen CI-Job lokal ausführen, und ein selbst gehosteter Runner auf einer geteilten Maschine kann nicht versehentlich Lizenzaktivität unter dem Account einer anderen Person erzeugen.
Welches Credential auf einer Maschine tatsächlich greift, zeigt:
codecharter auth status
Wo die Lizenzdatei hineinpasst
Die Auflösung des Credentials und die Suche nach der Lizenz sind zwei getrennte Schritte. Bevor überhaupt etwas erneuert wird, sucht die CLI nach einer brauchbaren Lizenzdatei, und findet sie eine mit mehr als einer Stunde Restlaufzeit, nutzt sie diese und fasst gar kein Credential an. Der vollständige Suchpfad steht unter Lizenzdatei.
Zwei Einträge davon sind Festlegungen, die eine Erneuerung nie überschreibt: ein
per --license übergebener Pfad und die Umgebungsvariable
CODECHARTER_LICENSE. Damit legen Sie eine bestimmte Datei fest, etwa auf einer
Maschine, die auf einer Offline-Lizenz bleiben muss.
Die Option --api-key
Einige Befehle sprechen das Portal für etwas anderes als eine Lizenz an und
nehmen einen Key direkt per --api-key entgegen: update, push,
rules search und verify --against-portal. Wo die Option angeboten wird,
gewinnt ein ausdrücklich übergebener Key gegenüber dem, was die CLI für diesen
Aufruf sonst verwenden würde. Optional ist sie bei allen vieren, ohne sie
greifen die Befehle auf die installierte Lizenz zurück.
Das ist ein eigener Mechanismus, getrennt von der Lizenzerneuerung. Ein an einen
dieser Befehle übergebener --api-key ändert nicht, welches Credential Ihre
Lizenz erneuert, dafür gilt weiterhin die Reihenfolge oben.
Abmelden und widerrufen
Ein Credential zu entfernen und es abzuschalten sind zwei verschiedene Dinge:
| Ziel | Vorgehen |
|---|---|
| Das Device-Token auf dieser Maschine nicht mehr nutzen | codecharter logout |
| Eine Maschine dauerhaft aussperren | Gerät auf /api-keys widerrufen, siehe Autorisierte Geräte |
| Einen CI-Key abschalten | Key auf /api-keys widerrufen, siehe API-Keys verwalten |
Ein Widerruf wirkt für Erneuerungen sofort. Eine bereits ausgestellte Lizenz läuft weiter, bis sie abläuft, also höchstens 24 Stunden.
Faustregeln
- Legen Sie nie einen API-Key auf eine Entwicklermaschine, wenn eine Browser-Anmeldung reicht. Ein Key auf einem Laptop ist ein geteiltes Secret an einem unverwalteten Ort.
- Verwenden Sie nie eine Browser-Anmeldung für die CI. Sie braucht einen Browser und bindet Ihre Pipeline an den Account einer einzelnen Person.
- Ein Key pro Pipeline, damit Sie einen widerrufen können, ohne die anderen anzuhalten.
- Melden Sie sich pro Maschine an. Die Datei
codecharter.device-tokenauf eine zweite Maschine zu kopieren bringt nichts: Beide teilen sich dann einen Eintrag im Portal, und Sie verlieren die Möglichkeit, sie einzeln zu widerrufen.