Cross-tenant version management (CI/CD)
Feature under active development
CI/CD version management is actively evolving. This documentation is continuously updated as the feature matures.
Always verify with the latest API reference or release notes before implementing in production.
Mosaic supports CI/CD by providing sandbox and production environments, with the option to maintain multiple tenants in each. This separation lets teams develop, test, and release safely without impacting production. To move configurations between environments (for example, from Dev to UAT to Prod), Mosaic provides Version Management APIs. These APIs let you export a tenant’s full configuration and import it into another tenant, ensuring consistency, repeatability, and security across your CI/CD pipeline.
Key benefits:
- Concurrent work – Developers can work in separate tenants and merge changes when ready.
- Controlled promotion – Only approved changes move forward in the release pipeline.
- Git compatibility – Exported files can be stored in version control for branching, reviews, merges, and rollbacks.
- Environment consistency – Apply the same tested configuration across multiple environments.
- Security – Sensitive values are never transferred; only aliases are included.
- Release confidence – External tooling gives you full control over what gets promoted.
About Mosaic's CI/CD flow
In Mosaic, CI/CD is organized around tenants, not just environments. A typical setup includes three tenants:
- Dev tenant – for building and iterating.
- UAT tenant – for reviewing and testing.
-
Prod tenant
– for live deployment.
The typical workflow is: - Dev tenant – Export a ZIP containing YAML files with the full configuration.
- UAT tenant – Review diffs and edit the files in your version management system, resolving issues if needed.
- Prod tenant – Import the curated data into the target tenant (overwriting its configuration).
At the end of the process, the target environment mirrors the exported configuration, with environment-specific values resolved through its own variables and secrets.
Import/export scope
The export package includes:
- Journeys
- External connections
- Typed lists
- Clients and client roles
- User schema and user groups
- Aliases for environment variables, credentials, keys, and certificates
- Application,
- Service providers,
- Resources,
- SSO configuration,
- Roles
- Role groups
Import/export is tenant-wide: each export contains the entire tenant configuration, and each import fully replaces the target tenant with the exported contents.
Important
- Imports are all-or-nothing: you cannot import only part of a configuration file.
- Sensitive values (such as API keys, certificates and credentials) are never exported—only their aliases and their versions. The target environment must already contain the required values. Data about revoked keys, certificates or credentials is excluded to keep exports clean.
- If you don’t want to promote certain items (for example, deprecated or blocked journeys), curate the export before import to exclude them.
Excluded A+ and IDM configuration fields
These fields are not included in export/import and must be configured directly in each tenant.
Note
The scope of excluded fields may change over time as support for additional fields is added. Always check the latest documentation for updates.
| Category | Field name |
|---|---|
| Application | subdomain |
| Application | org admin portal domain |
| Application | invite client |
| Application | app specific token |
| Client | client_id |
| Client | client_secret |
| Client | jwks |
| Auth methods | |
| Auth methods | |
| Auth methods | apple |
| Auth methods | push notification |
| Auth methods | tiktok |
| Auth methods | webauthn_api |
| Auth methods | line |
About the export file
The ZIP export is organized into folders by functional area (for example, authentication-and-user-management, journeys, secrets). Each journey, external connection, or sub-journey is stored as a separate YAML file, making changes easy to review in Git.
Every module folder—such as ido/ for journeys or authentication-and-user-management/ for identity management—includes a manifest.yaml file specifying the database version.
The journey folder includes a secrets/ directory that lists all secret aliases (and their versions) for that module.
For details, see Secure env vars, credentials, keys, certificates.
Next steps
To complete your CI/CD setup, you're ready to start preparing your export