Feature flags can help teams separate deployment from release, but only when each flag has a clear purpose, owner, rollout plan, and removal date. This checklist explains how to manage a feature flag from naming and testing through gradual release, incident response, and code cleanup.
Overview
A feature flag is a runtime control that changes application behavior without requiring a new deployment. That flexibility is useful for releasing incomplete work safely, testing an idea with a defined audience, controlling an operational capability, or restricting access to a permissioned feature. It also creates a new form of configuration that must be documented, tested, observed, and eventually removed.
Good feature toggle lifecycle management treats every flag as temporary or explicitly maintained configuration. Before creating one, the team should answer five questions:
- What behavior does the flag control?
- Why is a flag needed instead of a normal code change or configuration value?
- Who owns the decision to enable, disable, or remove it?
- Which environments and user groups can receive the enabled behavior?
- When will the team review or retire the flag?
Keep the flag definition close to the delivery workflow. If a CI/CD pipeline promotes code through staging, preproduction, and production, record the intended flag state at each stage rather than assuming that every environment should match. The distinction between staging, preproduction, and production matters because a flag may be enabled for testing in one environment while remaining disabled for customers.
Checklist by scenario
1. Create and name the flag
- Use a stable, descriptive name that reflects the behavior, not a temporary ticket number. For example,
checkout.new_address_validationis more useful thanflag_1842. - Choose a consistent naming convention for team, service, domain, and behavior.
- Write a short description explaining what changes when the flag is enabled.
- Assign a directly responsible owner and a backup team or person.
- Record the flag type, creation date, expected review date, and planned removal date.
- Document the safe default for missing, invalid, or unavailable flag data.
2. Select the right flag type
| Flag type | Primary purpose | Lifecycle guidance |
|---|---|---|
| Release | Keep new or incomplete functionality separate from deployment. | Remove soon after the release is fully adopted and the old path is deleted. |
| Experiment | Compare defined variants for a product or engineering question. | Set an analysis window, success criteria, audience rules, and decision date. |
| Operational | Control capacity-sensitive or failure-prone behavior, such as a background job. | Document the safe incident state and keep ownership clear if the control is long-lived. |
| Permission | Limit access based on role, account, plan, or approved group. | Review authorization logic separately; do not treat a flag as the only security boundary. |
The type determines the review process. A release flag generally needs a removal task. An experiment needs a measurement plan. An operational flag needs a runbook and an incident owner. A permission flag needs careful treatment of identity, privacy, and authorization data.
3. Test in preproduction
- Verify both enabled and disabled paths, including the default behavior when the flag service is unavailable.
- Test combinations with related flags. Interactions can create states that are not covered by a single-feature test.
- Use representative but safe test data. Follow a documented preproduction test data workflow when copying, resetting, or anonymizing data.
- Confirm that secrets, credentials, and environment-specific configuration are not exposed through targeting rules or logs. The preproduction secrets checklist can support this review.
- Test the flag state alongside API contracts, containers, and deployment dependencies. Contract checks can reveal whether the new path changes a response or request unexpectedly; see the API contract testing workflow.
- Include flag state in deployment evidence so reviewers know what was tested and what will be enabled after promotion.
4. Roll out gradually
- Start with the flag disabled or limited to an internal test group, depending on the risk and purpose.
- Enable a small, explicitly defined audience or percentage where the platform supports deterministic targeting.
- Watch technical and product signals before increasing exposure. Useful signals may include error rate, latency, task completion, support reports, and relevant business events.
- Increase exposure in documented steps rather than making an unrecorded manual change.
- Pause or reverse the rollout when an agreed threshold is exceeded.
- After full release, confirm that the old code path is no longer needed and schedule removal.
Observability should make flag changes visible in context. Record the evaluated flag version or key in appropriate traces and structured logs without exposing personal data or sensitive targeting attributes. The preproduction observability guide provides a useful model for connecting deployment signals with application behavior.
5. Prepare the kill switch
- Define which state reduces risk during an incident; “off” is not automatically the safe state.
- Document who can change the flag during an incident and whether approval is required.
- Verify that the control plane, SDK cache, or local fallback can deliver the intended state.
- Write the reversal step into the service runbook and test it before launch.
- After using the kill switch, open a follow-up task to investigate the cause and decide whether the flag should remain, change, or be removed.
What to double-check
Before enabling a flag for a wider audience, review the following inventory fields:
Flag key:
Type: release | experiment | operational | permission
Description:
Owner and backup:
Service and repository:
Default when unavailable:
Enabled in: local | test | staging | preproduction | production
Targeting rules:
Data or privacy considerations:
Success and failure signals:
Kill-switch procedure:
Created:
Review date:
Removal date:
Removal task or change request:
Also check SDK behavior. Different implementations may evaluate flags locally, remotely, from cached values, or through a fallback. Confirm startup behavior, timeout behavior, cache freshness, and what happens when a key is missing. A flag that controls a request path should be tested under dependency failure, not only under normal application startup.
Review targeting rules for unintended overlap. A broad rule placed before a narrow rule can cause the wrong audience to receive a feature. Avoid using raw personal information in flag attributes when a less sensitive identifier or group membership will work. Ensure that access control remains enforced by the application or identity system rather than relying solely on a user-visible toggle.
Common mistakes
- Permanent release flags: A completed launch is treated as finished, but the flag and old implementation remain indefinitely. Create the removal task when the flag is created.
- Unclear ownership: “The product team” or “the platform team” is too broad for an incident decision. Name a responsible role or person and a backup.
- Testing only the enabled path: Disabled, missing, stale, and unavailable states can fail independently. Include them in automated and preproduction checks.
- Too many flag combinations: Interacting toggles multiply test states. Remove completed flags and avoid using flags for unrelated concerns.
- Flags used as security controls: A rollout rule can improve release control but should not replace server-side authorization.
- Silent manual changes: Changing production state without a recorded reason makes incidents and audits harder to understand. Connect changes to a deployment, ticket, or incident record.
- No cleanup evidence: Deleting a dashboard entry is not the same as removing the conditional code, tests, configuration, and documentation.
When to revisit
Review the feature-flag inventory before every planned launch, rollout expansion, and seasonal planning cycle. Revisit it immediately when ownership changes, a service is reorganized, a flag platform or SDK changes, or a deployment workflow moves between tools. Platform changes can affect evaluation, caching, targeting, and CI/CD integration, so repeat the enabled, disabled, and unavailable-state tests after a material implementation change.
Schedule a monthly or quarterly stale-flag review according to the number and risk of flags your team maintains. For each candidate, ask whether the flag is still serving its original purpose, whether its owner is current, whether its targeting rules are still valid, and whether the conditional code can be removed. Coordinate cleanup with release engineering: image promotion, Kubernetes deployment manifests, infrastructure changes, and automated tests may all contain references to the flag. A container promotion review and a Kubernetes preproduction check can help catch environment-specific effects.
Use this final action list for every flag review:
- Confirm the owner, type, purpose, and safe default.
- Verify enabled, disabled, missing, and service-unavailable behavior.
- Check targeting, privacy, authorization, and observability details.
- Compare the recorded state with the actual state in each environment.
- Decide whether to keep, narrow, roll back, or remove the flag.
- Record the decision and create a dated cleanup task when removal is not immediate.
Feature flags improve engineering productivity when they make decisions explicit rather than invisible. A maintained inventory, tested fallback, observable rollout, and scheduled cleanup keep that flexibility from becoming unmanaged release complexity.