Migrate from Unleash

Last updated: April 2026

Moving from Unleash to FeatureSignals? This step-by-step guide walks you through exporting your Unleash feature toggles, transforming them to the FeatureSignals flag model, importing them, and validating parity — so you can switch with confidence.

Prerequisites

A running Unleash instance with admin access
A FeatureSignals account (Free tier is fine for migration testing)
A FeatureSignals API key with admin scope
The FeatureSignals CLI installed (npm i -g @featuresignals/cli)

Step 1: Export from Unleash

Unleash provides an admin API for exporting feature toggles. Use the FeatureSignals migration CLI to automate the export:

fs-migrate export unleash \ --url https://your-unleash-instance.com/api \ --token $UNLEASH_ADMIN_TOKEN \ --output ./unleash-export.json

The export captures:

Feature toggles with their strategies and variants
Activation strategies (gradual rollout, user IDs, IPs, etc.)
Strategy constraints and segments
Project and environment associations
Toggle state (enabled/disabled per environment)

Unleash Strategy → FeatureSignals Rule Mapping

Unleash activation strategies map to FeatureSignals targeting rules. The migration engine handles these automatically:

default → Boolean flag with default serve value

userWithId → Individual targeting (user ID list)

gradualRolloutUserId → Percentage rollout (deterministic by user ID)

gradualRolloutSessionId → Percentage rollout (deterministic by session)

remoteAddress → IP-based targeting rule

flexibleRollout → Percentage rollout with stickiness

Step 2: Transform for FeatureSignals

The migration engine analyzes your exported data and generates a preview report before writing anything:

fs-migrate transform unleash \ --input ./unleash-export.json \ --project my-project \ --preview

The preview report shows:

Number of feature toggles that will be created
Strategy-to-rule mappings with rationale
Any unsupported strategies that need manual migration
Variant mappings (Unleash variants → FeatureSignals AB flag type)

Unleash-Specific Considerations

Custom activation strategies:Custom strategies are flagged for manual review. You'll need to reimplement them as FeatureSignals targeting rules.
Segments (Unleash 4.x): Unleash segments map to FeatureSignals segments. Constraints with IN/NOT_IN operators are translated directly.
Impression data:Unleash impression events don't have a direct equivalent. Consider the FeatureSignals evaluation reason feature for debugging.
Stickiness: FeatureSignals uses deterministic hashing (MurmurHash3) for consistent percentage rollouts. The same user ID will consistently resolve to the same bucket.

Step 3: Import to FeatureSignals

Once you're satisfied with the preview, run the import:

fs-migrate import \ --input ./unleash-transformed.json \ --api-key $FS_API_KEY \ --env staging

The import is transactional — if any flag fails, the entire batch is rolled back. Always import to a staging or test environment first.

Import to a non-production environment first
Verify flags appear correctly in the Flag Engine dashboard
Test evaluations match expected Unleash behavior
Review targeting rules for accuracy

Step 4: Migrate Your SDK

Unleash and FeatureSignals both support OpenFeature, making SDK migration straightforward. Replace the Unleash provider with the FeatureSignals provider:

Node.js Example

// Before (Unleash) const unleash = require('unleash-client'); unleash.initialize({ url, appName, instanceId }); // After (FeatureSignals with OpenFeature) const { FeatureSignalsProvider } = require('@featuresignals/openfeature'); OpenFeature.setProvider(new FeatureSignalsProvider({ apiKey: process.env.FS_API_KEY, })); const client = OpenFeature.getClient();

Step 5: Validate Parity

Run the parity checker to confirm flags evaluate identically in both systems:

fs-migrate validate \ --source unleash \ --source-config ./unleash-config.json \ --target featuresignals \ --target-config ./fs-config.json \ --sample-size 1000

The validator evaluates each flag in both systems with 1,000 random user contexts and reports any discrepancies with the specific flag, context, and expected vs. actual value.