Lokale Regeln importieren

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

Aktualisiert am 2026-06-10

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 .cgr-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 gültigen API-Key, der über die Pflichtoption --api-key übergeben wird (Sie können den Key in einer Umgebungsvariable ablegen und auf der Kommandozeile übergeben, wie in den Beispielen unten)
Eine .cgr-Datei pro Regel, optional eine gleichnamige .spec.md daneben

Verzeichnisstruktur

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

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

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 .cgr-Dateien. Der Regel-Slug wird aus dem Dateinamen abgeleitet (ohne die Endung .cgr), also wird aus no-async-void.cgr der Slug no-async-void. Eine gleichnamige .spec.md-Datei wird automatisch mit hochgeladen. Der Lauf erstellt den Profil-Entwurf [email protected] aus diesen Regeln. Hat das Profil bereits einen offenen Entwurf, schlägt der Push mit einem Konflikt fehl, damit keine laufende Arbeit überschrieben wird.

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

Pushed 2 rule(s); profile draft '[email protected]' created.

Es gibt keinen rule:- oder severity:-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>`	ja	URL des CodeCharter-Portals.
`--api-key <key>`	ja	API-Key zur Authentifizierung gegenüber dem Portal.
`--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)
den Live-Trial nutzen, um die Regel gegen eigenen C#-Code zu testen
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.

API-Key fehlt

error: --api-key is required.

Übergeben Sie den Key mit --api-key. Der Befehl endet mit Exit-Code 2.

Keine Regeldateien gefunden

error: no .cgr files found in './rules'.

Das Verzeichnis enthält keine .cgr-Dateien (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 API-Key gültig und nicht abgelaufen ist und ob --portal-url auf das richtige Portal zeigt. Der Befehl endet mit Exit-Code 2.