Ein Profil fasst eine Menge von Regeln zu einer versionierten Einheit zusammen. Statt einzelne Regeldateien in eure CI zu kopieren, referenziert ihr ein Profil mit einer exakten Version. CodeCharter löst dann alle enthaltenen Regeln auf und stellt sie als signiertes Bundle bereit.
Was ein Profil ist
Jedes Profil hat einen unveränderlichen Slug, einen optionalen Anzeigenamen und eine
Beschreibung. Über den Slug referenziert ihr das Profil in eurer .codecharter/config.yml.
Der Slug ist nach der Erstellung nicht mehr änderbar; wählt ihn daher sprechend,
zum Beispiel backend-standards oder api-security.
Versionen eines Profils sind unveränderlich: einmal veröffentlicht, bleibt eine Version byte-eingefroren. Eure CI-Pipelines bekommen damit reproduzierbare Ergebnisse, auch wenn ihr das Profil später weiterentwickelt.
Profil anlegen
Wählt auf der Profile-Seite oben rechts Neues Profil. Ihr vergebt einen Slug (3 bis 64 Zeichen, Kleinbuchstaben, Ziffern und Bindestriche), optional einen Anzeigenamen und eine Beschreibung. Das Profil startet ohne veröffentlichte Version und ohne Entwurf.
Regeln ins Profil aufnehmen
Wählt in der Profilliste im Kebab-Menü (⋮) der Zeile Bearbeiten, oder öffnet das Profil und wählt Bearbeiten. Damit gelangt ihr in den Profil-Editor, in dem ihr Regeln aus eurer Regelbibliothek auswählt.
Für jede aufgenommene Regel legt ihr fest:
- Version: Jede aufgenommene Regel ist auf eine exakte veröffentlichte Version gepinnt. Ein neues Rule-Release verändert euer Profil daher nie von selbst. Ihr aktualisiert den Pin gezielt, entweder pro Regel oder mit Alle auf neueste Version (siehe unten).
- Severity-Override: Optional könnt ihr den Standard-Schweregrad der Regel überschreiben. Nützlich, wenn eine Regel in eurem Kontext kritischer (oder weniger kritisch) ist als ihr Default. Mit der Option Deaktiviert könnt ihr eine Regel innerhalb des Profils auch ganz abschalten.
Wählt Speichern, um eure Änderungen als Entwurf zu sichern; Entwürfe haben keinen Einfluss auf veröffentlichte Versionen. Verwerfen löscht den Entwurf nach einer Bestätigung.
Bulk-Bump auf neueste Version
Wenn ihr alle gepinnten Regeln auf ihre jeweils neueste veröffentlichte Version heben möchtet, wählt im Profil-Editor neben der Überschrift Im Profil Alle auf neueste Version. Der Editor zeigt euch für jede Regel die aktuelle und die neue Version zum Vergleich, bevor ihr bestätigt.
Version veröffentlichen
Um einen Entwurf zu veröffentlichen, wählt im Profil-Editor Veröffentlichen. Ihr vergebt eine SemVer-Versionsnummer (muss größer als die letzte veröffentlichte Version sein) und optional Release Notes.
Der Veröffentlichen-Dialog listet unter Enthaltene Regeln alle Regeln der neuen Version auf. Nach dem Veröffentlichen könnt ihr im Reiter Versionsverlauf des Profils zwei beliebige veröffentlichte Versionen vergleichen: Der Diff zeigt, welche Regeln hinzugekommen sind, welche entfernt wurden und welche sich in Version oder Schweregrad geändert haben.
Einmal veröffentlichte Versionen sind byte-eingefroren und können nicht mehr geändert werden.
Bundle herunterladen
Über das Kebab-Menü (⋮) in der Profilliste könnt ihr die neueste veröffentlichte
Version als signierte .cgbundle-Datei herunterladen. Ältere veröffentlichte
Versionen erhaltet ihr über Bundle herunterladen auf der Detailseite des
Profils. Das Bundle enthält:
- Alle referenzierten Regeldateien (
.cgr) in der gepinnten Version - Eine Manifest-Datei mit Metadaten und einem Inhalts-Hash
- Eine Ed25519-Signatur
Ihr könnt dieses Bundle manuell prüfen oder direkt in Offline-Setups verwenden, in denen eure CI keinen Internetzugang hat. Für den regulären CI-Einsatz mit Internetzugang empfehlen wir die direkte API-Anbindung, siehe Plattform-Profile nutzen.
Archivieren
Archiviert ein Profil, wenn es nicht mehr aktiv gepflegt werden soll. Archivierte Profile werden aus der aktiven Liste ausgeblendet und sind dafür gedacht, nicht weiter verändert zu werden. Auf bereits veröffentlichte Versionen kann eure CI weiterhin zugreifen; Lockfiles werden weiter aufgelöst.
Wählt im Kebab-Menü (⋮) einer Profilzeile in der Profilliste Archivieren, oder öffnet das Profil und wählt dort Archivieren. Ein Bestätigungsdialog weist noch einmal auf die Auswirkungen hin, bevor das Profil archiviert wird. Hat das Profil einen offenen Entwurf, ist das Archivieren blockiert, bis ihr diesen Entwurf veröffentlicht oder verworfen habt.
Wiederherstellen
Das Archivieren ist vollständig reversibel; ihr könnt es selbst rückgängig machen, ohne den Support zu kontaktieren. Öffnet dazu den Reiter Archiv in der Profilliste, sucht das archivierte Profil und wählt im Kebab-Menü Wiederherstellen. Das Profil erscheint danach sofort wieder in der aktiven Liste und kann bearbeitet werden.
Profile in der CI verwenden
Tragt den Profil-Slug und die Version in eure .codecharter/config.yml ein:
# .codecharter/config.yml
version: 1
profiles:
- "backend-standards@1.3.0"
Nachdem ihr einen Profil-Verweis hinzugefügt oder geändert habt, führt lokal
codecharter update aus, um das Lockfile neu aufzulösen und zu schreiben. Der Befehl
verwendet standardmäßig das gehostete Portal und authentifiziert sich mit eurer
installierten Lizenz, ein bloßes codecharter update reicht also meist aus. Für ein
selbst gehostetes Portal übergebt ihr --portal-url; alternativ zur installierten
Lizenz könnt ihr euch optional mit einem API-Key mit dem Scope read:rules
authentifizieren, den ihr auf der API-Keys-Seite des Portals erstellt:
codecharter update --portal-url https://portal.example.com --api-key <euer-API-Key>
Beachtet, dass API-Keys in Bezug auf Profile nur lesen können: Ein Key kann keine Entwürfe anlegen oder bearbeiten, keine Versionen veröffentlichen und keine Profile archivieren. Diese Aktionen stehen nur in einer eingeloggten Browser-Sitzung im Portal zur Verfügung.
Committet .codecharter/config.yml und .codecharter/codecharter.lock.json gemeinsam. In der CI lädt
codecharter restore das Bundle anhand des Lockfiles herunter, ohne Auflösungsaufrufe
ans Portal zu schicken. Den vollständigen Aufbau der Datei findet ihr unter
Konfigurationsdatei.