Cross-Environment Migration

FlagFlow's migration system enables you to transfer feature flag configurations between different environments, such as promoting flags from development to staging or from staging to production. The system intelligently compares flag configurations and generates specific migration steps to synchronize environments safely.

FlagFlow analyzes the differences between source and target environments and generates specific migration steps:

Step 1: Export from Source Environment

First, create an export from your source environment (e.g., development or staging):

# Export from source environment
curl -O http://staging.flagflow.com/migration/export

# This creates a file like:
# flagflow_migration_staging_20240810-143025.json

Step 2: Upload to Target Environment

In your target environment's FlagFlow interface:

1. Navigate to the Migration page
2. Locate the File-based Migration section
3. Click Choose File and select your exported JSON file
4. Click Analyze Migration to generate migration steps

Step 3: Review and Execute Migration Steps

The migration executor will show you all the changes that will be made:

• Environment flow indicator showing source → target
• Complete list of migration steps with checkboxes
• Dependencies between steps shown with indentation
• Option to include or exclude value-setting steps

Configuration

To enable remote migration, configure the source environment URL in your target environment:

# Environment variables for target environment
MIGRATION_SOURCE_URL=http://staging.flagflow.com
MIGRATION_SOURCE_ENVIRONMENT=staging

# Other standard configuration
ENVIRONMENT=production
LOGLEVEL=info

Using Remote Migration

When properly configured, remote migration provides a streamlined experience:

1. Navigate to the Migration page in your target environment
2. You'll see a Remote Migration section with your configured source
3. Click Fetch and Analyze to retrieve the latest configuration
4. Review and execute the generated migration steps

Pre-Migration Validation

FlagFlow performs comprehensive validation before allowing migration:

• Environment Check: Ensures source and target environments are different
• File Format: Validates JSON structure and required fields
• Flag Schema: Validates all flag types and constraints
• Flag Values: Ensures values match their respective schemas
• Dependencies: Checks that all step dependencies can be satisfied

Step Dependencies

Some migration steps depend on others and are automatically ordered:

Example migration with dependencies:

