Best Practices for Migrating from a Homegrown Feature Management Solution

Before moving to Unleash, many of our customers started with a homegrown feature management solution. We understand! Unleash started as an internal project at a single company written by a single dev, Ivar Østhus, our CTO. At the time, Ivar was a DevOps engineer at Finn and needed to improve the software release process. So he started Unleash. Eventually, it became clear that running a feature management solution at scale wasn’t the job of one person; it was the job of an entire company. The large enterprises we support often come to the same conclusion, so we have a lot of experience enabling customers to migrate from their homegrown feature management solution to Unleash.

More detailed guides are on our documentation outlining Best Practices for feature flag migrations. Approaching the migration from your current feature flag solution to Unleash the right way will save you time, money, and a lot of headaches.

Based on our work with organizations having millions of flags and thousands of users, there are five phases of a feature flag migration:

  1. Define scope
  2. Make business case
  3. Planning
  4. Execution
  5. Onboarding users

We will look at what each entails in this blog, with a more detailed description in our feature flag migration documentation, including a project template you can use to plan your migration.

Defining the scope of the feature flag migration

Scoping the migration properly is the most significant step you can take to ensure the success of your project.

Based on experiences working with dozens of large enterprises migrating homegrown systems to Unleash, we recommend two best practices when scoping your feature flag migration.

1- Separate the migration of old flags from the existing system from new flags created in Unleash.

The older the system, the more existing flags there are. One recent customer we will look at later in this post had 25,000 flags in their legacy system. It might take weeks or months to hunt down the developer responsible for an old flag in an obscure part of the code base. In the meantime, hundreds of developers are trying to create new flags today. By separating these concerns, you can get to the “happy end state” for your development team faster and burn down your flag migrations over time.

So, you should end up with two separate tracks as part of your project scope.

  1. Build the new platform around the “better” target state – ideal use cases and ways of working that enable greater levels of developer efficiency

In parallel, the second track:

  1. Clean up stale feature flags in the current platform. You should decide strategically on what should be migrated and cleaned up. Many old flags can be deleted rather than migrated.

2- Do not make end-to-end app modernization a dependency of your feature flag migration

Organizations who adopt feature flags see improvements in all key operational metrics for DevOps: Lead time to changes, mean-time-to-recovery, deployment frequency, and change failure rate. So, it is natural as part of a feature flag migration to also improve other aspects of the software development lifecycle. From the perspective of feature flag migration, this is a mistake.

Making feature flag migration dependent on breaking down mission-critical monolithic applications into microservices, for example, will slow down your feature flag migration.

Instead, enable feature flags for all codebases, independent of your state of modernization. Even monolithic applications can benefit from feature flags in some instances. When this monolith is broken down, the accrued benefits will be even more significant, and you will ship your new feature management system much faster.

Make the business case for feature flag migration.

Once you have scoped your migration, you need to make a business case. Even the most well-planned migrations take effort, meaning time, money, and energy dedicated to a project. If you don’t have the proper buy-in, you risk being under-resourced or, worse, unable to complete the migration.

When building a business case, you want to be clear on what pain the feature flag migration is solving and the happy end state once the migration is complete.

To structure your thinking, ask yourself:

  • What practices related to feature deployments, debugging, and rollbacks are overburdening teams today and driving down productivity?
  • What specific deficiencies are there in the current platform
  • What business outcomes are you looking to drive?
  • After the migration, what does “better” look like?

Use our Build a Business Case for Feature Flag Migration Template to answer specific questions for your company.

Planning Feature Flag Migration

When planning your feature flag migration, it is essential to focus on four key areas:

  • Use cases
  • Core feature flag setup
  • Key stakeholders
  • System architecture

Use Cases

An essential requirement is to understand how feature flags will be used so that you can set up the proper data model, user permissions, and system architecture.

Below are some of the most common use cases for feature flags. Start by selecting those that are in scope for your initial rollout. It is common to start with some, but not all, of these and roll out the remaining in the future.

Use cases for feature flags:

  • Operational or Permission flags (also known as “Kill Switches”)
  • Gradual rollouts
  • Canary releases
  • A/B testing / Experimentation

