CI/CD setup requirements
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.
To use Mosaic’s Version Management APIs in a CI/CD pipeline, you need proper authorization and a consistent way to handle sensitive data.
This page explains the prerequisites for running export, validation, and import operations across tenants. It also covers how to define and manage environment variables, credentials, keys, and certificates so that configuration moves cleanly between environments.
Obtain authorization/credentials
- Use a management app token with sufficient privileges for each tenant (source and target).
- Obtain access tokens for the source tenant (export) and the target tenant (validate/import). See Get access token .
Important
- Tokens must authorize Version Management endpoints and should be stored and rotated securely.
- Always generate a separate access token for each environment (source and target), with only the permissions required for its task.
Secure env vars, keys, credentials, and certificates
Manage your secrets
Exports never include secret values (API keys, credentials, certificates). Only their aliases and versions are included in the exported file. Before importing into a target tenant, make sure all corresponding values are already defined there.
When working across environments, always define the required environment variables, credentials, keys, and certificates as aliases in each tenant (Dev, UAT, Prod).
In the Admin Portal you can find:
- Environment variables in Settings > Environment Variables
- Keys , certificates , and credentials in Journey tools > Keys and credentials
Keys, certificates, and credentials are versioned. Select an alias and create a new version as needed. During import validation, Mosaic checks that all referenced aliases and their versions exist in the target tenant. If a required version is missing, validation fails and the configuration must be fixed before import.
When you export a configuration, Mosaic includes only aliases—never values. For example:
-
environment variable:
callback-domain -
key:
jwt-signing-key -
credential:
payment-gateway-credential -
certificate:
saml-idp-cert
The export package also contains all journeys and external connections that depend on these aliases (e.g., SMS provider or payment API connection).
Note
Before running an import, ensure every alias listed in the exported file has a value defined in the target tenant. Missing values cause validation to fail and the import cannot proceed.
Use the version validation API API to run a validation in the target tenant and confirm all aliases are present and populated.
In AuthScript, you can dynamically resolve environment-specific values using built-in functions:
-
@envVars.lookup("AliasName", "DefaultValue")Returns the value of the given alias in the current tenant; if the alias is missing or empty at runtime, the provided default is used instead. -
@envVars.list()returns all available environment variable aliases for that tenant.
This ensures that the same configuration can run across Dev, UAT, and Prod while resolving the correct values at runtime.
You can test your AuthScript expressions in Journey Tools > Expression Fiddle.
Reference configuration field values
In addition to environment variables, several Identity Management configuration fields also support using aliases. These include:
-
Application endpoints such as
loginUriorinviteMemberUri -
Client properties like
redirectUrisorconsentUri -
Service provider attributes such as
acsURLandentityId -
Authenticator parameters like
webauthn_api.configuration.rpIdand origins
Some of these fields are available in the Admin Portal UI, while others can only be set via API. During export, they appear with aliases, and during import the target tenant resolves them against the values already defined there.
Fields not supported for export/import (for example, social login methods like Google or Facebook) must still be configured directly in each tenant.
Supported Admin Portal and Identity Management fields for environment variable aliases
| Category | Field name | UI / API availability | Example alias name |
|---|---|---|---|
| Applications | authenticatorAppPreferences.loginUri | UI/API | login-uri |
| Applications | loginUri | UI/API | app-login-uri |
| Applications | inviteMemberUri | UI/API | invite-member-uri |
| Clients | redirectUris | UI/API | redirect-uri |
| Clients | deviceAuthConfiguration.approvalUri | API only | device-approval-uri |
| Clients | deviceAuthConfiguration.successUri | API only | device-success-uri |
| Clients | deviceAuthConfiguration.inputUri | API only | device-input-uri |
| Clients | cibaAuthConfiguration.loginUri | API only | ciba-login-uri |
| Clients | consentUri | UI/API | consent-uri |
| Clients | spAcsUrl | UI/API | sp-acs-url |
| Clients | spEntityId | UI/API | sp-entity-id |
| Clients | tlsClientAuth.certificate_chain | UI/API | tls-cert-chain |
| Clients | tlsClientAuth.ocspresponderuri | UI/API | tls-ocsp-uri |
| Clients | tlsClientAuth.ocsprespondercertificate | UI/API | tls-ocsp-cert |
| ServiceProviders | acsURL | UI/API | sp-acs-url |
| ServiceProviders | entityId | UI/API | sp-entity-id |
| ServiceProviders | nameQualifier | UI/API | sp-name-qualifier |
| Resources | uri | UI/API | resource-uri |
| Authenticators | webauthn_api.configuration.rpId | UI/API | rp-id |
| Authenticators | webauthn_api.configuration.rpWebOrigins | UI/API | rp-web-origins |
| Authenticators | webauthn_api.configuration.rpMobileOrigins | UI/API | rp-mobile-origins |
Next step
Once your setup is complete, you're ready to run your CI/CD flow.