1. DELETE old_feature_flag
   └── 2. CREATE_DEFAULTVALUE new_feature_flag  (depends on #1)
       └── 3. SET_VALUE new_feature_flag = true (depends on #2)

4. UPDATE_SCHEMA_DEFAULTVALUE max_connections
   └── 5. SET_VALUE max_connections = 100      (depends on #4)

Rollback Considerations

Schema-Only Migration

The default migration approach transfers only flag schemas and structures, not values:

• Ensures consistent flag definitions across environments
• Preserves environment-specific value configurations
• Safer for production deployments
• Allows gradual value updates after schema migration

Full Migration (Schema + Values)

Use the "Add value steps" option to include value migrations:

• Completely synchronizes environments
• Useful for replicating testing configurations
• May override important environment-specific settings
• Requires careful review before execution

Selective Migration

Choose which migration steps to execute:

• Uncheck steps you don't want to execute
• Migrate only specific flags or changes
• Useful for gradual rollouts or testing
• Dependencies must still be satisfied

Development → Staging

# Scenario: Promote new feature flags to staging
# Steps typically generated:

1. CREATE_DEFAULTVALUE new_feature_toggle (BOOLEAN)
2. CREATE_DEFAULTVALUE feature_rollout_percent (INTEGER) 
3. CREATE_DEFAULTVALUE supported_regions (TAG)

# Values are NOT migrated by default
# Staging team can set appropriate values for their environment

Staging → Production

# Scenario: Promote tested features to production
# More careful approach with schema-only migration

1. UPDATE_SCHEMA_DEFAULTVALUE existing_feature (new enum values)
2. CREATE_DEFAULTVALUE production_ready_feature (BOOLEAN)
3. DELETE experimental_flag (removed in staging)

# Production values remain unchanged
# Operations team sets production-appropriate values

Hotfix Deployment

# Scenario: Emergency flag changes across environments
# Include values for immediate effect

1. CREATE_DEFAULTVALUE emergency_circuit_breaker (BOOLEAN)
2. SET_VALUE emergency_circuit_breaker = true

# Execute immediately with values to enable circuit breaker

Pre-Migration

• Create Backup: Always export current target environment configuration first
• Review Changes: Carefully examine all generated migration steps
• Test First: Run migrations on development/staging before production
• Communication: Notify team members of planned migrations

During Migration

• Selective Execution: Consider excluding value-setting steps initially
• Monitor Dependencies: Ensure all required steps are selected
• Verify Steps: Double-check critical flag changes
• Gradual Rollout: Consider migrating flags in phases

Post-Migration

• Verification: Confirm all flags migrated correctly
• Value Configuration: Set appropriate values for the target environment
• Testing: Validate application behavior with new flag configurations
• Documentation: Update team documentation with changes

Automated Migration Scripts

#!/bin/bash
# automated-migration.sh
# Automate flag migrations in CI/CD pipelines

SOURCE_ENV="staging"
TARGET_ENV="production"
BACKUP_DIR="/tmp/flagflow-backups"

echo "🚀 Starting automated migration: $SOURCE_ENV → $TARGET_ENV"

# Step 1: Create backup of target environment
echo "📦 Creating backup of $TARGET_ENV..."
mkdir -p "$BACKUP_DIR"
BACKUP_FILE="$BACKUP_DIR/pre-migration-backup-$(date +%Y%m%d-%H%M%S).json"
curl -s "http://$TARGET_ENV.flagflow.com/migration/export" -o "$BACKUP_FILE"

if [ ! -f "$BACKUP_FILE" ]; then
    echo "❌ Failed to create backup"
    exit 1
fi

echo "✅ Backup created: $BACKUP_FILE"

# Step 2: Fetch source configuration
echo "📥 Fetching source configuration from $SOURCE_ENV..."
SOURCE_FILE="$BACKUP_DIR/source-config-$(date +%Y%m%d-%H%M%S).json"
curl -s "http://$SOURCE_ENV.flagflow.com/migration/export" -o "$SOURCE_FILE"

if [ ! -f "$SOURCE_FILE" ]; then
    echo "❌ Failed to fetch source configuration"
    exit 1
fi

echo "✅ Source configuration fetched: $SOURCE_FILE"

# Step 3: Validate files
echo "🔍 Validating configuration files..."
jq empty "$BACKUP_FILE" && jq empty "$SOURCE_FILE"
if [ $? -ne 0 ]; then
    echo "❌ Invalid JSON in configuration files"
    exit 1
fi

echo "✅ Configuration files validated"
echo "🎯 Migration ready. Upload $SOURCE_FILE to $TARGET_ENV manually or via API"
echo "🔄 Backup available at: $BACKUP_FILE"

CI/CD Pipeline Integration

# GitHub Actions example
name: Deploy Feature Flags
on:
  push:
    branches: [main]

jobs:
  migrate-flags:
    runs-on: ubuntu-latest
    steps:
      - name: Backup Production Flags
        run: |
          curl -o prod-backup-$(date +%Y%m%d).json \
            {{ secrets.PROD_FLAGFLOW_URL }}/migration/export
      
      - name: Export Staging Flags  
        run: |
          curl -o staging-export.json \
            {{ secrets.STAGING_FLAGFLOW_URL }}/migration/export
      
      - name: Upload Migration Artifacts
        uses: actions/upload-artifact@v2
        with:
          name: migration-files
          path: |
            prod-backup-*.json
            staging-export.json
      
      # Manual approval step before production migration
      - name: Wait for Approval
        uses: trstringer/manual-approval@v1
        with:
          secret: {{ github.TOKEN }}
          approvers: production-team
          
      # Note: Actual migration execution should be done manually
      # or through a separate secure process

After completing a migration, consider these follow-up actions:

• Configure Values: Set appropriate flag values for the target environment
• Test Applications: Verify that applications work correctly with migrated flags
• Update Documentation: Document any environment-specific flag configurations
• Plan Rollbacks: Keep backups ready in case rollback is needed

For restoring from backups within the same environment, see the Restore documentation. For creating backups, see the Export and Backup documentation.