Lokale Regeln per push ins CodeCharter-Portal hochladen

Wie ihr lokal entwickelte .ccr-Regeln mit codecharter push ins Portal hochladet und dort versioniert.

Aktualisiert am 2026-09-01

Wenn ihr Regeln lokal entwickelt, zum Beispiel mit der VS-Code-Extension oder direkt in einem Texteditor, könnt ihr 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

Ihr braucht:

Eine CodeCharter-CLI mit dem push-Befehl. Prüft die installierte Version mit codecharter --version. Für ein Upgrade lest ihr 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 ihr über die Option --api-key übergebt (ihr könnt 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 ihr den Lauf prüfen könnt:

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 ihr echte Entwürfe öffnet.

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önnt ihr:

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.

Lokale Regeln in euren Läufen

push lädt das Verzeichnis hoch, ändert aber nicht, welche Regeln eure Analyse ausführt. Seit CodeCharter 1.6.4 kommt ein lokales Verzeichnis nur in einen Lauf, wenn es unter rules: in .codecharter/config.yml deklariert ist (oder mit --rules übergeben wird), und es läuft zusätzlich zu den deklarierten Profilen:

profiles:
  - my-team-rules@1.0.0
rules:
  - rules

Solange beide deklariert sind, kommt eine Regel-ID, die im Profil und im Verzeichnis existiert, aus dem Verzeichnis, der späteren Quelle, und der Lauf nennt die überdeckte ID. Sobald das veröffentlichte Profil eure Regeln abdeckt, entfernt den rules:-Eintrag (codecharter config remove rules rules), damit sie nur noch aus dem Profil laufen.

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. Verwerft oder veröffentlicht diesen Entwurf im Portal und pusht 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. Übergebt einen API-Key mit --api-key, setzt die Umgebungsvariable CODECHARTER_API_KEY, oder installiert 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üft 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üft, 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.