Die Repositories vorbereiten¶

Die Plattform nutzt zwei Arten von Repositories (Repo-Setup): das Code-Repository, das für jeden Kunden gleich ist, und ein Konfigurations-Repository pro Kunde. Diese Seite beschreibt, wie du sie im Azure-DevOps-Projekt oder in der GitHub-Organisation des Kunden einrichtest, wie der Code dorthin kommt und welche Schutzmaßnahmen du wann einschaltest.

Was du anlegst¶

Repository	Name (Beispiel)	Inhalt am Anfang	Geschrieben von
Code	`xms-cloud-platform-code`	Eine Kopie des veröffentlichten Codes, per Sync eingespielt. Nur lesbar für das Team des Kunden.	Nur der Sync
Konfiguration	`xms-cloud-platform-config`	Eine Kopie der Template-Konfiguration (`environments/canary`, `environments/prod`, `pipelines/`, `.github/workflows/`)	Das Plattform-Team

Die spoke-Dateien gehören zum Konfigurations-Repository (<env-folder>/spokes/). Das Terraform des spoke canvas gehört zum Code-Repository. Ältere Versionen nutzten vier Repositories; siehe Ältere Layouts.

Wo die Repositories liegen

Azure DevOps: ein privates Projekt in der Organisation des Kunden, mit Git-Repositories.
GitHub: Repositories in der Organisation des Kunden, mit Standardeinstellungen.
Im Managed-Modell wird das Code-Repository zusätzlich auf dem eigenen Host des Anbieters gehalten und zum Kunden synchronisiert. Im Eigenbetrieb synchronisierst du ein Release aus der veröffentlichten Quelle des Anbieters auf deinen eigenen Host und entscheidest selbst, wann du aktualisierst (Versionierung).

1. Die Repositories erstellen¶

Azure DevOps¶

Öffne das Projekt, Repos, New repository. Typ Git. Name: der Name des Code-Repositorys. Wiederhole das für das Konfigurations-Repository.
Klone das Konfigurations-Repository. Wenn es noch keinen main-Branch hat, lege einen mit einem leeren Commit an und arbeite für die Implementierung auf einem separaten Branch:
```
git checkout --orphan main
git commit --allow-empty -m "Initial empty commit"
git push -u origin main
git checkout -b initial
```

GitHub¶

Erstelle beide Repositories mit Standardeinstellungen.
Öffne im Code-Repository Settings, Actions, General, Access und erlaube den Zugriff von Repositories der Organisation, damit das Konfigurations-Repository seine workflows nutzen kann.
Erstelle im Konfigurations-Repository main mit einem leeren Commit und einen Branch initial wie oben. Setze den Default-Branch während der Implementierung auf initial und danach, wenn die Implementierung abgeschlossen ist, zurück auf main.

2. Den Code einspielen¶

Das Code-Repository wird im Host des Kunden nicht bearbeitet. Es erhält veröffentlichte Versionen (Branches release/vX.Y und tags vX.Y.Z) aus der Quelle des Anbieters. Wie das funktioniert, hängt vom Betriebsmodell ab:

Managed-Modell. XMMS betreibt einen Sync aus seinem eigenen Code-Repository. Du gibst dem Sync eine Möglichkeit, in das Repository des Kunden zu schreiben (siehe unten), und XMMS fügt das Repository des Kunden als Ziel hinzu.
Eigenbetrieb. Du beziehst das Release vom Anbieter und pushst es selbst in das Code-Repository oder richtest einen gleichwertigen Sync ein. Vereinbare den Liefermechanismus mit dem Anbieter.

Egal welchen Mechanismus du nutzt, das Ergebnis muss sein: Das Code-Repository auf dem Host des Kunden enthält die Release-Branches und tags, die das Konfigurations-Repository pinnt, und niemand sonst ändert es.

Ziel auf GitHub: eine GitHub App für den Sync¶

Der Sync authentifiziert sich als GitHub App, die in der Organisation des Kunden installiert ist. Zum Erstellen und Verwalten ist die Rolle App Manager nötig.

Organization settings, Developer settings, GitHub Apps, New GitHub App.
Name und Beschreibung, die sagen, was sie tut (zum Beispiel "repository sync"). Webhook: inactive.
Repository permissions: Contents: read and write, Workflows: read and write.
Wo sie installiert werden kann: nur in diesem Account.
Notiere nach der Erstellung die App ID und erzeuge einen private key (.pem). Lege den Key im secret store der Partei ab, die den Sync betreibt, und übergib die App ID.
Installiere die App, wähle Only select repositories und wähle das Code-Repository (und in älteren Layouts das spoke- Code-Repository). Notiere die installation ID.

Der Sync signiert eine Token-Anfrage mit dem Key und tauscht sie gegen ein kurzlebiges installation token.

Das Ziel-Repository sperren¶

Mach das Code-Repository für alle außer dem Sync schreibgeschützt, mit einem ruleset auf allen Branches, das das Anlegen, Aktualisieren und Löschen von refs sowie non-fast-forward-Pushes blockiert und die App daran vorbeilässt.

