Create/manage flags in the UI

Feature flags enable software development teams to progressively toggle features on and off for certain segments of users. Flags are defined as Boolean, number, or string type. Create flags in either the UI or in your code.

Flag settings

Flag names are case-sensitive, and must exactly match in both the source code and the platform UI to be the same flag. The flag name and the flag data type are required settings and not editable.

Table 1. Flag settings apply to a flag in all environments.
Flag setting	Definition	Required?	Editable?
Name	The flag name.
Description	Any descriptive information about the flag.
Type	The flag type: Boolean, string, or number.
Variation (string or number flags only)	One or more possible predefined flag values. Each value must be the appropriate type. For example, the string value `test` is a variation for a string flag, and `234` is a variation for a number flag.
Label	A way of organizing flags. For example, tag all flags administered by a specific developer team with the same label.
Mark as permanent	Set a flag, for example, a timeout or URL flag, to permanent status to ignore its impression data.

Access the flags overview

Display the flag list for an organization or sub-organization, the top-level resource in feature management.

To display the flag list for all environments, select Feature management from the left pane.

Flag configurations are environment-dependent. For more information, refer to how flags relate to environments.

Figure 1. Flag overview with available options.

In the flag list example above, the following options are available:

Select CREATE FLAG to create a new flag in the current environment.
Select to copy the SDK key.

Your SDK key is a unique environment identifier.
Filter flags according to multiple criteria.
Select an Environment from the options to display flag details for that environment.
Search for flags by entering all or part of a flag name into Search.
Select to display cleanup candidates. The number of available cleanup candidates is displayed per total number of flags.
Any active filtering is displayed. Select to remove a specific active filter, or select Clear all to remove all filters.
Select on a specific flag to perform editing, configuration, or deletion.

Select

next to a heading to sort ascending or descending, respectively, on that heading.

Filter flag lists

Filter flags in an environment according to the following criteria:

Table 2. Feature flag filters
Filter	Possible options	Reference
Configuration status	Off On	Configure feature flags
Flag type	Boolean Number String	Create flags in the UI
Label	Any existing label	Flag settings
Source	Original Inherited	How flags relate to environments
Namespace	Any existing namespace	Create flags in code
Activity status	Setup Active Stale Inactive Permanent	Flag impressions and activity status

To filter flags:

Select Filter. Each of the separate filters is displayed.
For one or more filters, select an option. Refer to the table above for more information.

The flags are displayed according to the filtering criteria.

Figure 2. Filtering on status, label, source, and activity, with Filter highlighted.

Create a flag in the UI

A created flag is available across all environments of the top-level resource (the organization or sub-organization) in which it is created.

Once you create a flag, you cannot edit its name or its data type.

To create a flag:

Select Feature management from the left pane.
Select Create flag.
Enter a flag Name.
(Optional) Enter a Description.
Select a Type from the options.
(Optional, for string and number flags only) Define variations, as follows:
1. Select Define variations.
2. Select Add variation.
3. Enter a value of the appropriate data type for your flag.
4. (Optional) Select Add variation to enter another value.
  
  You may enter unlimited variations.
  
  Figure 3. Creating a flag, with variations highlighted.
(Optional) Enter any Labels.
Select Save.

Your flag is created, and listed in Feature management. Enable the flag configuration by turning the configuration status to On.

Create a flag in code

Create a flag in your source code and run your application. Your newly created flag is displayed in the platform feature management flag list. Refer to Create flags in code to learn more.

Update an optional flag setting

Add to, remove, or edit any optional flag setting.

To update optional flag settings:

Select Feature management from the left pane.
Select next to the flag you want to edit.
Select Edit.
Update the Description, any variations, or any Labels.
Select the next to a variation to remove it, or delete all variations at once by selecting Define variations.

Remove a label from a flag by selecting the "X" next to the label name.
Select Update.

The optional flag setting(s) is updated accordingly.

Delete a flag

To delete a feature flag, you must first turn off its configuration in all environments. A deleted flag is completely removed from the CloudBees platform, including all environments, and deletion is irreversible.

The flag activity status informs users of the flag lifecycle across all environments, helping them make an informed deletion choice.

Select Show cleanup candidates in the Flags dashboard to display all flags with stale or inactive status. These flags are often a good choice for deletion.

To delete a flag:

Select Feature management from the left pane.
Select next to the flag you want to delete.
Select Delete.
Select the toggle next to the flag to disable the flag configuration for all environments.

Figure 4. Selecting the highlighted toggle disables a flag configuration.
Select Delete.

The selected flag is deleted and removed from the flag list.

Filter stale and inactive flags

You can filter stale and inactive flags, known as cleanup candidates, within any environment. Cleaning up these flags by deletion often reduces tech debt. The number of candidates per total flags is listed next to the filter.

To filter cleanup candidates:

Select Feature management from the left pane.
Select Show cleanup candidates to the right of Search.

The list of flags is filtered for only those with Stale or Inactive activity status.