GitLab Feature Flags

This guide defines the BetterFleet Manage feature-flag process.

Purpose

• Align daily rollout practice with the intended feature-control model.
• Keep stage language, release communication, help-doc follow-through, and retirement expectations consistent.
• Make current usage explicit instead of relying on implied team knowledge.

Operating Model

• Runtime rollout state lives in GitLab Feature Flags and GitLab user lists.
• The Manage sysadmin feature-flag page is the operational view of stage and user access.
• The frontend still reads feature flags through Unleash.
• Local web development enables all flags by default unless VITE_FEATURE_FLAGS_READ_FROM_UNLEASH=true.
• bf-manage-web/feature-flags.md is the inventory of Manage flags.
• Owner, rollout intent, release-note expectation, help-doc expectation, and retirement expectation must still be visible in the governed story, MR, or linked Linear work.

If the product behavior and this guide disagree, follow the product behavior and fix the guide.

Stage Language

Use this language in process conversations:

Process term	Sysadmin label	Implementation rule	Meaning
Internal	Pre-Release	Any flag that is not All Users and does not use a Beta user list	limited rollout for internal or tightly controlled audiences
Beta	Beta	At least one GitLab user list whose first word is Beta	limited rollout for a named beta audience
Fully Released	Fully Released	All Users strategy is present	normal product behavior for everyone

Additional rules:

• enabled and stage are separate. A disabled flag is still off even if its derived stage is Beta or Fully Released.
• Beta detection is based on the first word of the user-list name being Beta, case-insensitive. Use names like Beta Customers or Beta Feature X. Do not rely on beta-* naming with punctuation and no space.
• Pre-Release is the sysadmin label for what the process should treat as Internal.

Working Process

1. Define the flag before or with implementation.
2. Choose a stable flag name.
3. Record the intended audience, stage, owner, release-note expectation, help-doc expectation, and retirement expectation in the story, MR, or linked Linear work.
4. Add the flag to bf-manage-web/feature-flags.md when it is a Manage flag in active use.
5. Deploy independently from rollout.
6. Code may be deployed before the flag is broadly available.
7. Do not use deployment alone as evidence that a feature is released.
8. Set rollout using the GitLab conventions.
9. Use explicit users or non-Beta user lists for Internal.
10. Use Beta-named GitLab user lists for Beta.
11. Use All Users only when the feature should behave as standard product behavior.
12. Check the sysadmin page after rollout changes.
13. Confirm the derived stage matches the intended stage.
14. Confirm the expected users have or do not have access.
15. Treat local development as a convenience, not rollout truth.
16. If rollout-accurate local behavior matters, set VITE_FEATURE_FLAGS_READ_FROM_UNLEASH=true.
17. Do not use local default all-flags-enabled behavior as release evidence.

Release Notes And Help Docs

• Feature-flagged work still follows the normal release-note and help-doc process.
• Internal, shown in sysadmin as Pre-Release, should usually stay in holdback.md unless it is intentionally being communicated to internal or System Admin audiences now.
• Beta work may go to next.public.md, next.internal.md, or holdback.md depending on who should be told about it now.
• Fully Released work should be treated as normal shipped behavior in release communication.
• Do not expose raw feature-flag names in public or internal release-note entries; keep rollout labels in holdback.md when needed to preserve unpublished context.
• Update in-app help when flagged behavior changes what the intended current audience should see, expect, or do.
• Do not update general help as if a feature is broadly available while it is still Internal or Pre-Release.

Retirement

• All Users is the technical marker for Fully Released. It is not the desired long-term resting state.
• Moving a flag to All Users starts retirement.
• Record a retirement owner and due date in the story, MR, or linked execution issue.
• Remove the feature flag and stale conditional code in the next practical slice. Same-MR removal is preferred when easy, but it is not required.
• Do not leave permanent All Users flags in place without an active cleanup expectation.
• Remove retired flags from bf-manage-web/feature-flags.md.

References

• Manage inventory: bf-manage-web/feature-flags.md
• Release-note guide: docs/process/guides/release-notes.md
• In-app docs guide: docs/process/guides/in-app-docs-authoring.md