Core Feature Flag setup

This planning phase is about understanding the anatomy of the existing feature flag setup so it can be moved to Unleash.

Key questions include:

  • How many many flags are there?
  • How many are active?
  • Do the inactive flags need to be migrated, or can they be removed entirely, simplifying migration?

Once you understand what needs to be migrated, you should plan how flags will be organized. Picking the correct organizing principle is critical for access controls. Unleash supports Application, Project, Environment, and Role-based access, so choose the most logical option for your organization.

Our experience tells us that organizing flags by the development teams that work on them is the best approach. For example:

  • By application or microservice
    • E.g., Shopping Cart, Website, Mobile app
  • By Projects
    • E.g., Logistics, Finance
  • By organization hierarchy
    • E.g., Frontend, backend, platform teams

Key stakeholders

When planning your migration, it is essential to understand who will be managing the feature flag system and who will be using it daily. Additionally, you need to know who will be responsible for crucial migration tasks.

From our experience, looping all key stakeholders into the project early on means that all eventualities can be planned for in advance, reducing the risk of project implementation delays due to unforeseen sign-off requirements. Decision makers can help assign and gather resources needed for the migration and advise on the correct business processes that need to be followed at the various project stages.

System Architecture

You will also need to plan how you set up Unleash itself as part of your migration planning process. Unleash is highly flexible, with lots of hosting and security configuration options to align with the unique requirements of large enterprises.

How is our current feature flag architecture set up?

This part is critical to understanding how Unleash needs to be implemented. This plays a role in resource planning for personnel and infrastructure cost allocation. For instance

  • What languages and frameworks are our front end and back end using?
  • Where are our applications hosted?
  • Where are end users of the application based geographically?

Security and organizational policy requirements

You will also want to pay attention to Security & Organisational Policy requirements.

For example, do you need to keep sensitive context inside your firewall perimeter?

The answer to this question often defines whether you will run Unleash in a hosted or self-hosted fashion.

Many customers prefer a hosted solution if their security policy allows it because it reduces overhead on SRE teams and infrastructure. Unleash offers a single-tenant hosted solution, so even security-conscious customers can sometimes opt for a hosted solution.

If that is not an option, Unleash instances must be managed by customer SRE / DevOps teams. If this is your direction, you should plan for it in this phase of the project.

Other areas of system architecture to investigate during the planning phase are:

  • Data protection
    • Do we have to comply with HIPPA, SOC-2, ISO 27001, GDPR, etc?
      • How do we authenticate and manage user access & RBAC/roles?
      • Do we have any Change Management policies we need to adhere to?
      • Do we consume feature flag data, such as events, in other downstream systems?
        • For example, Jira Cloud for issue management, Datadog for real-time telemetry, Slack or Microsoft Teams for notifications, or Google Analytics for user interactions.

Use our Feature Flag Migration Planning Template to fill in detailed information about each category.

Migration Execution

Now that we have completed the planning, below are some of our Best Practices for carrying out the migration based on our experience.

First, it can help to break the migration down into an order of activities, for example:

  • Minimum Viable Product (MVP) launch
    • Platform implemented, passed security/change management requirements, and available for developer use.
    • Rollout to the highest priority groups of users
    • Matching use cases of the legacy platform
    • Legacy system fallback available
  • Medium-term
    • Rollout to additional groups; adoption of further, less critical use cases
    • Sunset of legacy system
  • Longer term
    • Adoption of new use cases

For each activity, plan for the Level of Effort (LoE) or the number of hours/days the task will take the assigned resource or group to fulfill.

Next up is risk handling. Are there any perceived risks to the timelines that could be addressed upfront?

  • Have the teams involved with the migration committed to set hours for working the migration tasks upfront, have the migration project success criteria and their tasks communicated to them, and have Q&A fulfilled?
  • How long are various sign-offs by any relevant groups expected to take?
    • E.g., Change Advisory Board, Security Controls, hardening checks, etc
    • Plan to exceed each team’s documentation requirements to ensure fewer Requests for Information.

