Skip to content

Offline-Bundles

Bundles aus dem Portal exportieren, im Air-Gap-CI einsetzen, einen internen Mirror aufsetzen und Signaturverifikation verstehen.

Aktualisiert am 2026-06-12

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 jede veröffentlichte Profil-Version aus dem Portal herunterladen:

  1. Öffnen Sie die Profil-Liste oder die Plattform-Regeln-Übersicht.
  2. In der Profil-Liste klicken Sie auf das Kebab-Menü (⋮) der gewünschten Profilkarte und wählen Bundle herunterladen. In der Plattform-Regeln-Übersicht klicken Sie direkt auf den Button Bundle herunterladen auf der Profilkarte.
  3. Wählen Sie die Version aus und laden Sie die signierte .cgbundle-Datei herunter.

Das Bundle enthält alle Regeldateien (.cgr) der gepinnten Version, eine Manifest-Datei mit Metadaten und einem Content-Hash sowie eine Ed25519-Signatur.

Bundle als Datei in .codecharter/config.yml referenzieren

Statt einem API-Aufruf ans Portal können Sie ein lokal vorliegendes Bundle direkt referenzieren. Der Schlüssel path akzeptiert sowohl lokale Dateipfade als auch HTTPS-Mirror-URLs:

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

Die CLI prüft die Signatur des Bundles bei jedem Laden und legt es unter .codecharter/cache/ ab. Für den dateibasierten Einsatz muss CODECHARTER_API_KEY nicht gesetzt sein. Existiert eine referenzierte Bundle-Datei nicht, meldet die CLI einen Fehler für diesen Eintrag und überspringt ihn; eine fehlgeschlagene Signaturprüfung bricht den Lauf dagegen ab.

Empfehlung: Committen Sie das Bundle nicht direkt ins Repository. Laden Sie es stattdessen in einem vorgelagerten CI-Step aus Ihrem internen Mirror herunter.

Internen Mirror aufsetzen

Sie können Bundles hinter einer internen HTTPS-URL spiegeln und dabei denselben Schlüssel path verwenden:

# .codecharter/config.yml
version: 1
profiles:
  - path: "https://artifacts.internal.example.com/codecharter/dotnet-standard-2.1.0.cgbundle"

Anforderungen an den Mirror:

  • Nur HTTPS, http://-URLs werden abgelehnt. Das Zertifikat muss vom Zertifikatsspeicher des Betriebssystems als vertrauenswürdig eingestuft werden; es gibt keine CLI-Option, um die Zertifikatsprüfung zu übergehen.
  • Unveränderliche URLs pro Version: Die CLI lädt jede URL einmal herunter und verwendet danach die gecachte Datei.
  • Die Mirror-URL muss ohne Authentifizierung erreichbar sein. Die CLI sendet keine Zugangsdaten und keine Authentifizierungsheader an Mirror-URLs.

Signaturverifikation

Jedes Bundle ist mit dem Ed25519-Signaturschlüssel des Portals signiert. Die CLI verifiziert die Signatur vor der Verwendung. Schlägt die Verifikation fehl, bricht der Build mit einem Fehler ab, zum Beispiel:

Bundle 'dotnet-standard-2.1.0.cgbundle': Bundle signature is invalid (key '<key-id>').
  The bundle may have been tampered with.

CodeCharter holt die öffentlichen Signing-Keys vom Portal und legt sie lokal unter .codecharter/cache/signing-keys.json ab. Sie werden automatisch aufgefrischt, wenn sie fehlen oder älter als 24 Stunden sind. Es gibt keinen manuellen Schlüssel-Befehl. Ist das Portal nicht erreichbar, greift die CLI auf die gecachten Keys zurück, auch wenn diese veraltet sind. Für einen vollständig offline arbeitenden Runner bedeutet das: Der Key-Cache muss vorab befüllt sein. Führen Sie die CLI einmal mit Portal-Verbindung aus oder kopieren Sie eine befüllte .codecharter/cache/signing-keys.json auf den Runner, damit die Signaturverifikation ohne Netzwerkzugriff gelingt.

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. Bundle in das interne Artefakt-Repository hochladen.
  3. In .codecharter/config.yml die neue Version eintragen.
  4. Auf der Maschine mit Internetzugang codecharter update --portal-url <url> --api-key <key> ausführen, um das Lockfile zu aktualisieren. 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: das gespiegelte Bundle über einen path:-Eintrag in .codecharter/config.yml referenzieren (lokale Datei oder interne HTTPS-URL) und wie gewohnt codecharter analyze ausführen.

Über path: referenzierte Bundles werden beim Analyse-Lauf automatisch heruntergeladen, verifiziert und gecacht; ein separater Restore-Schritt ist für sie nicht nötig.