Mirrors/unleash.unleash
1
0
Fork 0
mirror of https://github.com/Unleash/unleash.git synced 2025-08-13 13:48:59 +02:00
Code Issues Projects Releases Wiki Activity

Second iteration of gudie

Browse Source
This commit is contained in:
melindafekete 2025-07-23 16:46:18 +02:00
parent f773cf364d
commit 191dafd049
No known key found for this signature in database
2 changed files with 254 additions and 142 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

391
website/docs/feature-flag-tutorials/use-cases/organize-feature-flags.mdx
View File

@ -1,213 +1,320 @@
---
title: Organizing feature flags with Unleash environments and projects
title: Organizing feature flags using environments and projects
toc_max_heading_level: 2
---
Feature flag management in a large organization can become complex. Unleash provides environments and projects as key mechanisms to organize your feature flags, making it easier to manage flags across development, testing, and production.
This guide outlines best practices for using environments and projects in Unleash to support diverse team needs, ensure smooth release workflows, and maintain security and compliance.
We’ll cover how to structure feature flags to mirror your organization, manage multiple environments, update flags consistently across projects and environments, handle flag dependencies, and design an architecture that balances open collaboration with proper access control.
As your use of Unleash grows from a handful of developers to hundreds or even thousands, you need to ensure you can maintain control, security, and velocity across your organization.
## Understanding environments: a single feature's journey across your lifecycle
This guide helps you design a structure around Unleash that is scalable and secure. By following these recommendations, you can establish a robust feature management system that supports diverse teams, complex release lifecycles, and enterprise-grade security requirements.
In Unleash, an environment represents a distinct stage in your software development lifecycle.2 Think of them as the places your code runs, such as
development, test, pre-production, and production. While Unleash comes with default development and production environments, Enterprise customers can create, clone, and manage a custom set of environments that precisely matches their organization's workflow, which often includes 3 to 7 stages for larger teams.2
We'll cover how to:
- [Maximize the capabilities of projects and environments](#projects-and-environments-overview), and the [unified flag model](#the-unified-flag-model).
- [Structure your Unleash setup to mirror your organization](#design-your-project-setup) and [release pipeline](#design-your-environments).
- [Design a project architecture that balances open collaboration](#design-for-collaboration-and-visibility) with granular access control.
- [Secure your setup](#secure-your-setup) with environment-specific permissions, SSO, and API tokens.
- [Manage flag configurations consistently](#manage-flag-configurations-across-projects-and-environments) using segments, release templates, and dependencies.
- [Establish best practices](#best-practices-for-long-term-maintenance) for scaling in the long run.
The Unleash difference: the unified flag model
## Projects and environments overview
**Projects** and **environments** are the two main ways to organize your feature flags in Unleash.
A core architectural principle in Unleash is the unified flag model. A feature flag is a single, logical entity that exists across all of your environments. The flag's name, description, and other core metadata are defined once. What changes from one environment to the next is its configuration—the activation strategies, rollout percentages, and variants.2
This model offers several key advantages for enterprise teams:
Holistic view and traceability: You get a complete, unified view of a feature's journey. From a single screen, you can see that the new-checkout-flow flag is enabled for your internal QA team in the test environment, rolled out to 10% of users in pre-production, and currently disabled in production. This eliminates the need to track separate flag instances across different systems, reducing mental overhead and making audits simpler.
Simplified promotion workflow: Promoting a feature from one stage to the next doesn't involve creating a new flag. Instead, you simply update the configuration of the existing flag in the next environment. This workflow is more intuitive, less error-prone, and aligns with the natural progression of a feature through the development lifecycle.
A single source of truth: Because the flag's essential metadata is defined once, you maintain a consistent source of truth. The purpose of checkout.new-payment-gateway.web is the same everywhere, preventing the configuration drift and confusion that can arise when managing separate flag definitions per environment.6
Think of them this way:
### Environment types and the flag lifecycle
- **Projects organize *who***. They group related flags to align with your organizational structure—such as teams, applications, or business units—and are the primary tool for managing access control.
Each environment you create is assigned one of four types: Development, Test, Pre-production, or Production.2 These types are not just labels; they directly influence a flag's automated lifecycle tracking in Unleash. As a flag receives metrics from SDKs connected to these environments, it automatically progresses through distinct stages:
Define: The flag has been created but has not yet been detected in any environment.
Develop: The flag is active and receiving metrics in a non-production environment (e.g., development or test).
Production: The flag is enabled and exposed to users in a production-type environment.
Cleanup: The feature has been marked as "completed" in Unleash, but is still receiving metrics, signaling that it's time to remove the flag's code from your application.
Archived: The flag has been cleaned up from the codebase and archived in Unleash.
This automated lifecycle provides valuable insights into your development process, helping you identify features that are stuck in development or flags that are creating technical debt and need to be cleaned up.6
- **Environments organize *where***. They represent the stages in your deployment pipeline—like development, testing, and production—and control what a flag does in each of those stages.
### Security and access
[projects vs environments diagram coming soon]
Security is enforced at the environment level through API tokens. When you connect an application to Unleash, you use an environment-scoped API token. For instance, your production application will use a production token and can only fetch flag configurations for the production environment.2 This creates a strong security boundary, ensuring that development configurations can never be accidentally served to production users.
A single feature flag is defined once within a project, but its configuration (its on/off state and activation strategies) can be different in each environment. This separation allows you to manage a feature's entire lifecycle safely and efficiently.
### Strategic use cases for cloning environments
## The unified flag model
Unleash Enterprise allows you to clone an entire environment, which duplicates the environment itself along with all its feature flag configurations and states.2 While useful for setting up new, similar environments quickly, this feature enables more advanced, dynamic release workflows.
Consider a "release rehearsal" scenario. Your team is preparing for a complex launch involving ten interdependent feature flags. Instead of testing these changes directly in a shared pre-production environment, you can clone your production environment to create a temporary, high-fidelity release-rehearsal-q4 environment. Within this isolated space, the release team can practice the exact sequence of enabling flags, validating dependencies, and checking system behavior, all without any risk to live systems. This process builds confidence, validates your release runbook, and uncovers potential issues before they can impact customers.
A core architectural principle in Unleash is the **unified flag model**.
## Understanding projects: grouping flags for ownership and context
This means a feature flag is a single, logical entity that exists across all your project's environments. The flag's name, description, and other core metadata are defined once. What changes from one environment to the next is its configuration—the activation strategies, rollout percentages, and variants.
While environments manage a feature's journey through your release process, projects are the primary tool for organizing related feature flags into logical groups.1 Every feature flag in Unleash must belong to a project. A new Unleash instance includes a
default project, but creating custom projects is essential for scaling effectively.
Projects provide several key benefits for organization and governance:
Ownership and context: Projects establish clear ownership boundaries. By grouping flags into projects like project-checkout or project-search, you immediately know which team is responsible for them.
Project status dashboard: Each project has its own dashboard that gives you an at-a-glance overview of its health. This includes metrics on technical debt (the number of stale and potentially stale flags), recent activity within the project, and information on project-specific resources like API tokens.1
Project-specific settings: You can configure settings at the project level, such as a default activation strategy. For example, you can set a rule that any new flag created in the project-payments project is disabled by default in the production environment. This acts as a critical safety net to prevent features from being exposed prematurely.1
Collaboration mode: Projects can be set to "open" (all instance members can submit changes) or "protected" (only specific users or groups can submit changes), giving you control over collaboration workflows.1
This contrasts with approaches in other feature flag providers where you might create entirely separate flag objects for each environment (for example, `new-checkout-dev`, `new-checkout-prod`). That method can lead to configuration drift and makes it difficult to trace a single feature's journey.
### Managing projects
The unified flag model in Unleash offers several key advantages:
- **Holistic view and traceability**: You get a complete, unified view of a feature's journey. At a glance, you can see that the `new-checkout-flow` flag is enabled for your internal QA team in the test environment, rolled out to 10% of users in pre-production, and currently disabled in production. This eliminates the need to track separate flag instances across different systems, reducing mental overhead and making audits simpler.
- **Simplified rollout workflow**: Promoting a feature from one stage to the next doesn't involve creating a new flag. Instead, you simply update the configuration of the existing flag in the next environment. This workflow is more intuitive, less error-prone, and aligns with the natural progression of a feature through the development lifecycle.
- **A single source of truth**: Because the flag's essential metadata is defined once, you maintain a consistent source of truth. The purpose of `checkout.new-payment-gateway.web` is the same everywhere, preventing the configuration drift and confusion that can arise when managing separate flag definitions per environment.
You can manage projects through the Unleash Admin UI or the API. This includes creating new projects, moving flags between existing projects, and archiving or deleting projects. To maintain integrity, a project cannot be deleted until all of the feature flags within it have been archived first.1
## Design your environments
Architectural patterns: designing your project and environment structure
Every project in Unleash contains a set of environments. You should create a set that mirrors your development and release pipeline.
Choosing how to structure your projects is a critical architectural decision that will impact your organization's ability to manage flags efficiently and securely. There is no single "best" way; the right model depends on your team structure, software architecture, and governance requirements. Below are the most common patterns and our recommendation for large enterprises.
A typical setup includes:
- **Development**: For local developer machines or shared development servers.
- **Testing**: For automated tests and manual QA.
- **Staging** (or pre-production): A production-like environment for final validation.
- **Production**: The live environment serving end-users.
Project architecture models
The power of environments is that a single feature flag exists once within a project, but its state and configuration can be different in each environment.
Model Name
Description
Best For
Pros
Cons
Team-Centric
Projects map directly to development teams or squads (e.g., project-checkout, project-search).
Organizations with stable, cross-functional teams aligned to specific business domains.
- Aligns perfectly with agile structures. - Ownership is unambiguous. - Easy to implement team-based RBAC.
- Features spanning multiple teams can be hard to place. - Can lead to coordination overhead for cross-cutting initiatives.
Application-Centric
Projects map to specific applications or microservices (e.g., project-webapp-frontend, project-billing-api).
Organizations with a service-oriented or microservices architecture.
- The "blast radius" of a flag is clearly contained. - Easy for developers to find flags relevant to the service they are working on.
- A single team may work across multiple projects, fragmenting their view. - Can be less intuitive for product managers who think in terms of user-facing features, not services.
Hybrid (Product Line + Tags)
Projects represent major product lines or business units (e.g., project-consumer-banking). Tags are used for granular ownership (team:checkout, app:ios).
Most large, complex enterprises.
- Provides both high-level business organization and granular, filterable metadata. - Highly flexible and scalable. - Balances the needs of technical and non-technical stakeholders.
- Requires discipline in applying tags consistently.
For example, the flag `new-dashboard` can be:
- **On** in the `development` environment for all developers.
- **On** in the `testing` environment, but only for users in the "QA" segment.
- **Off** by default in `production`, but enabled for a small percentage of users for a gradual rollout.
For most large organizations, we recommend the hybrid approach. Using projects to represent broad business domains provides a stable, high-level structure. Layering tags on top of this allows you to add flexible, multi-dimensional metadata for team ownership, affected applications, or release cohorts without being locked into a rigid project structure.6
This separation is critical for safety. It allows developers to work freely in development without impacting production, lets QA teams create specific testing scenarios, and gives product teams fine-grained control over the production rollout.
Securing your setup with role-based access control (RBAC)
Each environment you create is assigned one of four environment types: `development`, `testing`, `pre-production`, or `production`.
These types are not just labels; they directly influence a flag's automated lifecycle tracking in Unleash, helping you identify features that are stuck in development or flags that have become technical debt and need to be cleaned up.
## Design your project setup
Every feature flag in Unleash must belong to a project. A new Unleash instance includes a default project, but creating custom projects is essential for scaling effectively.
Projects help you:
- **Establish clear ownership and context**: By grouping flags into projects like `project-checkout` or `project-search`, you immediately know which team is responsible for them.
- **Understand technical debt at a glance**: Each project has its own dashboard that gives you an instant view of its health, including metrics, recent activity within the project, and information on project-specific resources.
- **Define specific settings**: You can configure settings at the project level, such as a default activation strategy or requiring approvals for changes in production environments.
- **Manage collaboration and visibility**: Projects can be set to open, protected, or private, defining who can access the project or submit change requests.
## Choose a project structure
Choosing how to structure your projects is a critical architectural decision. The right model depends on your team structure, software architecture, and governance requirements.
The goal is to organize your flags in a way that matches how your teams actually work. Avoid putting all flags into one large project, as it quickly becomes difficult to manage permissions and overwhelms users with irrelevant information.
Here are some common and effective strategies for structuring your projects:
**By team or squad**
If your organization is composed of autonomous, cross-functional teams that own features end-to-end, grouping flags by team is an excellent model.
- **Project name**: `payments-squad`, `mobile-core-team`, `growth-hacking`.
- **Pros**: Clearly maps ownership, simplifies access control, and reduces cognitive load for team members.
- **Cons**: May be less intuitive if features often span multiple teams.
**By application or service**
If your teams are structured around specific microservices or applications, organizing projects by that boundary is a natural fit.
- **Project name**: `checkout-api`, `user-profile-service`, `ios-app`.
- **Pros**: Creates a very clear link between a flag and the codebase it lives in. Ideal for technical flags that control infrastructure, performance, or kill switches.
- **Cons**: Can be confusing for user-facing features that involve changes across multiple services, as a single product feature might require coordinating flags across several projects.
**By product line or business unit**
In larger enterprises, it often makes more sense to align projects with broader business contexts rather than individual engineering teams.
In this setup, it's important to use a clear system for tags indicating granular ownership, for example `team:checkout`, `app:ios`.
- **Project name**: `enterprise-accounts`, `consumer-banking`, `insurance-products`.
- **Pros**: Aligns feature management with business-level objectives and scales well in very large organizations.
- **Cons**: Requires discipline in applying tags consistently to indicate clear ownership.
**By initiative or temporary project**
Sometimes, a group of features is part of a single, time-bound initiative, like a major redesign or a new market launch.
- **Project name**: `project-phoenix-redesign`, `new-market-latam`
- **Pros**: Keeps all flags related to a specific initiative in one place, making it easy to archive or clean up once the project is complete.
- **Cons**: Flags might need to be moved to a more permanent project if they persist after the initiative ends.
### Handling cross-application features
A common challenge is managing a single feature that spans multiple services (for example, a frontend application and a backend API). You have two primary strategies:
- **Use a single, shared flag**: If the services are implementing parts of the same logical feature that must be released and enabled together, they should share a single flag from one project. This ensures consistency and acts as a single switch for the entire feature.
- **Use separate, coordinated flags**: If the services are owned by different teams and have different release cadences, it's better to create separate flags in their respective projects. This prevents one team from impacting another's release. The rollout can then be coordinated across teams using release templates.
## Evolve your structure
Remember that your initial project and environment structure is not set in stone. Unleash is flexible. You can add new environments, create new projects, and even move flags between them later on.
The system is designed to evolve with your organization, so don't be afraid to start with a simple setup and refactor as your needs change.
## Design for collaboration and visibility
Modern applications are composed of multiple services with many complex dependencies. While organizing flags into projects is a good starting point, your feature management system should be open by default.
An engineer on the `user-profile-service` team might need to investigate a bug that depends on a flag in the `checkout-api` project.
When someone searches for a flag, they should be able to view its configuration and ownership so they can request access or submit a change request.
This transparency is key to debugging complex, cross-service interactions. Unleash supports private projects, but these should be the exception, not the norm.
## Secure your setup
Once you have a logical structure for your projects and environments, you can secure it using Unleash's role-based access control (RBAC) framework. RBAC allows you to implement the principle of least privilege, ensuring users only have the access they need.
Once you have a logical structure for your projects and environments, you can secure it using Unleash's role-based access control (RBAC) framework. RBAC is the mechanism that enforces governance and allows you to implement the principle of least privilege, ensuring users only have the access they need to perform their jobs.8
Unleash provides two levels of access control:
Root roles: These roles (Admin, Editor, Viewer) grant permissions across the entire Unleash instance. They are intended for administrators who need to manage global resources like users, groups, SSO configurations, and instance-wide settings.8
Project roles: These roles (Owner, Member) grant permissions within a specific project. This is where you will implement the most granular day-to-day access controls for your development teams.1
- **Root roles**: These roles (Admin, Editor, Viewer, or custom) grant permissions across the entire Unleash instance for global resources like users, groups, SSO configurations, and instance-wide settings.
- **Project roles**: These roles (Owner, Member, or custom) grant permissions within a specific project. This is where you implement the most granular day-to-day access controls for your development teams.
### Environment-specific permissions
A key capability for enterprise governance is the ability to define custom project roles with environment-specific permissions. This allows you to precisely control what actions a user can take in each environment.9
For example, you can create a "Developer" role that allows a team member to freely create and modify activation strategies in the development environment but only allows them to submit a change request for the production environment. This workflow empowers developers to innovate quickly in safe environments while ensuring that all changes to production are subject to a formal review and approval process.8
A key capability for enterprise governance is the ability to define custom project roles with environment-specific permissions. This allows you to precisely control what actions a user can take in each environment.
For example, you can create a "Developer" role that allows a team member to freely create and modify activation strategies in the `development` environment but only allows them to submit a change request for the `production` environment.
This workflow empowers developers to innovate quickly in safe environments while ensuring that all changes to production are subject to a formal review and approval process.
Recommended RBAC permissions for common roles
| Role | Permissions in development | Permissions in test | Permissions in production | Rationale |
|-----------------|----------------------------------------------------------|-----------------------------------------------------------|-----------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------|
| Developer | Full access to create/update/delete strategies and flags | Full access to enable/disable flags and update strategies | Read-only access and submit change requests | Allows developers to iterate quickly in their own environment while ensuring changes to production environments are controlled and reviewed |
| QA Engineer | Read-only access | Full access to enable/disable flags and update strategies | Read-only access | Empowers the QA team to fully control feature configurations in their dedicated testing environment without affecting development or production |
| Product Manager | Read-only access | Read-only access | Can enable/disable flags and update rollout percentages via change requests | Allows product managers to control the business logic of a release (e.g., gradual rollouts) in production through a safe, audited approval process |
| DevOps/SRE | Full access | Full access | Full access | Enables platform owners to manage all aspects of the feature flagging system, including acting as kill-switch operators in case of an incident |
Setting up RBAC from scratch can be challenging. This table provides a recommended starting point for configuring permissions for common roles in a typical enterprise workflow.
Role
development Env Permissions
test Env Permissions
production Env Permissions
Rationale
Developer
Full access to create/update/delete strategies and flags.
Read-only access. Can submit change requests.
Read-only access. Can submit change requests.
Allows developers to iterate quickly in their own environment while ensuring changes to shared and production environments are controlled and reviewed.
QA Engineer
Read-only access.
Full access to enable/disable flags and update strategies.
Read-only access.
Empowers the QA team to fully control feature configurations in their dedicated testing environment without affecting development or production.
Product Manager
Read-only access.
Read-only access.
Can enable/disable flags and update rollout percentages via change requests.
Allows product managers to control the business logic of a release (e.g., gradual rollouts) in production through a safe, audited approval process.
DevOps/SRE
Full access.
Full access.
Full access.
Enables platform owners to manage all aspects of the feature flagging system, including acting as kill-switch operators in case of an incident.
### Automating at scale with SSO and SCIM
## Automating at scale with SSO and SCIM
For large organizations, manually managing user accounts and permissions isn't scalable. Unleash integrates with your existing identity provider (like Okta, Microsoft Entra ID, or Keycloak) via SAML or OpenID Connect for single sign-on (SSO).
For large organizations, manually managing user accounts and permissions is not scalable. Unleash integrates with your existing identity provider (such as Okta, Microsoft Entra ID, or Keycloak) via SAML or OpenID Connect for single sign-on (SSO). Furthermore, Unleash supports the SCIM protocol, which automates the provisioning and de-provisioning of users and the syncing of user groups. This ensures that a user's access to Unleash is always in sync with their status in your central identity management system, significantly improving security and reducing administrative overhead.8
Furthermore, Unleash supports the SCIM protocol, which automates the provisioning and de-provisioning of users and the syncing of user groups.
Managing configurations across projects and environments
This ensures that a user's access to Unleash is always in sync with their status in your central identity management system, significantly improving security and reducing administrative overhead.
### Security for API tokens
Security is enforced through API tokens that are scoped to a specific environment and one or more projects. This allows you to apply the principle of least privilege to your applications.
For example, your checkout service would use a token valid only for the `production` environment and the `project-checkout`. This token could not fetch configurations from the `development` environment, nor could it access flags from another project like `project-search`.
This creates a strong security boundary, serving as a critical safeguard against both environment mix-ups and unauthorized cross-project data access.
As with any API token, proper secret management is essential to prevent misuse.
## Manage flag configurations across projects and environments
With a secure and logical structure in place, you can focus on managing flag configurations efficiently.
## Managing strategy variants
### Strategy variants
Strategy variants, used for A/B testing, are configured as part of an activation strategy within a specific environment.
This powerful scoping means you can run a complex experiment with multiple variants in your production environment while the same feature flag has a simple on/off strategy in your development environment.
This allows for safe, targeted experimentation without impacting other stages of your lifecycle.
Strategy variants, used for A/B testing and experimentation, are configured as part of an activation strategy within a specific environment.11 This powerful scoping means you can run a complex experiment with multiple variants in your
production environment while the same feature flag remains completely disabled or configured with a simple on/off strategy in your development environment. This allows for safe, targeted experimentation without impacting other stages of your lifecycle.
[screenshot coming soon]
## Using segments for consistency and scale
### Segments
... and release templates
Segments are reusable collections of strategy constraints.13 They are one of the most powerful tools in Unleash for managing configurations at scale.
Imagine you have a beta program for early adopters. Instead of adding a list of 50 user IDs to every new beta feature flag, you can create a single BetaUsers segment. You then apply this one segment to all ten of your beta flags. When a new user joins the program, you add their ID to the BetaUsers segment in one place, and the change instantly propagates to all ten flags that use it. This reduces redundant configuration, minimizes the risk of human error, and makes managing large user groups effortless.13 Segments can be global (available to all projects) or project-scoped, allowing you to control their visibility and reuse.
Segments are reusable collections of strategy constraints and are one of the most powerful tools for managing configurations at scale. Instead of adding a list of 50 user IDs to every new beta feature flag, you can create a single `BetaUsers` segment. When a new user joins the program, you add their ID to the segment once, and the change instantly propagates to all flags that use it.
This reduces redundant configuration, minimizes human error, and makes managing large user groups effortless. Segments can be global (available to all projects) or project-scoped.
## Managing flag dependencies
### Release templates
Unleash allows you to create parent-child dependencies between flags, ensuring a child flag can only be enabled if its parent flag is also enabled.6 This is useful for coordinating releases where one feature relies on another.
A critical architectural constraint to understand is that dependent flags must belong to the same project.6 This is a deliberate design choice to promote loose coupling and prevent the creation of a complex, brittle web of dependencies between different teams and services. If you find you need a dependency between flags in different projects, it often signals that the features are more tightly coupled than you thought and may belong in the same project, or that your service boundaries may need to be reconsidered. This constraint encourages better architectural design.
To ensure consistency in how you roll out features, you can use release templates.
A release template is a pre-defined set of milestones for different environments. For instance, you could create a "Gradual Rollout UK" template that automatically configures a new flag to be:
- **On** for everyone in `development`.
- **On** only for the `QA Engineers` segment in `testing`.
- **Enabled** for 10% of users in the UK in `production`.
[screenshot coming soon]
Using release templates saves time, reduces manual errors, and ensures that all teams follow a standardized and proven rollout process for common release patterns.
### Flag dependencies
Unleash allows you to create parent-child dependencies between flags, ensuring a child flag can only be enabled if its parent is also enabled.
A critical architectural constraint is that dependent flags must belong to the same project.
This constraint is intentional and crucial for preventing architectural fragility. If a flag in `project-search` could depend on a flag in `project-payments`, the Search team could inadvertently break the Payments feature.
This creates hidden, cross-team dependencies that are difficult to track and debug. By keeping dependencies within a single project, ownership and impact remain clear and contained.
### Cloning environments
Unleash Enterprise allows you to clone an entire environment, which duplicates the environment along with all its feature flag configurations. This is useful for setting up new environments quickly, but it also enables advanced workflows.
For a complex launch, you could clone your production environment to create a temporary `release-rehearsal-q4` environment.
In this isolated space, the team can practice the exact release sequence, validating dependencies and system behavior without any risk to live systems.
## Best practices for long-term maintenance
A feature flagging system requires good hygiene to remain effective. Without it, you risk accumulating technical debt that can make your system difficult to manage and understand.
A feature flagging system requires good housekeeping to remain effective and avoid accumulating technical debt.
### Establish naming conventions
A consistent naming convention is one of the most important practices for maintaining clarity and order, especially in large teams.3 A good name should make a flag's purpose immediately obvious. We recommend a pattern that includes key contextual information, such as:
[project-key].[feature-description].[platform]
For example: checkout.new-payment-gateway.web
Unleash Enterprise helps you enforce this discipline. At the project level, you can define a regular expression that all new feature flag names must match. This ensures that all flags created in that project, whether through the UI or the API, adhere to your chosen convention.6
A consistent naming convention is crucial for clarity. A good name should make a flag's purpose immediately obvious.
Because flag names must be unique across the entire Unleash instance, plan a convention that ensures uniqueness.
### Manage technical debt: the flag lifecycle
[screenshot coming soon]
Most feature flags are temporary. They are created to serve a specific purpose—like a release, an experiment, or an operational migration—and should be removed once that purpose is fulfilled.6 Only certain types of flags, like kill switches or long-term permission flags, are intended to be permanent.
The process for cleaning up a temporary flag is straightforward:
Once the feature is fully rolled out and stable, the flag's code is no longer needed. Mark the flag as stale in Unleash.
This "stale" status signals to developers that it is safe to remove the corresponding if/else blocks from the codebase. The project status dashboard makes it easy to find all stale flags that are ready for cleanup.1
After the code has been removed and deployed, you can archive the flag in Unleash. This removes it from the active list but preserves its history for auditing purposes.6
To ensure these conventions are followed, Unleash allows you to enforce a specific naming pattern at the project level.
For example, in `project-checkout`, you could require all new flags to follow the pattern `checkout-[feature-name]`. Any attempt to create a flag with a non-compliant name will be rejected.
This is a key governance tool for preventing a chaotic and inconsistent flag namespace as your organization grows.
### Use tags for discovery and automation
Tags are free-form, key-value labels that you can apply to feature flags to add flexible, cross-project metadata. They are an essential tool for discovery and automation.6 You can use tags to:
Filter and search: "Show me all flags tagged with team:payments."
Indicate ownership: "Who is the point of contact for this flag? Check the owner:jane.doe@example.com tag."
Drive automation: Use tags to configure integrations. For example, you can set up a rule that any updates to flags tagged with slack-channel:checkout-alerts will automatically post a notification to that specific Slack channel.6
Tags are free-form labels that you can apply to feature flags to add flexible, cross-project metadata.
## Frequently asked questions (FAQa)
You can use tags to:
- **Filter and search**: "Show me all flags tagged with team:payments."
- **Indicate ownership**: "Who is the point of contact for this flag? Check the owner:jane.doe@example.com tag."
- **Drive automation**: Configure integrations. For example, you can post a Slack notification for any updates to flags tagged with `slack-channel:checkout-alerts`.
Use colors in tags to add further visual distinctions and make flags easy to identify at a glance.
### Mandate approvals and audit everything
For critical environments like production, enable change requests to enforce a "four-eyes principle", where one user proposes a change and another must approve it. This is essential for compliance and preventing costly mistakes.
Equally important is tracking what happens to your flags. In Unleash, Event Log provides accountability, simplifies debugging, and is indispensable for security and compliance.
## Key takeaways
By following these best practices, you can harness Unleash to bring order and scalability to your feature management. A well-designed system leads to a more secure, collaborative, and efficient rollout process for all your features.
Remember these core principles:
- **Structure follows strategy**: Align your projects with your team structure (for example, by team, application, or business unit).
- **Environments map to your deployment pipeline**: Create environments that mirror your actual release stages.
- **Embrace the unified model**: Manage one flag across its entire lifecycle for a single source of truth.
- **Secure by design**: Use RBAC, environment-specific permissions, and SSO to enforce the principle of least privilege.
- **Maintain clarity and auditability**: Enforce naming conventions, use tags, require approvals, and audit everything to prevent technical debt.
## Frequently asked questions (FAQs)
**How is Unleash's environment model different from other tools like LaunchDarkly?**
Unleash uses a unified flag model where a single flag is a persistent entity across all environments, with only its configuration (strategies, variants) changing per environment. This provides a holistic, end-to-end view of a feature's lifecycle from a single dashboard.2 Other tools may treat flags in each environment as more distinct, separate objects, which can sometimes make it harder to trace a single feature's entire journey.17 The key benefit of the Unleash model is simplified management, clear traceability, and a more intuitive structure for applying environment-specific RBAC.
Unleash uses a unified flag model where a single flag is a persistent entity across all environments, with only its configuration (strategies, variants) changing per environment. This provides a holistic, end-to-end view of a feature's lifecycle from a single dashboard.
**What's the best way to handle a feature that spans multiple projects?**
First, this is a good opportunity to evaluate your project boundaries. If the features are tightly coupled and must be released together, they might belong in the same project. If they are truly separate but need to be coordinated, the best practice is to create separate feature flags in each respective project and coordinate their rollout manually or through external automation scripts that use the Unleash API. This approach respects project boundaries and avoids creating hidden, complex dependencies across different teams or services.
Other tools may treat flags in each environment as more distinct, separate objects, which can sometimes make it harder to trace a single feature's entire journey. The key benefit of the Unleash model is simplified management, clear traceability, and a more intuitive structure for applying environment-specific RBAC.
**How can we synchronize flag configurations between a staging and production environment?**
For Unleash Enterprise users, the "clone environment" feature is the quickest way to create a new environment with a configuration identical to an existing one.2 When promoting changes from an existing environment (like
staging) to another (like production), the recommended workflow is to manually re-configure the flag's activation strategies in the target environment. This intentional, manual step serves as a final safeguard before impacting users. For teams that require full automation, the Unleash API can be used to build scripts that read the configuration from a source environment and apply it to a target environment.
The recommended workflow is to manually re-configure the flag's activation strategies in the target environment (e.g., production). This intentional step serves as a final safeguard.
For Enterprise users, the "clone environment" feature can bootstrap a new environment.
For full automation, you can use the Unleash API to build scripts that read the configuration from a source environment and apply it to a target.
**Can I restrict a user's access to only one environment within a project?**
Yes. This is a core use case for custom project roles. You can create a new role (e.g., "QA Tester") and grant it permissions, such as UPDATE_FEATURE_STRATEGY, only for the test environment. For all other environments like development and production, you would grant no permissions or read-only permissions. This ensures the user can only make changes in their designated environment.9
**What happens if I move a flag with dependencies to another project?**
This action is not directly supported because Unleash requires that parent and child flags in a dependency relationship exist within the same project.6 You would need to remove the dependencies before you could move the flag. This constraint is a deliberate design choice to prevent tight, unmanageable coupling between features owned by different teams or services.
Yes. This is a core use case for custom project roles. You can create a new role (for example, "QA Engineer") and grant it permissions, such as `UPDATE_FEATURE_STRATEGY`, only for the test environment. For all other environments like development and production, you would grant no permissions or read-only permissions. This ensures the user can only make changes in their designated environment.
**How many environments should we have?**
This depends entirely on your team's release process. A typical setup for a large organization is three to five environments:
development: For local developer machines and CI builds.
test or qa: A shared, stable environment for dedicated testing by the QA team.
staging or pre-prod: A production-like environment for final validation, performance testing, and release rehearsals.
production: The live environment for your end users.
It depends on your release process. A typical setup for a large organization is three to five environments:
- development: For local developer machines and CI builds.
- test or QA: A shared, stable environment for dedicated testing by the QA team.
- staging or pre-prod: A production-like environment for final validation, performance testing, and release rehearsals.
- production: The live environment for your end users.
Some organizations add more specialized environments, such as one for demo purposes or a hotfix environment for emergency patches.
**What is the difference between a segment and a strategy constraint?**
**How many projects should we create?**
A strategy constraint is a single rule (e.g., userId is one of ``) that is applied to a single activation strategy. A segment is a reusable collection of one or more strategy constraints.13
Use a simple constraint for a rule that is unique to one specific flag's strategy. Use a segment when you have a set of rules that you expect to reuse across multiple feature flags, such as targeting a group of BetaUsers or users in a specific Region. Updating the segment updates all flags that use it, saving time and ensuring consistency.13
Start with a structure that mirrors how your teams are organized. Avoid the extremes of a single monolithic project or a separate project for every feature.
A good rule of thumb is to create projects for distinct, long-lived teams, products, or applications. You can always refactor later.
**Can a single feature flag exist in multiple projects?**
No. A feature flag belongs to exactly one project. This is fundamental to Unleash's model, as the project defines the flag's ownership and access control.
**We are a small team just starting out. What's a good initial setup?**
Start simple. Use a single project named after your main application or team. Within that project, use the two default environments: `development` and `production`. This provides the essential separation and is easy to manage.
You can add more environments or projects as you grow.
**How do we handle flags that are used in multiple services or applications?**
This is a strength of a centralized system. If multiple services need to check the same flag, they can all use the same Unleash project and environment API key. However, it doesn't always make sense for different services to share flags.
- When to use a single flag: If multiple services are implementing parts of the same logical feature that must be released together, they should share a single flag from one project. This ensures consistency.
- When to use separate flags: If the services are owned by different teams and have different release cadences, or if the functionality is related but not tightly coupled, it's better to create separate flags in their respective projects. This prevents one team from impacting another's release.
**What if a team needs a new environment or project later on?**
Unleash is flexible. You can add new environments at any time and decide which projects they apply to. You can also create new projects and even move flags between them if their environment setups are compatible. The system is designed to evolve with your organization, so don't be afraid to refactor your setup as your needs change.
**What's the best way to handle a feature that spans multiple projects?**
First, evaluate your project boundaries. If the features are tightly coupled and must be released together, they might belong in the same project. If they are separate but need coordination, the best practice is to create separate flags in each project and coordinate their rollout manually or through external automation. This respects project boundaries and avoids creating hidden, complex dependencies.
**Can we manage our Unleash setup using Infrastructure as Code tools like Terraform?**
Yes, and it is a highly recommended practice for ensuring consistency and automation at scale. Unleash has a Terraform Provider that allows you to manage your instance configuration—things like projects, environments, segments—as code.
This brings your feature flag configuration into a Git workflow, enabling version control, peer reviews, and automated, repeatable deployments. It's a powerful approach for platform and DevOps teams looking to manage Unleash at scale.

5
website/sidebars.ts
View File

@ -265,6 +265,11 @@ const sidebars: SidebarsConfig = {
label: 'Scaling Unleash',
id: 'feature-flag-tutorials/use-cases/scaling-unleash',
},
{
type: 'doc',
label: 'Organizing feature flags using projects and environments',
id: 'feature-flag-tutorials/use-cases/organize-feature-flags',
},
],
},
{