# Requires the GitHub CLI (gh auth login) and PowerShell 7. Run once per code repository.
$sync_app_id = "<app-id>"
$org         = "<organization>"
$repo        = "xms-cloud-platform-code"
$body = @"
{
  "name": "RO-enforcement",
  "target": "branch",
  "enforcement": "active",
  "conditions": { "ref_name": { "include": ["~ALL"], "exclude": [] } },
  "rules": [
    {"type": "deletion"},
    {"type": "non_fast_forward"},
    {"type": "creation"},
    {"type": "update"}
  ],
  "bypass_actors": [
    { "actor_id": $sync_app_id, "actor_type": "Integration", "bypass_mode": "always" }
  ]
}
"@
$body | gh api --method POST "/repos/$org/$repo/rulesets" --input -

Teste den Sync, nachdem du das Repository gesperrt hast

Führe nach dem Erstellen des rulesets einen Sync aus und prüfe, dass die App noch schreiben kann. Ein ruleset, das den Sync blockiert, ist die übliche Ursache für einen fehlgeschlagenen ersten Sync.

Ziel auf Azure DevOps¶

Die Entry-pipelines referenzieren das Code-Repository als Repository-Resource (mcp-code). Je nach Setup zeigt diese Resource über eine service connection auf den Host des Anbieters (der endpoint: in der Entry-Datei, siehe Versionierung) oder auf eine synchronisierte Kopie im eigenen Projekt des Kunden. Im zweiten Fall vereinbare in der Planungsphase, welche Identität in das Code-Repository schreibt, gib nur dieser Identität Schreibzugriff und blockiere alle anderen Schreibenden mit einer Branch Policy.

3. Das Konfigurations-Repository füllen¶

Kopiere das Template auf den Branch initial in das Konfigurations-Repository. Das Template ist die Demo-Konfiguration im Code-Repository (config/Demo/) oder ein Template-Repository, das dein Anbieter dir gibt.
Passe es mit dem Mapping an. Entferne Inhalte, die nicht zutreffen (spokes anderer Kunden, Beispiel-Policies, die du nicht willst).
Setze in jeder Entry-pipeline (pipelines/*.yaml oder .github/workflows/*.yaml) die Referenz auf das Code-Repository und die gepinnte Version (Versionierung), den agent pool, die service connections und die Umgebungen.
Committe und pushe nach initial.

Bleib auf initial, bis die Plattform validiert ist. So beschreibt main immer eine Konfiguration, die deployt und geprüft wurde, und die folgenden Branch-Schutzmaßnahmen bremsen die Implementierung nicht aus.

4. Die Repositories am Ende der Implementierung schützen¶

Schalte diese nach der Validierung und vor der Übergabe ein. Nutze eine Gruppe von Reviewern, der der Kunde zustimmt (Beispielname: <platform approvers group>).

Schutz	Azure DevOps	GitHub
Genehmigung vor prod-Läufen	Environment `prod` (und ein spoke-Environment wie `<spoke environment>-prod`) mit Genehmigern; Projektadministratoren haben darauf die Rolle Administrator; Genehmiger dürfen ihre eigenen Läufe nicht genehmigen	Environment `prod` mit required reviewers (die Genehmigergruppe), Prevent self-review an, Allow administrators to bypass aus. Außerdem das Environment `approval-required` für die `Approve*`-Modi (Pipelines).
Review vor dem Merge nach `main`	Eine repository-übergreifende Branch Policy auf dem Default-Branch: automatisch eingeschlossene Reviewer = die Genehmigergruppe, erforderlich, mindestens 1 Reviewer, Antragsteller dürfen ihre eigenen Änderungen nicht genehmigen	Ein ruleset auf `main`: pull request mit 1 Genehmigung erforderlich, Genehmigung des letzten prüfbaren Pushs, Auflösung von Konversationen, nur squash merge, force pushes blockiert
spoke-Dateien vor dem Merge geprüft	Build-Validierung im Konfigurations-Repository: die spoke-Verifizierungs-pipeline, automatischer Trigger, erforderlich, Build-Ablauf nach 12 Stunden	Ein pull-request-workflow, der die Config tests ausführt
Lesezugriff für Genehmiger	Die Genehmigergruppe kann die Repositories lesen	Die Genehmigergruppe hat Lesezugriff auf die Repositories

Öffne zum Schluss einen pull request von initial nach main und merge ihn. Setze in GitHub den Default-Branch zurück auf main und aktualisiere die federated credential für den Branch (siehe GitHub-Variante).

Ältere Layouts¶

Älteres Layout	Ersetzt durch	Hinweise
Vier Repositories: Plattform-Code, Plattform-Konfiguration, spoke-canvas-Code, spoke-canvas-Konfiguration	Zwei Repositories (Code und Konfiguration) im aktuellen Layout	Im älteren Layout liegen die spoke-Dateien in `spokes/tfspokes/<workload>/` des spoke-Konfigurations-Repositorys, und das spoke-Deployment nutzt eine eigene pipeline und einen eigenen state-Container.
Ein separates Repository für die selbst gehosteten Agents (Terraform und ein Image-Build)	Die pipelines `infrastructure` und `container` im Code-Repository	Siehe Pipelines und Agents.
Ein Repository pro Kunde mit allem Code und allen Parametern (Mono-Repo) oder eine einzelne `landingzone.yml`-pipeline	Layered Deployment	Siehe Migration von einer älteren Plattformversion.

Zum spoke canvas als separatem Deployment (eigenes Code-Repository und eigene pipeline) siehe Die spoke-pipeline vorbereiten: Der Code bleibt entweder beim Plattform-Team und wird über eine service connection gelesen, oder er wird in die Organisation des Kunden kopiert.

Prüfe, welches Layout deine gepinnte Version erwartet: Die Entry-pipelines und die Release Notes der Version sagen es dir.