Skip to content

API-Keys in Secrets

Wie Sie API-Keys sicher in Ihrem CI-System hinterlegen und ersetzen.

Aktualisiert am 2026-07-13

Der API-Key authentifiziert Ihre CI gegen das CodeCharter-Portal. Er ist genauso sensibel wie das Passwort einer Produktionsdatenbank und sollte auch so behandelt werden.

Wo Keys hingehören

CI-System Speicherort
GitHub Actions Repository Secrets oder Org Secrets
GitLab CI Project Variables (Protected, Masked)
Azure DevOps Library Variable Groups, secret-locked
Bitbucket Pipelines Repository Variables, Secured
TeamCity Project Parameter, Type "Password"
Jenkins Credentials Manager, "Secret text"

Unabhängig vom Speicherort: Stellen Sie das Secret dem Build als Umgebungsvariable CODECHARTER_API_KEY bereit, denn das ist die Variable, die die CLI automatisch liest.

Wo Keys NICHT hingehören

  • Nie ins Repo committen. Auch nicht "nur kurz zum Testen". Git-History ist permanent, ein einmal exponierter Key ist verbrannt.
  • Nicht in Logs. Wenn Sie in einem Skript echo "Key: $CODECHARTER_API_KEY" ausführen, taucht er im Build-Log auf und damit potenziell auch in Artefakten und Sicherheits-Scans.
  • Nicht in .env-Dateien, die Sie versehentlich in Backups, Slack-Threads oder Wikis verschicken.

Maskieren in CI-Logs

Die meisten CI-Systeme maskieren Secret-Variables automatisch im Log, wenn sie als Secret markiert sind. Achten Sie trotzdem auf Folgendes:

# Schlecht, das Token landet als URL-Parameter im Log
curl "https://example.com/?token=$CODECHARTER_API_KEY"

# Besser, als Header, der nicht protokolliert wird
curl -H "Authorization: Bearer $CODECHARTER_API_KEY" https://example.com/

Key austauschen

Wenn ein Key kompromittiert ist oder ein Team-Mitglied geht, das den Klartext gesehen haben könnte, ersetzen Sie ihn so:

  1. Im Portal unter API Keys einen neuen Key erzeugen.
  2. Den neuen Key im CI-System hinterlegen (Update der Secret-Variable).
  3. Einmal CI laufen lassen, prüfen, dass alles grün ist.
  4. Den alten Key im Portal widerrufen.

Mehrere Keys dürfen gleichzeitig aktiv sein, deshalb können Sie in Schritt 2 und 3 in Ruhe umstellen, bevor Sie in Schritt 4 den alten widerrufen. Der Widerruf ist endgültig, ein widerrufener Key lässt sich nicht wieder aktivieren.

Ein Vorbehalt: Die CLI cacht die mit dem Key geholte kurzlebige Lizenz bis zu 24 Stunden pro Runner. Ein grüner Lauf in Schritt 3 kann also noch auf einer Lizenz des alten Keys laufen, und Läufe können nach dem Widerruf des alten Keys noch bis zu 24 Stunden erfolgreich sein.

Pro Repo oder pro Team?

Die Standardempfehlung ist ein Key pro Repository (oder pro CI-Job-Familie). Das begrenzt den Schaden bei einem kompromittierten Key: ein geleakter Key für ein Repo setzt nicht die Pipelines aller anderen Repos aufs Spiel.

  • Ein Key pro Repo ist der sichere Standard nach dem Least-Privilege-Prinzip. Wird das Secret eines Repos exponiert, bleiben die anderen unberührt.
  • Ein gemeinsamer Key pro Team oder Job-Familie ist ein Komfort-Kompromiss, akzeptabel, wenn alle Repos dasselbe Vertrauensniveau haben und Key-Rotation automatisiert ist. Niemals einen Key zwischen einem öffentlichen und einem privaten Repo teilen.
  • Nicht ein Key pro Entwickler. Keys gehören zu CI-Jobs, nicht zu Personen.
  • Aussagekräftige Namen. Im Portal können Sie dem Key einen Namen geben. acme-web-ci ist gut, prod-key ist okay, key ist nicht hilfreich beim Audit.

Kompromittiert, was tun

  1. Key sofort im Portal widerrufen.
  2. Neuen Key erzeugen.
  3. CI-Secret-Variable aktualisieren.
  4. Den Zeitstempel Zuletzt benutzt des Keys auf der API-Keys-Seite auf unerwartete Aktivität prüfen.
  5. Falls der Key öffentlich (z.B. in einem PR) exponiert war: GitHub Secret Scanning meldet sich in der Regel automatisch. Der Widerruf im Portal ist der einzige Weg, dem Key den Zugriff zu entziehen. Beachten Sie: Bereits mit dem Key ausgestellte Lizenz-Tokens bleiben bis zu 24 Stunden gültig und lassen sich nicht zurückrufen.

Lebenszyklus

Im Portal können Sie pro Key eine Gültigkeitsdauer setzen: 30 Tage, 90 Tage, 1 Jahr (der Standard) oder nie. Nach Ablauf wird der Key automatisch deaktiviert.

Eine Pipeline, die beim Ablauf bereits läuft, wird ohne Unterbrechung abgeschlossen: Die CLI prüft die Lizenz einmal beim Start eines Kommandos und tauscht den Key gegen eine kurzlebige Lizenz mit 24 Stunden Gültigkeit. Da diese Lizenz pro Runner gecached wird, können neue Runs nach dem Ablauf noch bis zu 24 Stunden weiterlaufen, bevor sie mit Exit-Code 6 fehlschlagen, wenn die CLI keine Lizenz mehr beziehen kann. Auf ephemeren Runnern ohne Cache schlagen sie sofort fehl. Richten Sie Key-Rotation vor dem Ablauf ein, um ungeplante CI-Ausfälle zu vermeiden.

Sinnvoll für temporäre Keys, z.B. für eine externe Beratungsfirma, die Ihre CI temporär anbindet.

Siehe API-Keys verwalten.