Every step of the way, it can help conduct reviews and look-backs at each rollout stage and what lies ahead.


Finally, after the migration has been completed and everyone has celebrated, you must onboard team members onto the platform.

Unleash Customer Success is here to help; whether your developers are seasoned feature flag management experts or new to the concepts – we will deliver tailored, white-glove training to accommodate use cases and developer skill levels.

In addition, for those who prefer a self-paced approach, a wealth of content is available on our YouTube channel, website, and documentation portal to get your teams going quickly.

Lessons from two large-scale feature flag migrations

How does this process work with large enterprises completing a large-scale feature flag migration? Let’s find out.

How a major US-based e-commerce firm moved 24,000 feature flags off their legacy platform.

Working with one of the largest e-commerce companies in the US, we identified several pain points from their legacy systems and, in working through the migration, came away with several key findings.

Pain points that come with scale

The business problem driving the migration of this large-scale e-commerce provider was three-fold.

First, development teams were burdened with stale, inactive feature flags. Features that had been released in the product previously still had feature flags permanently enabled. This led to a slowdown in velocity as teams dealt with growing technical debt.

Additionally, a highly complex legacy architecture had long troubleshooting times from DevOps teams during service-related events, impacting online sales and user experience.

Finally, the rigidity of the overall system was slowing down innovation. Business applications depended on specific data structures within feature flag payloads, which required preserving the data format expected by the legacy application stack. Because the number of flags was so high, updating the code to adopt a different JSON structure was cost-prohibitive.

Learnings & Observations

As we dug in and understood the current system state with the customer, we found that they had 24,000 feature flags. However, only 16% of these were active and needed to be migrated. Reducing the scope of the project by over 80% dramatically speed up the migration and reduced costs for the customer.

The customer also focused on reaching the happy end state quickly. First, they focused on creating new flags in Unleash as soon as possible to reduce future dependence on a fragile system. For the migrated flags, the customer separated them into different Unleash projects with different access controls. This allowed most feature flag users to start fresh, driving a positive feedback loop from developers adopting Unleash for new flags.

One of the UK’s largest banks accelerates application development while maintaining security posture.

Another recent example of a migration success story comes from one of the UK’s largest banks. With the legacy feature management platform, development teams were limited in how they could target specific groups or users with new features, slowing down innovation. On top of that, the complexity of the existing system made it hard to maintain and manage as the number of flags and developers using the system increased.

But the stakes of the feature flag migration were high. First, in a highly regulated industry, strict change request approvals, separation of concerns between pre-prod and production environments, and sufficient testing before rollout were all non-negotiable.

The migration stakes were also very high because the legacy system included long-lived flags tightly integrated with their operations team as kill switches. While many existing flags could be deprecated, some flags need to be migrated for continued use into Unleash, and the room for error was minimal.

Learnings & Observations

Close collaboration was essential for the success of this migration. After discussing the ideal end-state, the team followed the best practices of separating migration efforts from new feature development. Rather than spend time and effort migrating legacy flags, these were removed manually so that more time could be spent building the ideal end state.

Security and audit were built into the plan from the beginning. In addition to ensuring all functional requirements for feature flags were met, the bank leveraged Unleash Enterprise features like Change Requests to approve changes and updates to new and migrated flags, meeting compliance and audit requirements.

To minimize risk during the rollout of new flags, Unleash Playground was used to compare feature flags across different contexts and between environments to prevent inconsistency and reduce risk.

Finally, the bank was able to meet its strict compliance requirements for the separation of concerns between pre-prod and production environments with separate Unleash instances that communicated via the Unleash Environment export and import capability to move feature flags between them. A combination of Change Requests, rigorous tests, and the right architecture ensured stability, ease of use, and compliance with regulations and internal policies.


This article shared some insights into how we at Unleash Customer Success think about migrations and, from our learnings and expertise, some approaches you can take to break down such large initiatives with direct examples and an action plan.

Thanks for reading, and remember, we are here to listen, help, and support – to see, understand, and surprise! We look forward to hearing from you and learning about your pain points!

Share this article