CloudBees platform includes predefined roles (Admin, User, and Approver) that grant broad, platform-wide permissions across all capability areas, including feature management. These roles are intended for general use but may be either too permissive or too restrictive for specific feature flag work.
To support more precise access control, you can create custom roles specific to feature management. Custom roles allow you to assign permissions based on team responsibilities, such as creating flags, managing target groups, submitting approval requests, or deploying changes.
In feature management, permissions are evaluated at both the application and environment levels. To manage feature flags or related resources, users must have the required permissions in both scopes.
Feature management permissions
Creating flags, managing target groups, and submitting approval requests, are controlled by specific permissions grouped into four categories as shown in the table below. Depending on the flag behavior, the required permissions may apply at the application level, the environment level, or both.
| Category | Possible permissions | What the permission allows | ||
|---|---|---|---|---|
Approval requests |
|
Submit, approve, or reject feature flag approval requests. |
||
Custom property |
|
Define and manage custom properties used in flag targeting rules. |
||
Flags |
|
Manage feature flags, including creating, updating, and deleting. |
||
Target groups |
|
Manage target groups at the application level.
|
Feature management permission levels
Permissions for feature management are assigned at the category level, using one or more permission levels.
| Level | Description | ||
|---|---|---|---|
|
Grants read access to feature management entities (flags, target groups, and custom properties). Granted to all users by default. |
||
|
Allows users to create new flags, target groups, approval requests, or custom properties. |
||
|
Allows users to edit an entity. For example, to update a flag’s configuration or target group conditions.
|
||
|
Permits users to delete a flag, target group, or custom property. Also required to reject or delete an approval request. |
||
|
While |
Quickstart example to create a custom role
The following steps explain how to create a custom role and assign permissions.
To create the role:
-
Navigate to .
-
Select Create role.
-
To name the role:
-
Select
next to Custom role, and then enter a name for the role. -
Select
next to Description to enter a description, such as a summary of permissions granted.
-
-
Select the Feature management category.
The Feature management section on the Custom Role page includes four categories of features possibly needing permissions, and varying permission levels.
Figure 1. Custom role permissions user interface -
Apply the appropriate permissions.
-
Select Save.
-
Assign users or teams to the new custom role.
-
To grant the role, go to .
-
Once the permissions are applied to the custom role, you must assign the role to a user or team, and specify the scope (organization, application, or environment).
-
Permission evaluation
When a user attempts to perform a task, such as editing a flag, CloudBees platform evaluates the user’s:
-
Assigned roles.
-
Permission levels within the categories.
-
Role scopes at both the application and environment levels.
To proceed successfully, the user must hold the necessary permission at both scopes. If any required permission is missing at either level, the request is denied.
For example, when a target group is referenced by a flag in an environment, modifying that group requires the following:
-
Target groups:
Updateat the application level. -
Flags:
Updatefor:-
The application level
-
Each environment where the flag uses the group.
-
Tutorials
These tutorials provide step-by-step instructions to create fully-configured custom roles for two common feature management personas: an administrator and an approver.
Each example guides you through creating the role, applying the principle of least privilege by assigning only the necessary permissions, and granting the role to a team for a specific application or environment scope.
| Although these tutorials (and the example use cases below) explain how to assign a team to the new roles, you can also assign roles directly to individual users if needed. |
Create an administrator role for feature management
By default, the pre-defined System Admin role in CloudBees platform grants full administrative access platform-wide and cannot be restricted to a specific capability area such as feature management.
To enforce the principle of least privilege and improve security, you can create a custom admin role specifically for feature management to limit administrative access to only those capabilities associated with feature flags.
This example creates a custom role named fm-admin-custom-role with full feature management permissions. It is assigned to a team, App2Admins, at both the application and environment levels.
To create the role:
-
Navigate to .
-
Select Create role.
-
To name the role:
-
Select
next to Custom role, and then enter a name for the role. -
Select
next to Description to enter a description, such as a summary of permissions granted.
-
-
Select the Feature management category.
-
Apply the required permissions as shown in this example:
-
Approval request:
-
Createto propose a request. -
Updateto approve a request. -
Deleteto reject or delete a request.
-
-
Flags:
-
Create,Update, andDeleteto create, update, and manage flag settings.
-
-
Target group:
-
Create,Update, andDeleteto manage audience targeting groups.
-
-
Custom property:
-
Create,Update, andDeleteto manage flag rule conditions and context-based targeting.
Figure 2. Feature management administrator custom role
-
-
-
Select Save.
-
To grant the role, go to .
Figure 3. Grant the new role to a team, and multiple scopes -
Select Team as the principal type.
-
Select the App2Admins team as the team to which users who approve flag changes belong to.
-
Select the first resource type Application.
-
Select the application name, app-1.
-
Select the role fm-admin-custom-role that holds the permissions.
-
Perform the same steps to assign the role to another application, app-2.
-
Perform the same steps to assign the role to the environment env-1.
The custom role fm-admin-custom-role, which includes permissions to fully manage feature flags, is assigned to the team App2Admins rather than directly to individual users.
To ensure permissions apply in the correct scope, the role is granted to App2Admins in the following resources:
-
The application scope for app-1
-
The application scope for app-2
-
The environment scope for env-1
By assigning the role to the team in both scopes, all members of App2Admins, including any newly added team members, automatically inherit the necessary permissions to manage all aspects of feature flags.
-
This completes the steps to create a custom feature management administrator role.
Define a feature flag approver role
In this example, the goal is for a new employee to be able to create, approve, and reject approval requests for feature flags in app-1, specifically in the env-1 environment.
Instead of assigning permissions directly to the user, the recommended approach is to assign the permissions to a team, such as the App1Admins team. As a member of that team, they will automatically inherit the team’s permissions.
First, create a custom role with the necessary permissions. For this example, the name of the role is: fm-approver-custom-role:
To create the role:
-
Navigate to .
-
Select Create role.
-
To name the role:
-
Select
next to Custom role, and then enter a name for the role. -
Select
next to Description to enter a description, such as a summary of permissions granted.
-
-
Select the Feature management category.
-
Assign the following permissions:
-
Approval request:
Read,Create,Update, andDelete -
Custom property:
Read -
Flag:
Read -
Target group:
Read
Figure 4. Example custom role: Flag approver roleFor minimum permissions:
-
Updateis required to approve a request. -
Deleteis required to reject or delete a request.
CloudBees recommends assigning only the minimal permissions necessary for each user’s responsibility.
-
-
-
Select Save.
-
To grant the role, go to .
Figure 5. Example granting the new role to a team, and both scopes -
Select Team as the principal type.
-
Select the App1Admins team as the team to which users who approve flag changes belong to.
-
Select the first resource type Application.
-
Select the application name, app-1.
-
Select the role fm-approver-custom-role that holds the permissions.
-
Perform the same steps to assign the role to the environment env-1.
To ensure permissions apply in the correct scope, the role is granted to App1Admins in both of the following resources:
-
The application scope for app-1
-
The environment scope for env-1
-
By assigning the new custom fm-approver-custom-role to the App1Admin team in both scopes, all members of App1Admins, including any newly added team members, automatically inherit the necessary permissions to approve flag changes in that application and environment.
This completes the steps to create a custom feature flag approver role.
Example use cases
The following use cases provide permission templates for common feature management roles. Unlike the step-by-step tutorials, these examples focus on the "why" and "what" of each role’s permissions. Use them as a starting point to design custom roles that fit your organization’s specific needs.
Use case: Flag owner custom role
Use this role for users who are responsible for creating, managing, and deploying feature flags, but who do not need full access to approval requests, target groups, or custom properties.
To create the role:
-
Navigate to .
-
Select Create role.
-
To name the role:
-
Select
next to Custom role, and then enter a name for the role. -
Select
next to Description to enter a description, such as a summary of permissions granted.
-
-
Select the Feature management category.
-
Assign the following permissions:
-
Approval request:
Read -
Custom property:
Read -
Flag:
Read,Create,Update, andDelete -
Target group:
Read
Figure 6. Example flag owner custom role
-
-
Select Save.
-
To grant the role, go to .
This completes the steps to create a custom feature flag owner role.
Use case: Flag contributor custom role
Use this role if you want users to draft feature flag changes without the ability to save them directly. This is useful for developers or team members who need to suggest flag edits but should not have permission to apply changes.
| Role | Feature management, Role permissions | Can propose approval? | Can approve/reject? | Can edit flag configuration? |
|---|---|---|---|---|
Flag change requester |
Approval request: |
To create the role:
-
Navigate to .
-
Select Create role.
-
To name the role:
-
Select
next to Custom role, and then enter a name for the role. -
Select
next to Description to enter a description, such as a summary of permissions granted.
-
-
Select the Feature management category.
-
Assign the following permissions:
-
Approval request:
Read,Create -
Custom property: N/A
-
Flag:
Read,Create -
Target group: N/A
-
-
Select Save.
-
To grant the role, go to .
This completes the steps to create a custom feature flag contributor role.