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 nutzen Sie 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 Ihr 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

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

  1. Öffnen Sie die Profil-Liste oder den Tab Plattform der Profil-Liste.
  2. Bei Ihren eigenen Profilen klicken Sie auf das Kebab-Menü (⋮) der gewünschten Zeile und wählen Bundle herunterladen; das liefert die zuletzt veröffentlichte Version. Im Tab Plattform klicken Sie 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 öffnen Sie stattdessen die Detailseite des Profils und nutzen 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önnen Sie 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, entpacken Sie 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/. Erledigen Sie das als Schritt in Ihrer eigenen CI-Pipeline oder beim Image-Build, vor codecharter analyze; es gibt keinen CodeCharter-Befehl, der das Herunterladen oder Entpacken für Sie ü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üfen Sie 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. Betrachten Sie die Bundle-Datei selbst als Vertrauensgrenze: Beziehen Sie sie über einen Kanal, dem Sie bereits vertrauen (ein authentifizierter Download aus dem Portal, aus Ihrem eigenen signierten Artefakt-Speicher oder über die Integritätskontrollen Ihrer Organisation), und committen Sie sie nicht direkt in Ihr Quell-Repository, sondern holen Sie sie in einem vorgelagerten CI-Schritt aus Ihrem 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 Ihr 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 Sie daneben auch Slug-basierte Profile verwenden. 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: Legen Sie das entpackte Bundle in einem vorgelagerten Pipeline-Schritt unter .codecharter/cache/extracted/<name>/ ab und führen Sie danach codecharter analyze wie gewohnt aus. Es liest das path:-Profil direkt aus diesem Verzeichnis.