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 your development lifecycle (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 learn more, see Understand environments, regions, and tenants and Development lifecycle.
In Mosaic, CI/CD is organized around tenants, not just environments. To move configurations between tenants, Mosaic provides Version Management APIs. These APIs let you export a tenant’s configuration—either in full or scoped to the entities you select—and import it into another tenant, ensuring consistency, repeatability, and security across your CI/CD pipeline.
The typical workflow is:
- Dev tenant – Export a ZIP containing YAML files with the requested configuration (full or selected entities only).
- UAT tenant – Review diffs and edit the files in your version management system, resolving issues if needed.
- Production tenant – Import the curated data into the target tenant. Importing a full export replaces the target tenant's configuration. Importing a partial export applies changes within the scope and modes defined in the package (see Full and partial exports).
At the end of the import, the target tenant is updated according to the export type and mode, and environment-specific values resolve through the target tenant's own variables and secrets.
- 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.
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
Mosaic supports the following export options:
- Full export – exports the entire tenant configuration. Importing it replaces the target tenant with the exported contents.
- Partial export – exports a subset that you scope per entity type, so you can promote individual journeys without touching everything else in the target tenant.
A partial export scopes four entity types: journeys, sub-journeys, external connections, and typed lists. For each entity type, you choose a mode:
| Mode | What's exported | What the import does to that type |
|---|---|---|
sync | Every item of that type | Mirrors the source: items that aren't in the package are deleted from the target |
selective | Only the ids listed (up to 25 per type) | Adds or updates those items; all other items of that type are left as they are |
| Type omitted from the request | Nothing | The type isn't touched in the target tenant |
The export records the mode it used for each type in a manifest.yaml in each entity folder, so the import handles it accordingly. Don't remove or edit these files — without them the package is treated as a full export and every type is synced.
- A partial export scopes the four entity types listed above. The rest of the tenant configuration (identity management data, such as clients, user schema, and SSO configuration) is still exported and imported in full.
- A single configuration file is still applied as a whole: you can't import part of a package. Control what gets promoted by scoping the export instead.
- 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), scope the export to exclude them, or curate the export before import.
Excluded identity management configuration fields
These fields are not included in export/import and must be configured directly in each tenant.
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 | 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 |
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.
After a partial export, each exported entity folder (journeys/, sub-journeys/, external-connections/, typed-lists/) also contains its own manifest.yaml recording the mode used for that type, for example:
mode: selective
notFound:
- journey_id_that_does_not_existnotFound lists ids that were requested but don't exist in the source tenant (for sync, a message field notes when the tenant had no items of that type). The import reads the mode from these files to decide how to apply each type, so keep them in the package.
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.
To complete your CI/CD setup, you're ready to start preparing your export.