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 tenants (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:

  1. Dev tenant – Export a ZIP containing YAML files with the full configuration.
  2. UAT tenant – Review diffs and edit the files in your version management system, resolving issues if needed.
  3. Prod tenant – Import the curated data into the target tenant (overwriting its configuration).

At the end of the process, the target tenant 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 google
Auth methods facebook
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.