Namespaces and labels

CloudBees feature management uses namespaces and labels to help you manage and organize feature flags at scale. These tools improve visibility, control, and collaboration across teams.

Namespaces are used to group feature flags logically by teams, applications, or services. They help you structure feature flag implementations and prevent naming collisions across different parts of your organization. Namespaces are typically used in configuration and access control scenarios.
Labels provide a flexible way to categorize feature flags across different namespaces. They are commonly used to filter, sort, and group flags based on characteristics like environment, feature status, project, or team. Labels are especially useful in dashboards, analytics, and reporting.

This guide explains when and how to use namespaces and labels, and how using both can enhance clarity, reduce operational overhead, and support scalable flag management across your organization.

What is a namespace?

In CloudBees feature management, a namespace is a logical grouping of feature flags based on a naming convention; it is not a distinct field in the UI. While you do not explicitly set a namespace when creating a flag, you can enforce namespacing by using consistent, prefixed naming patterns in the flag name itself.

For example:

checkout.enableDiscounts
auth.enable2FA
user.profileRedesign

In these examples, checkout, auth, and user act as logical namespaces. They reflect organizational structures such as product areas, services, or responsible teams. This practice helps your team:

Organize feature flags: Group related flags by module, service, or feature domain.
Avoid naming conflicts: Prevent duplicate or confusing flag names across teams.
Improve clarity and ownership: Make it immediately clear which area or team owns which flags.

While namespaces are not a distinct field in the UI, they are essential in the SDKs and APIs. CloudBees feature management SDKs register containers using a namespace and support operations such as freezing, unfreezing, and scoping feature flag evaluations at the namespace level. Use consistent, prefixed naming when registering flags in the SDK.

For example, checkout can be used as the namespace when registering the container, and enableDiscounts as the flag name, resulting in a fully qualified flag name checkout.enableDiscounts that appears in the UI. This approach allows you to logically group flags and take advantage of SDK-level namespace management.

When to use namespaces

Use namespaces when you need to:

Structure your system modularly: For example, by service using billing,enableCoupons, or feature area using search.enableAutocomplete.
Assign ownership: Designating team-specific flags with consistent prefixes. For example, teamA.
Manage access or governance: By aligning naming conventions with access controls (especially relevant in audit or compliance-driven environments).

Namespaces form the foundation for organizing flags within job workflows and SDKs, while labels (covered in the next section) provide a flexible layer for filtering, reporting, and cross-cutting categorization.

What is a label?

In CloudBees feature management, a label is metadata you can apply to a feature flag to help categorize, filter, and analyze it across projects, teams, and environments. Unlike namespaces, which are part of the flag’s name, labels are a structured field that you can manage directly in the user interface.

Labels are used exclusively within the CloudBees feature management UI and backend for organizing, filtering, and analyzing feature flags. They are not referenced or utilized by SDKs during runtime execution.

Labels are especially useful for organizing flags in dashboards, segmenting them for reporting or analytics, and creating cross-functional views across services, modules, or development phases.

Key benefits of labels

Using labels offers several benefits including:

Flexible categorization: Label flags by team, project, feature type, release phase, or environment.
Better visibility: Search, filter, and group feature flags by label in the UI.
Enhanced reporting: Use labels to segment metrics and dashboards for performance tracking and adoption analysis.
Dynamic organization: Reassign or update labels without changing flag keys or altering workflows.

When to use labels

Use labels when you need to:

Group flags by purpose or lifecycle stage. For example, beta, deprecated, or production.
Organize flags by feature type. For example, qa, backend, or payments.
Analyze metrics in dashboards. For example, view results only for flags with the label experimental.
Align flags with team or functional ownership. For example, Team:Platform, Team:Mobile.

Labels complement namespaces by providing a flexible and searchable method to organize flags outside of structural naming conventions. While namespaces define the scope and organizational structure, labels enable rich, dynamic grouping for insights, reporting, and operational clarity.