Mit Umgebungsvariablen arbeiten

Jedes generierte Repository bringt seine Konfiguration mit. Es gibt zwei Orte, an denen Umgebungsvariablen leben: das env/-Verzeichnis im Code-Repository (für die lokale Entwicklung und die App-Builds) und das gitops-configuration-Repository (für die Deployments auf Dev und Prod).

Das env/-Verzeichnis

App- und Backend-Repositories enthalten ein env/-Verzeichnis mit Dateien nach dem Muster <stage>.<art>.env:

Datei	Wer pflegt sie	Inhalt
`local.generated.env`	Plattform	URLs und Werte für die lokale Entwicklung
`local.custom.env`	Du	Deine eigenen lokalen Einstellungen
`dev.generated.env` / `prod.generated.env`	Plattform	Stage-spezifische URLs (z. B. Backend-URL auf Dev/Prod)
`dev.custom.env` / `prod.custom.env`	Du	Eigene stage-spezifische Werte
`shared.generated.env`	Plattform	Stage-übergreifende Werte (z. B. Sentry-DSN, Bundle-IDs)
`shared.custom.env`	Du	Eigene stage-übergreifende Werte

Die Regel ist einfach:

*.generated.env wird von der Plattform geschrieben und bei Änderungen überschrieben – nicht bearbeiten.
*.custom.env gehört dir. Hier ergänzt du eigene Variablen oder überschreibst generierte Werte.

Beim Start über ap run-local werden automatisch die passenden Dateien geladen – bei Flutter-Apps z. B. über --dart-define-from-file.

Tipp

Neue Variable fürs lokale Arbeiten? Einfach in env/local.custom.env eintragen und ap run-local neu starten.

Deployment-Konfiguration: Dev und Prod

Was auf den Servern läuft, wird im gitops-configuration-Repository deines Projekts konfiguriert – pro Umgebung ein Ordner:

gitops-configuration/
└── configurations/
    ├── dev/
    │   ├── generated.yaml   # Plattform: Hostnamen, Registry, Secrets (SOPS)
    │   ├── custom.yaml      # Du: eigene Umgebungsvariablen
    │   └── versions.yaml    # Pipeline: deployte Image-Versionen
    └── prod/                # gleiche Struktur

Eigene Umgebungsvariablen für das Deployment ergänzt du in custom.yaml unter additional_env_variables. Nach einem Commit auf main rollt das GitOps-Repository die Änderung automatisch auf die jeweilige Umgebung aus – wie beim normalen Deployment-Workflow.

Secrets

Passwörter, Tokens und Schlüssel generiert die Plattform und legt sie verschlüsselt bzw. automatisch verwaltet ab – unter anderem Datenbank-Zugänge, JWT-Secrets und Registry-Credentials.

Achtung

Lege keine Passwörter oder API-Keys im Klartext in *.custom.env oder custom.yaml ab, wenn sie schützenswert sind. Nutze für sensible Werte die von der Plattform verwalteten Secrets oder frag den Support, welcher Weg für deinen Fall passt.

Siehe auch

Anwendungen starten mit der ap-CLI – wie die env-Dateien beim Start geladen werden.
Git-Workflow & Deployment – wie Änderungen auf Dev und Prod landen.
Architektur – die Rolle des GitOps-Repositories im Gesamtbild.