Run CI/CD flow

This page walks you through the practical steps of using Mosaic’s Version Management APIs to move configurations across tenants. It covers the full lifecycle: export, review, validate, and import — including caveats such as alias handling, concurrency, and audit logging.

If you're looking for general guidance, see Development lifecycle.

Mosaic supports two export types.

• A partial export (recommended) promotes specific entities.
• A full export moves the entire tenant configuration.

To learn more about their differences, see Cross-tenant version management (CI/CD).

Both exports include aliases for environment variables, keys, credentials, and certificates. Sensitive values are never included. A manifest.yaml file is also included, with details about the database versions of the Journey module entities, and Identity Management data. These details are useful during validation (see Phase 3: Validate).

To perform an export, call Version Management against the source tenant and provide a valid access token for that tenant (issued using management app credentials).

The response is a binary ZIP payload. When using curl, redirect the output to a file (for example, with --output export.zip). To inspect or version the configuration, extract the ZIP contents before reviewing or committing them to Git. The same structure must be preserved if you later re-zip the bundle for import.

curl -X 'POST' \
  'https://version-management.transmitsecurity.io/version/export/<SOURCE_TENANT_ID>' \
  -H 'Authorization: Bearer <MANAGEMENT_APP_ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "entities": {
      "journeys": { "mode": "selective", "ids": ["<JOURNEY_ID>"] },
      "externalConnections": { "mode": "sync" }
    }
  }' \
  --output export.zip

After generating an export, store the package in a version control system such as Git. Use pull requests and protected branches to review changes before promotion to the next environment. Version control provides a clear history of configuration changes and helps identify regressions. Be sure to keep dependencies intact (for example, journeys and their external connections) to avoid broken references during import.

Use GitHub or another version control system to manage your exports. Keep bundles private and never store secret values in Git.

Before applying a configuration, use the version validation API in the target tenant with the exported data.

curl -X 'POST' \
  'https://version-management.transmitsecurity.io/version/validate/<TARGET_TENANT_ID>?format=zip' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <MANAGEMENT_APP_ACCESS_TOKEN>' \
  -H 'Content-Type: application/zip' \
  --data-binary '@export.zip'

Validation checks that:

• all required aliases (environment variables, keys, certificates, credentials) exist and have values,
• the exported configuration is structurally valid,
• and it is compatible with the target tenant’s version.

For a partial export, validation additionally checks that every entity referenced by the package (for example, an external connection used by an exported journey) is either included in the package or already present in the target tenant. Full exports are self-contained, so this check doesn't apply to them.

If references are missing, the response returns status: failure with the message Validation completed with missing dependencies, and details contains a MISSING_DEPENDENCIES entry naming each missing entity and where it's used:

{
  "status": "failure",
  "message": "Validation completed with missing dependencies",
  "details": [
    {
      "type": "MISSING_DEPENDENCIES",
      "message": "One or more depend on entities not found in this package or in the target tenant",
      "details": [
        "Missing provider \"<CONNECTION_ID>\" (used in journey \"<JOURNEY_ID>\" - \"My journey\")"
      ]
    }
  ]
}

Each line names the missing entity and the item that references it. External connections appear as provider in these messages, and sub-journeys as sub-journey.

Resolve the findings before importing: add the missing entities to the selection, or make sure they already exist in the target tenant. An import of a package with missing dependencies is rejected with 400 Bad Request.

Note that this phase does not run the full import logic — it only validates prerequisites and structure. This means validation may pass even if the subsequent import encounters issues.

Review the validation report carefully and fix any problems (e.g., missing variables or version mismatches). Repeat validation until the report is clean before proceeding with the import.

Once validation passes, run the import API in the target tenant to apply the configuration. There's a single import API for both kinds of package — the package itself tells the import what to apply:

• Full export – the import replaces the tenant’s configuration with the content of the file.
• Partial export – the import applies each entity type according to the mode recorded for it at export time: sync mirrors the type (items missing from the package are deleted), selective adds or updates only the exported items, and a type that wasn't exported is left untouched. Identity management data in the package is still applied in full.

Optional: rollback on failure — You can pass the query parameter failureRollBack=true to request that, if the import fails or only partially completes (e.g. one module import succeeds but another fails), the system automatically reverts the target tenant to its state before the import. The response may include a rollbackResult object with the outcome (e.g. success or failure and a message).

curl -X 'POST' \
  'https://version-management.transmitsecurity.io/version/import/<TARGET_TENANT_ID>?format=zip&failureRollBack=true' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <MANAGEMENT_APP_ACCESS_TOKEN>' \
  -H 'Content-Type: application/zip' \
  --data-binary '@export.zip'

Run imports serially and schedule them during a maintenance window if the changes are significant to reduce the risk of conflicts.

In addition to the standard import, the Version Management Service provides a force import API.

Force import should be a last resort. It skips alias validation and, for partial packages, the missing-dependency check. Database version compatibility and conversion checks still run, and the bundle’s structural integrity is enforced. If database versions are incompatible, force import will fail.

Use cases are rare, for example:

• Recovering from a failed import where alias validation blocks a retry.
• Aligning environments when you intentionally do not provision all aliases in the target tenant (accepting the risks).

Risks include:

• Missing or unresolved aliases will not be detected and can cause runtime errors in journeys.
• The missing-dependency check is skipped as well, so a partial package can be imported with references that resolve to nothing in the target tenant.
• The tenant configuration is overwritten (for a partial package, within the scope recorded in it); use failureRollBack=true if you want the system to revert the tenant to its state before the import when the import fails or only partially completes.

Recommendation: Always run version validation API and import API first. Use force import only if you fully accept the risks, and ideally under guidance from Transmit Security support.

After a successful import, run a full regression in the target tenant to verify that all journeys, configurations, and integrations behave as expected.

All import and export operations are recorded in the Admin User Activity Log for traceability and troubleshooting. Logged details include:

• Action type (export, import, validation) and related metadata
• Timestamp

Sensitive data such as tokens or secrets are never stored in plain text; they are redacted or fingerprinted in logs.