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 | Validiert offline bis zum Ablaufdatum |
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 du nicht auf einem Laptop liegen haben willst.
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
deine 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: Du musst dich nie abmelden, bevor du einen CI-Job lokal ausführst, 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 legst du eine bestimmte Datei fest, etwa auf einer
Maschine, die auf einer Offline-Lizenz bleiben muss.
Welches Credential einen Portal-Aufruf authentifiziert
Einige Befehle sprechen das Portal für etwas anderes als eine Lizenz an:
update, restore, push, rules search und verify --against-portal. Sie
ermitteln das Credential für diesen Aufruf in derselben Reihenfolge:
- Ein ausdrücklich übergebener
--api-key, wo der Befehl die Option anbietet (update,push,rules search,verify --against-portal). - Die Umgebungsvariable
CODECHARTER_API_KEY, wenn sie gesetzt und nicht leer ist. - Die installierte Lizenz, als kurzlebiges JWS.
Die Umgebungsvariable gewinnt gegenüber der Lizenz aus demselben Grund, aus dem sie bei der Erneuerung gegenüber einem gespeicherten Gerätetoken gewinnt: Sie zu setzen ist eine ausdrückliche Entscheidung für diesen Aufruf, während eine Lizenzdatei beiläufiger Zustand von einem früheren Tag ist und zu einem anderen Konto gehören kann. Ein Profil deiner Organisation ist nur für diese Organisation sichtbar, ein Aufruf unter der falschen Identität wirkt also nicht bloß seltsam, sondern scheitert mit einem "nicht gefunden".
Ein an einen dieser Befehle übergebener --api-key ändert weiterhin nicht,
welches Credential deine Lizenz erneuert, dafür gilt 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
- Leg 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.
- Verwende nie eine Browser-Anmeldung für die CI. Sie braucht einen Browser und bindet deine Pipeline an den Account einer einzelnen Person.
- Ein Key pro Pipeline, damit du einen widerrufen kannst, ohne die anderen anzuhalten.
- Melde dich pro Maschine an. Die Datei
codecharter.device-tokenauf eine zweite Maschine zu kopieren bringt nichts: Beide teilen sich dann einen Eintrag im Portal, und du verlierst die Möglichkeit, sie einzeln zu widerrufen.