Lokale Regeln per push ins CodeCharter-Portal hochladen

Wie Sie lokal entwickelte .ccr-Regeln mit codecharter push ins Portal hochladen und dort versionieren.

Aktualisiert am 2026-09-01

Wenn Sie Regeln lokal entwickeln, zum Beispiel mit der VS-Code-Extension oder direkt in einem Texteditor, können Sie sie mit codecharter push ins Portal hochladen. Der Befehl durchsucht ein Verzeichnis nach .ccr-Dateien, lädt sie als Regel-Entwürfe hoch und legt einen Profil-Entwurf im Portal an, ohne die aktuell veröffentlichte Version zu berühren. Hat eine Regel oder das Profil bereits einen offenen Entwurf im Portal, bricht der Push mit einem Konflikt ab, statt ihn zu überschreiben.

Voraussetzungen

Sie brauchen:

Eine CodeCharter-CLI mit dem push-Befehl. Prüfen Sie die installierte Version mit codecharter --version. Für ein Upgrade lesen Sie den Abschnitt Downloads.
Einen Zugang zum Portal: entweder ein installiertes codecharter.license (Standardfall, keine weitere Option nötig) oder einen API-Key mit dem Recht write:rules, den Sie über die Option --api-key übergeben (Sie können den Key in einer Umgebungsvariable ablegen und auf der Kommandozeile übergeben, wie in den Beispielen unten)
Eine .ccr-Datei pro Regel, optional eine gleichnamige .spec.md daneben

Verzeichnisstruktur

codecharter push arbeitet auf einem Verzeichnis und durchsucht es rekursiv nach .ccr-Dateien:

rules/
  no-async-void.ccr
  no-async-void.spec.md
  max-method-length.ccr

Kanonische Verwendung

codecharter push ./rules \
  --profile my-team-rules \
  --version 1.0.0 \
  --portal-url https://codecharter.tools \
  --api-key $CODECHARTER_API_KEY

Das durchsucht ./rules rekursiv nach .ccr-Dateien. Der Regel-Slug wird aus dem Dateinamen abgeleitet (ohne die Endung .ccr), also wird aus no-async-void.ccr der Slug no-async-void. Eine gleichnamige .spec.md-Datei wird automatisch mit hochgeladen. Der Lauf erstellt den Profil-Entwurf my-team-rules@1.0.0 aus diesen Regeln. Hat das Profil bereits einen offenen Entwurf, schlägt der Push mit einem Konflikt fehl, damit keine laufende Arbeit überschrieben wird.

--portal-url und --api-key sind hier nur zur Veranschaulichung gesetzt: --portal-url fällt ohne Angabe auf das gehostete Portal zurück, und --api-key fällt ohne Angabe auf die installierte codecharter.license zurück.

Bei Erfolg gibt die CLI eine Zusammenfassung aus, an der Sie den Lauf prüfen können:

Pushed 2 of 2 rule(s); profile draft 'my-team-rules@1.0.0' created.

Die Regeldatei braucht keinen Deklarationsblock: Der Slug kommt aus dem Dateinamen, der Schweregrad aus der @severity-Direktive in der Regeldatei (Standard: warn, falls die Direktive fehlt). codecharter push lädt den Dateiinhalt unverändert hoch; die Direktive wirkt, wenn die Regel geladen wird.

Trockenlauf

codecharter push ./rules \
  --profile my-team-rules \
  --version 1.0.0 \
  --portal-url https://codecharter.tools \
  --api-key $CODECHARTER_API_KEY \
  --dry-run

--dry-run listet die Regeln und den Profil-Entwurf auf, die gepusht würden, ohne etwas hochzuladen. Nützlich zur Kontrolle, bevor Sie echte Entwürfe öffnen.

Optionen

Option	Pflicht	Beschreibung
`--profile <slug>`	ja	Der Profil-Slug, der angelegt oder aktualisiert werden soll.
`--version <semver>`	ja	Semantische Versionsnummer des Profil-Entwurfs (z.B. `1.0.0`).
`--portal-url <url>`	nein	URL des CodeCharter-Portals. Ohne Angabe wird das gehostete Portal verwendet; nur für ein selbst gehostetes Portal setzen.
`--api-key <key>`	nein	API-Key zur Authentifizierung gegenüber dem Portal (benötigt den Scope `write:rules`). Ohne Angabe wird die installierte Lizenz verwendet.
`--license <pfad>`	nein	Pfad zu einer `codecharter.license`-Datei, überschreibt die Standard-Suche.
`--dry-run`	nein	Zeigt Aktionen ohne Upload.

Exit-Codes

Code	Bedeutung
`0`	Alle Entwürfe erfolgreich angelegt (oder Trockenlauf abgeschlossen).
`1`	Eine Regel oder das Profil hat bereits einen konfliktierenden Entwurf.
`2`	Bedienfehler, E/A-Fehler oder Netzwerkfehler.

Nach dem Push

Nach einem erfolgreichen push erscheint die Regel im Portal unter /rules mit dem Entwurf-Badge. Von dort können Sie:

die Spec im Portal ausführen (Specs ausführen)
eine neue Version veröffentlichen (Veröffentlichen)

Ein Push veröffentlicht nie selbst. Das bleibt bewusst ein manueller Schritt im Portal.

Hat eine gepushte Regel noch keine veröffentlichte Version, verweist der Profil-Entwurf auf den Regel-Entwurf und die CLI warnt:

warning: rule 'no-async-void' has no published version yet; profile references the draft.

Häufige Fehler

Konfliktierender Entwurf

error: Rule 'no-async-void' already has a draft. Discard or publish it first.

error: Profile 'my-team-rules' already has a draft. Discard or publish it first.

Eine Regel oder das Profil hat bereits einen offenen Entwurf im Portal. Verwerfen oder veröffentlichen Sie diesen Entwurf im Portal und pushen Sie dann erneut. Der Befehl endet mit Exit-Code 1.

Kein Portal-Zugang

error: no portal credential available. Pass --api-key, set CODECHARTER_API_KEY, or install a codecharter.license (point at it with --license).

Weder ein API-Key noch eine gültige installierte Lizenz sind verfügbar. Übergeben Sie einen API-Key mit --api-key, setzen Sie die Umgebungsvariable CODECHARTER_API_KEY, oder installieren Sie eine codecharter.license (bei einem abweichenden Speicherort mit --license darauf verweisen). Der Befehl endet mit Exit-Code 2.

Keine Regeldateien gefunden

error: no rule files (.ccr) found in './rules'.

Das Verzeichnis enthält keine unterstützten Regeldateien (.ccr, oder das veraltete .cgr; die Suche ist rekursiv). Prüfen Sie den übergebenen Pfad. Der Befehl endet mit Exit-Code 2.

Portal lehnt die Anfrage ab

error: portal returned 401 Unauthorized for rule 'no-async-void'.

Das Portal hat den Upload abgelehnt. Prüfen Sie, ob der verwendete API-Key oder die installierte Lizenz gültig und nicht abgelaufen ist und ob --portal-url auf das richtige Portal zeigt. Der Befehl endet mit Exit-Code 2.