Ein Profil fasst eine Menge von Regeln zu einer versionierten Einheit zusammen. Statt einzelne Regeldateien in Ihre CI zu kopieren, referenzieren Sie 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 referenzieren Sie das Profil in Ihrer .codecharter/config.yml.
Der Slug ist nach der Erstellung nicht mehr änderbar; wählen Sie ihn daher sprechend,
zum Beispiel backend-standards oder api-security.
Versionen eines Profils sind unveränderlich: einmal veröffentlicht, bleibt eine Version byte-eingefroren. Ihre CI-Pipelines bekommen damit reproduzierbare Ergebnisse, auch wenn Sie das Profil später weiterentwickeln.
Profil anlegen
Klicken Sie auf der Profile-Seite oben rechts auf Neues Profil. Sie vergeben 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ählen Sie in der Profilliste im Kebab-Menü (⋮) der Zeile Bearbeiten, oder öffnen Sie das Profil und klicken Sie auf Bearbeiten. Damit gelangen Sie in den Profil-Editor, in dem Sie Regeln aus Ihrer Regelbibliothek auswählen.
Für jede aufgenommene Regel legen Sie fest:
- Version: Jede aufgenommene Regel ist auf eine exakte veröffentlichte Version gepinnt. Ein neues Rule-Release verändert Ihr Profil daher nie von selbst. Sie aktualisieren den Pin gezielt, entweder pro Regel oder mit Alle auf neueste Version (siehe unten).
- Severity-Override: Optional können Sie den Standard-Schweregrad der Regel überschreiben. Nützlich, wenn eine Regel in Ihrem Kontext kritischer (oder weniger kritisch) ist als ihr Default. Mit der Option Deaktiviert können Sie eine Regel innerhalb des Profils auch ganz abschalten.
Klicken Sie auf Speichern, um Ihre Ä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 Sie alle gepinnten Regeln auf ihre jeweils neueste veröffentlichte Version heben möchten, klicken Sie im Profil-Editor neben der Überschrift Im Profil auf Alle auf neueste Version. Der Editor zeigt Ihnen für jede Regel die aktuelle und die neue Version zum Vergleich, bevor Sie bestätigen.
Version veröffentlichen
Um einen Entwurf zu veröffentlichen, klicken Sie im Profil-Editor auf Veröffentlichen. Sie vergeben 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önnen Sie 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önnen Sie die neueste veröffentlichte
Version als signierte .cgbundle-Datei herunterladen. Ältere veröffentlichte
Versionen erhalten Sie ü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
Sie können dieses Bundle manuell prüfen oder direkt in Offline-Setups verwenden, in denen Ihre CI keinen Internetzugang hat. Für den regulären CI-Einsatz mit Internetzugang empfehlen wir die direkte API-Anbindung, siehe Plattform-Rules nutzen.
Archivieren
Archivieren Sie 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 Ihre CI weiterhin zugreifen; Lockfiles werden weiter aufgelöst.
Öffnen Sie das Profil und klicken Sie auf Archivieren. Ein Bestätigungsdialog weist noch einmal auf die Auswirkungen hin, bevor das Profil archiviert wird.
Wiederherstellen
Das Archivieren ist vollständig reversibel; Sie können es selbst rückgängig machen, ohne den Support zu kontaktieren. Öffnen Sie dazu den Reiter Archiv in der Profilliste, suchen Sie das archivierte Profil und wählen Sie im Kebab-Menü Wiederherstellen. Das Profil erscheint danach sofort wieder in der aktiven Liste und kann bearbeitet werden.
Profile in der CI verwenden
Tragen Sie den Profil-Slug und die Version in Ihre .codecharter/config.yml ein:
# .codecharter/config.yml
version: 1
profiles:
- "[email protected]"
Nachdem Sie einen Profil-Verweis hinzugefügt oder geändert haben, führen Sie lokal
codecharter update aus, um das Lockfile neu aufzulösen und zu schreiben. Der Befehl
benötigt Ihre Portal-URL und einen API-Key mit dem Scope read:rules, den Sie auf
der API-Keys-Seite des Portals erstellen:
codecharter update --portal-url https://portal.example.com --api-key <Ihr-API-Key>
Beachten Sie, 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.
Committen Sie .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 finden Sie unter
Konfigurationsdatei.