Validate and cut over safely

A successful import means FlagTGL accepted and stored the source configuration. It does not prove application-level parity. Use this checklist for every provider before production traffic moves.

Before the first write

• Export or otherwise back up the source configuration.
• Inventory every project/config, environment, flag type, segment, prerequisite, direct target, rule operator, rollout, integration, SDK, and owner.
• Identify provider-only behavior listed in the relevant migration guide and assign an owner for each redesign.
• Restrict the migration credential and project scope. Record its planned revocation date.
• Decide which system is authoritative during the transition and establish a change freeze or a repeatable resync process.

Read the preview

The preview is a dry run. Reconcile project, environment, flag, and segment counts with the intended source scope. A project marked imported is new; synced means its target key already exists. Flag results distinguish created, updated, unchanged, and error.

An empty or unexpectedly broad preview is a stop condition. Check the provider URL, credential permissions, and project/config scope before migrating.

Build a parity fixture

For every critical flag, record the expected result for contexts that cover:

1. the default/off path;
2. each direct target or segment;
3. each ordered rule, including a context that almost matches;
4. each prerequisite state;
5. each typed variation;
6. percentage boundaries and overlapping audiences;
7. missing, null, malformed, numeric, and string context attributes;
8. custom context kinds or identity traits.

Evaluate the fixture against both platforms. Compare returned type and value, not just whether a flag appears enabled. For transformed percentage rollouts, compare aggregate distribution separately from per-user cohort identity.

Application and SDK cutover

LaunchDarkly SDKs can use FlagTGL's documented compatible endpoints where supported. Unleash, ConfigCat, and Flagsmith applications must move to a supported FlagTGL SDK or evaluation API; their source credentials and SDK initialization are not portable.

Move development first, then staging/UAT, then production. Prefer one service or environment at a time. During each stage:

• keep the source configuration unchanged or mirror approved changes through another migration run;
• use dual evaluation in application code where risk justifies it, recording differences without letting the shadow result affect users;
• observe FlagTGL Live events, Context explorer, error rate, latency, and fallback behavior;
• verify browser/mobile exposure rules and ensure server credentials never enter client code;
• retain an application-level switch that returns evaluation to the source during the rollback window.

Replay and ownership handoff

Run the migration a second time before cutover. A healthy replay normally reports matching flags as unchanged, or updated only when the source changed. Unexpected duplicates indicate a key-normalization or scoping problem.

After FlagTGL becomes authoritative:

1. stop scheduled source syncs and document the ownership date;
2. disconnect the migration source in FlagTGL;
3. revoke the provider migration credential;
4. rotate application SDK credentials as needed;
5. configure and test operational integrations independently;
6. retain source exports and audit evidence according to your retention policy;
7. decommission the source only after the rollback window closes.

Captured replay and live contract tests

FlagTGL uses three provider-test modes:

Mode	Provider network calls	Changes the committed capture	Intended use
replay	No	No	Every CI run and local regression testing
live	Yes	No	Check whether current provider APIs still satisfy the importer contract
capture	Yes	Yes	Validate live APIs and deliberately refresh the credential-free CI fixture

The replay fixture is backend/internal/api/testdata/portable-provider-live-capture.json. It contains the portable projects, environments, flags, typed variations, flag state, rules, rollouts, and segments observed through the live APIs. It must never contain provider credentials, source SDK keys, login details, email addresses, or customer identities. The capture test refuses to write if it finds any supplied credential in the serialized result.

Run the deterministic suite with:

make migration-test-replay

For live validation, put the required credentials in an untracked file with mode 0600, then run:

make migration-test-live \
  MIGRATION_CREDENTIALS_FILE=/absolute/path/to/migration-trials.env

Use capture mode only when reviewing an intentional fixture update:

make migration-test-capture \
  MIGRATION_CREDENTIALS_FILE=/absolute/path/to/migration-trials.env
git diff -- backend/internal/api/testdata/portable-provider-live-capture.json
make migration-test-replay

The environment file accepts LAUNCHDARKLY_API_TOKEN, LAUNCHDARKLY_BASE_URL, UNLEASH_ADMIN_TOKEN, UNLEASH_BASE_URL, CONFIGCAT_API_CREDENTIAL_ID, CONFIGCAT_API_CREDENTIAL_PASSWORD, CONFIGCAT_BASE_URL, FLAGSMITH_ORGANISATION_API_KEY, FLAGSMITH_BASE_URL, and FLAGSMITH_PROJECT_ID. Optional LAUNCHDARKLY_MIGRATION_SCOPE, UNLEASH_MIGRATION_SCOPE, CONFIGCAT_MIGRATION_SCOPE, and FLAGSMITH_MIGRATION_SCOPE values override the trial scopes; comma-separate multiple scopes.

Treat a live failure or a changed capture as a provider-contract review, not an automatic fixture update. Determine whether the provider changed pagination, authentication, endpoint shape, typed values, rule semantics, or permissions. Update the importer and its focused parser tests first, then capture again and review the portable semantic diff before committing it.

Failure and rollback

Do not delete the source configuration to fix a failed migration. Correct scope, permissions, unsupported data, or key collisions, then preview again. If production behavior differs, switch application evaluation back to the source, preserve both platforms' logs, capture the mismatching context without secrets, and compare ordered rule evaluation.

Contact [email protected] with the provider, project/config scope, migration job ID, redacted report, and a minimal parity fixture. Never send API keys, SDK secrets, TOTP codes, recovery codes, or raw customer attributes in a support ticket.