Zum Inhalt springen

CodeCharter-Regelbundles in Air-Gap- und Offline-CI nutzen

Ein signiertes Bundle aus dem Portal exportieren und direkt in Air-Gap- oder vollständig offline arbeitender CI einsetzen, ohne Portal-Zugriff zur Analysezeit.

Aktualisiert am 2026-09-01

Mit Offline-Bundles nutzt ihr Plattform-Profile und eigene Profile in Umgebungen ohne direkten Internetzugang, etwa in Air-Gap-CI-Systemen oder internen Artefakt-Repositories.

Wozu Offline-Bundles

In manchen Umgebungen darf euer CI-Runner nicht direkt auf das Internet zugreifen:

  • Air-Gap-CI: Isolierte Build-Infrastruktur ohne Outbound-Verbindung zum Portal.
  • Internes Artefakt-Repository: Bundles werden einmal heruntergeladen und intern gespiegelt, sodass alle Teams auf denselben Stand zugreifen.
  • Regulatorische Anforderungen: Prüfpflichtige Umgebungen, in denen externe Netzwerkverbindungen aus dem CI verboten oder eingeschränkt sind.

Bundle aus dem Portal exportieren

Ihr könnt ein Bundle für eine veröffentlichte Profil-Version aus dem Portal herunterladen:

  1. Öffnet die Profil-Liste oder den Tab Plattform der Profil-Liste.
  2. Bei euren eigenen Profilen klickt ihr auf das Kebab-Menü (⋮) der gewünschten Zeile und wählt Bundle herunterladen; das liefert die zuletzt veröffentlichte Version. Im Tab Plattform klickt ihr direkt auf den Button Bundle herunterladen auf der Profilkarte, mit derselben Einschränkung auf die neueste Version.
  3. Für eine ältere veröffentlichte Version öffnet ihr stattdessen die Detailseite des Profils und nutzt dort Bundle herunterladen, wo jede Version verfügbar ist.

Die heruntergeladene Datei ist ein signiertes .cgbundle: ein ZIP-Archiv mit den Regeldateien (.cgr) der gepinnten Version, einem Manifest mit Metadaten und einem Content-Hash sowie einer Ed25519-Signatur über dieses Manifest.

Eine Bundle-Datei ohne Portal-Zugriff zur Analysezeit verwenden

Für eine CI ohne jede Verbindung zum Portal könnt ihr in .codecharter/config.yml statt eines Slugs ein lokales Bundle referenzieren:

# .codecharter/config.yml
version: 1
profiles:
  - path: "./bundles/dotnet-standard-2.1.0.cgbundle"

Darauf bauen Air-Gap- und vollständig offline arbeitende Setups auf: Ein path:-Eintrag spricht zu keinem Zeitpunkt mit dem Portal. Damit das funktioniert, entpackt ihr das heruntergeladene .cgbundle (ein gewöhnliches ZIP-Archiv) nach .codecharter/cache/extracted/<name>/, wobei <name> der Dateiname des Bundles ohne die Endung .cgbundle ist, für das Beispiel oben also .codecharter/cache/extracted/dotnet-standard-2.1.0/. Erledigt das als Schritt in eurer eigenen CI-Pipeline oder beim Image-Build, vor codecharter analyze; es gibt keinen CodeCharter-Befehl, der das Herunterladen oder Entpacken für euch übernimmt. codecharter analyze liest die Regeln dann direkt aus diesem Verzeichnis. Fehlt es, gibt codecharter analyze eine Warnung aus und überspringt den Profil-Eintrag einfach, statt den Lauf abzubrechen. Ein Tippfehler im Pfad fällt dadurch leicht nicht auf, prüft die Warnausgabe deshalb nach der ersten Einrichtung.

CodeCharter prüft Signatur oder Content-Hash eines path:-Eintrags nicht erneut; die SHA-256-Absicherung, die Slug-basierte Profile schützt (siehe Plattform-Profile nutzen), gilt nur für Bundles, die über codecharter update aufgelöst wurden. Betrachtet die Bundle-Datei selbst als Vertrauensgrenze: Bezieht sie über einen Kanal, dem ihr bereits vertraut (ein authentifizierter Download aus dem Portal, aus eurem eigenen signierten Artefakt-Speicher oder über die Integritätskontrollen eurer Organisation), und committet sie nicht direkt in euer Quell-Repository, sondern holt sie in einem vorgelagerten CI-Schritt aus eurem internen Speicher.

Update-Workflow im Air-Gap

In einer vollständig isolierten Umgebung empfehlen wir folgenden Ablauf:

  1. Auf einer Maschine mit Internetzugang: neues Bundle aus dem Portal herunterladen.
  2. Entpacken und den Inhalt in euer internes Artefakt-Repository hochladen, benannt nach dem Bundle, damit der CI-Runner ihn nach .codecharter/cache/extracted/<name>/ holen kann.
  3. In .codecharter/config.yml die neue Version eintragen (entweder im path:-Wert, falls dieser die Version enthält, oder im referenzierten Dateinamen).
  4. Auf der Maschine mit Internetzugang codecharter update --portal-url <url> --api-key <key> ausführen, um das Lockfile zu aktualisieren, sofern ihr daneben auch Slug-basierte Profile verwendet. Dieser Befehl benötigt eine Verbindung zum Portal und kann nicht innerhalb des Air-Gaps laufen.
  5. .codecharter/config.yml und .codecharter/codecharter.lock.json per PR mergen.
  6. Im CI-Runner: Legt das entpackte Bundle in einem vorgelagerten Pipeline-Schritt unter .codecharter/cache/extracted/<name>/ ab und führt danach codecharter analyze wie gewohnt aus. Es liest das path:-Profil direkt aus diesem Verzeichnis.