Introduction
Understanding organizationsUnderstanding componentsManage organizationsManage componentsManage component Jira integrations
Set up your first organizationUnderstanding users and teamsUnderstanding role-based access controlManage usersManage teamsConfigure role-based access controlRBAC permissions reference
Understanding authentication in CloudBees UnifySet up multifactor authenticationConfigure SAML single sign-onConfigure OIDC authenticationConfigure network security policiesNetwork security reference
Understanding platform configurationUnderstanding environmentsManage properties and secretsManage environmentsTrack environment inventoryConfigure containersSet up preconfigured actionsConfigure notifications
Accessibility policy referenceShared responsibility model referenceSubscription and services agreementSupport policiesSupported browsers and external tools
Introduction
Understanding feature managementUnderstanding Configuration as CodeGet started with feature managementCreate and manage feature flagsConfigure feature flag targetingOrganize feature flagsImplement feature flag governanceConfiguration as Code reference
Understanding flag impressions and activity statusUnderstanding flag healthUnderstanding code referencesReview and clean up feature flagsSet up code references
Understanding Jira integration for feature flagsSet up the Jira integrationLink Jira tickets to feature flags
Understanding multiple SDK keysBuild your first mobile app with feature flagsBuild your first feature-flagged web applicationBuild your first feature-flagged backend serviceInstall client-side SDKsInstall server-side SDKsConfigure multiple SDK keysMobile SDK referenceWeb SDK referenceBackend SDK referenceClient SDK referenceFlag implementation reference
Introduction
Understanding CI workflowsCreate a build workflowCreate and manage workflowsCreate reusable workflowsTest and validate containers in workflowsCheck out source codeTrigger workflows remotelyWorkflow syntax referenceJobs syntax referenceSteps syntax referenceServices syntax reference
Monitor workflow runsView test results in runsView evidence in runsView deployments in runsManage workflow artifactsPublish test resultsPublish evidence itemsGenerate a software bill of materialsManage ServiceNow change requests
Configure workflow credentialsConfigure AWS credentialsConfigure container registry credentialsConfigure Git credentialsIntegrate external secret providers
Understanding GitHub Actions integrationSet up GitHub Actions integrationDisplay GitHub Actions workflows and runsRegister GHA build artifactsPublish GHA deployed artifactsPublish GHA test resultsPublish GHA evidence itemsTrigger CloudBees workflows from GitHub ActionsScan with GitHub Actions
Understanding CloudBees CI and Jenkins® integrationConnect CI and Jenkins controllersMonitor CI and Jenkins buildsRegister CI build artifactsRegister CI deployed artifactsPublish CI test resultsConfigure CI security scanningCI and Jenkins integration reference
Build and publish container imagesUnderstanding external CI/CD integrationsRun external CI/CD jobsExternal CI/CD action reference
Introduction
Understanding release orchestrationManage applicationsCreate deployer workflowsCreate staged workflowsCreate and manage releasesOrchestrate multi-workflow releasesRelease management reference
Understanding artifact managementRegister and track artifactsStore and retrieve artifactsPromote artifactsGenerate a software bill of materialsArtifact management reference
Deploy with HelmDeploy to KubernetesContainer deployment reference
Deploy to AWSAWS deployment reference
Deploy with enterprise platformsExecute remote deployment commandsEnterprise deployment reference
Verify deployments with New RelicDeployment verification reference

Implement feature flag governance

9 minute read

Establish approval workflows, custom roles, and audit tracking to ensure feature flag changes follow organizational governance requirements and maintain accountability across teams.

Governance becomes essential when feature flags affect production environments, require regulatory compliance, or need structured review processes.

Prerequisites

Before implementing governance, ensure you have:

  • Administrative access to CloudBees Unify for role and permission management.

  • Understanding of your team structure and approval workflows.

  • Feature flags created that require governance oversight.

  • Email access for approval notifications.

Set up custom roles for feature management

CloudBees Unify includes predefined roles (Admin, User, and Approver) that grant broad, platform-wide permissions across all capability areas, including feature management. These roles 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.

Feature management permissions

Creating flags, managing target groups, and submitting approval requests are controlled by specific permissions grouped into four categories. Depending on the flag behavior, the required permissions may apply at the application level, the environment level, or both.

Table 1. Permission categories and associated permissions
Category Possible permissions What the permission allows

Approval requests

Create, Update, Delete

Submit, approve, or reject feature flag approval requests.

Custom property

Create, Update, Delete

Define and manage custom properties used in flag targeting rules.

Flags

Create, Update, Delete

Manage feature flags, including creating, updating, and deleting.

Target groups

Create, Update, Delete

Manage target groups at the application level.

No environment-level target group permission exists. However, if a target group is used in flags, Flag: Update is required on the application and in each environment where the group is used.

Feature management permission levels

Permissions for feature management are assigned at the category level, using one or more permission levels.

Table 2. Permission levels for feature management
Level Description

Read

Grants read access to feature management entities (flags, target groups, and custom properties). Granted to all users by default.

Create

Allows users to create new flags, target groups, approval requests, or custom properties.

Update

Allows users to edit an entity. For example, to update a flag’s configuration or target group conditions.

For approval requests, Update is required to approve a request. To reject or delete a request, use Delete.

Delete

Permits users to delete a flag, target group, or custom property. Also required to reject or delete an approval request.

Execute

While Execute can be selected in the UI, it is not used in feature management.

Permission evaluation

When a user attempts to perform a task, such as editing a flag, CloudBees Unify evaluates the user’s assigned roles, permission levels within the categories, and 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: Update at the application level.

  • Flags: Update for the application level and each environment where the flag uses the group.

Create a custom role

To create a custom role and assign permissions:

To create the role:

  1. Navigate to Tenant settings  Roles.

  2. Select Create role.

  3. To name the role:

    1. Select Pencil next to Custom role, and then enter a name for the role.

    2. Select Pencil next to Description to enter a description, such as a summary of permissions granted.

  4. 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.

  5. Apply the appropriate permissions.

  6. Select Save.

  7. Assign users or teams to the new custom role.

    • To grant the role, navigate to Admin settings  Tenant settings  Access control.

    • 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).

Role tutorials

The following 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 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 predefined System Admin role in CloudBees Unify 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, 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, assigned to a team named App2Admins at both the application and environment levels.

To create the role:

  1. Navigate to Tenant settings  Roles.

  2. Select Create role.

  3. To name the role:

    1. Select Pencil next to Custom role, and then enter a name for the role.

    2. Select Pencil next to Description to enter a description, such as a summary of permissions granted.

  4. Select the Feature management category.

  5. Apply the required permissions:

    • Approval request: Create to propose a request, Update to approve a request, Delete to reject or delete a request.

    • Flags: Create, Update, and Delete to create, update, and manage flag settings.

    • Target group: Create, Update, and Delete to manage audience targeting groups.

    • Custom property: Create, Update, and Delete to manage flag rule conditions and context-based targeting.

  6. Select Save.

  7. To grant the role, navigate to Admin settings  Tenant settings  Access control.

  8. Select Team as the principal type.

  9. Select the App2Admins team.

  10. Select the first resource type Application.

  11. Select the application name, app-1.

  12. Select the role fm-admin-custom-role.

  13. Repeat to assign the role to application app-2 and environment 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

This example creates a custom role that allows a user 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 App1Admins. As a member of that team, the user automatically inherits the team’s permissions.

Create a custom role named fm-approver-custom-role:

To create the role:

  1. Navigate to Tenant settings  Roles.

  2. Select Create role.

  3. To name the role:

    1. Select Pencil next to Custom role, and then enter a name for the role.

    2. Select Pencil next to Description to enter a description, such as a summary of permissions granted.

  4. Select the Feature management category.

  5. Assign the following permissions:

    • Approval request: Read, Create, Update, and Delete.

    • Custom property: Read.

    • Flag: Read.

    • Target group: Read.

      For minimum permissions:

      • Update is required to approve a request.

      • Delete is required to reject or delete a request.

      CloudBees recommends assigning only the minimal permissions necessary for each user’s responsibility.

  6. Select Save.

  7. To grant the role, navigate to Admin settings  Tenant settings  Access control.

  8. Select Team as the principal type.

  9. Select the App1Admins team.

  10. Select the first resource type Application.

  11. Select the application name, app-1.

  12. Select the role fm-approver-custom-role.

  13. Repeat to assign the role to environment env-1.

    By assigning the role to App1Admins 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. 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:

  1. Navigate to Tenant settings  Roles.

  2. Select Create role.

  3. To name the role:

    1. Select Pencil next to Custom role, and then enter a name for the role.

    2. Select Pencil next to Description to enter a description, such as a summary of permissions granted.

  4. Select the Feature management category.

  5. Assign the following permissions:

    • Approval request: Read.

    • Custom property: Read.

    • Flag: Read, Create, Update, and Delete.

    • Target group: Read.

  1. Select Save.

  2. To grant the role, navigate to Admin settings  Tenant settings  Access control.

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.

Table 3. Permissions to make a change to a flag and submit it for approval
Role Feature management role permissions Can propose approval? Can approve/reject? Can edit flag configuration?

Flag change requester

Approval request: Read, Create
Flag: Read, Create

To create the role:

  1. Navigate to Tenant settings  Roles.

  2. Select Create role.

  3. To name the role:

    1. Select Pencil next to Custom role, and then enter a name for the role.

    2. Select Pencil next to Description to enter a description, such as a summary of permissions granted.

  4. Select the Feature management category.

  5. Assign the following permissions:

    • Approval request: Read, Create.

    • Flag: Read, Create.

  1. Select Save.

  2. To grant the role, navigate to Admin settings  Tenant settings  Access control.

This completes the steps to create a custom feature flag contributor role.

Configure approval workflows

Implement structured review processes for feature flag changes.

Submit approval requests

Create approval requests for flag changes that require review:

  1. Navigate to Feature management and select your application.

  2. Select the flag requiring configuration changes.

  3. Make the desired configuration modifications using the standard configuration interface.

  4. Instead of saving directly, select Request approval.

  5. In the approval request dialog:

    1. Add a descriptive comment explaining the proposed changes and their purpose.

    2. Review the change summary to ensure accuracy.

    3. Select Submit request.

After submission: - The flag configuration becomes locked for editing in the target environment. - A diff view displays current configuration versus proposed changes. - Email notifications are sent to users with approval permissions. - Only the requester can withdraw the request before approval.

Manage approval requests as a reviewer

Review and process incoming approval requests:

  1. Receive notification: Check email for approval request notifications containing flag change details and review links.

  2. Accept review: Select Respond to request in the email notification to accept the review responsibility.

    • The requester receives confirmation that you’ve accepted the review.

    • You can view the proposed changes in the CloudBees Unify interface.

  3. Review changes: Navigate to the flag configuration page to examine:

    • Current configuration (top section of diff view)

    • Proposed changes (bottom section of diff view)

    • Requester’s comments and change rationale

  4. Make approval decision: Select Review approval request and choose:

    • Approve: Apply the proposed changes immediately to the flag configuration.

    • Reject: Decline the changes and notify the requester with feedback.

  5. Provide feedback: Add comments explaining approval or rejection reasoning to help requesters understand decision criteria.

Best practices for approval workflows

Design effective governance processes:

  • Define approval criteria: Establish clear guidelines for when approval is required versus optional.

  • Set reviewer responsibilities: Assign specific reviewers for different flag categories or environments.

  • Document change rationale: Require meaningful descriptions in approval requests to support audit and compliance.

  • Establish response timeframes: Set expectations for approval request response times to avoid blocking development work.

  • Coordinate with deployment processes: Align flag approvals with application deployment schedules and change windows.

Track changes with audit history

Monitor and review all feature flag modifications for compliance and troubleshooting purposes.

Access audit history

Review historical changes across feature management entities.

Changes to application or environment names are not currently captured in audit history, even though this information is displayed in flag entity change records. For example, if an environment name changes, flag entity change records reflect the new environment name, but there is no dedicated environment record indicating when the name change occurred.

  1. Navigate to your organization and select Audit history.

  2. Use filtering options to focus on relevant changes:

    • Application: Filter by specific application.

    • Entity type: Choose flags, target groups, or custom properties.

    • Entity name: Search for specific flag or entity names.

    • Environment: Filter by deployment environment.

    • Date range: Select time periods (last 7 days, 30 days, or custom range).

      You cannot filter the audit history display by organization.

Review audit records

Examine detailed change information:

  1. Locate the relevant audit record in the filtered list.

  2. Select View details to expand the audit record.

  3. Review the side-by-side comparison showing:

    • Before state: Original configuration or settings

    • After state: Modified configuration or settings

    • Change metadata: Timestamp, user, and change type

    • Context information: Application and environment details

Use audit data for governance

Leverage audit history for compliance and operational needs:

Compliance reporting: Generate reports showing all changes within specific timeframes for regulatory requirements.

Change analysis: Investigate configuration drift or unexpected behavior by reviewing recent flag modifications.

Team accountability: Track which team members made specific changes to support responsibility and training needs.

Pattern identification: Analyze change frequency and types to identify improvement opportunities in governance processes.

Incident response: Use audit trails to understand the sequence of changes leading to production issues.

Integrate governance with development workflows

Align feature flag governance with existing development and deployment processes.

Coordinate with CI/CD pipelines

Integrate flag approvals with deployment workflows:

  • Pre-deployment reviews: Require flag configuration approvals before major releases.

  • Environment promotion: Use audit history to verify flag consistency across environments.

  • Rollback procedures: Document flag state changes to support rapid rollback during incidents.

Establish change management processes

Create structured approaches for flag lifecycle management:

  • Flag creation standards: Define naming conventions and required documentation for new flags.

  • Configuration change procedures: Establish when approval is mandatory versus optional.

  • Cleanup governance: Use audit history and permissions to coordinate flag removal after feature completion.

  • Emergency procedures: Define expedited approval processes for critical production issues.

Monitor governance effectiveness

Track and improve your governance implementation:

  • Approval metrics: Monitor approval request volume, response times, and approval rates.

  • Audit coverage: Ensure all critical changes are properly tracked and reviewed.

  • Process compliance: Regular review whether teams follow established governance procedures.

  • Training needs: Use audit patterns to identify areas where additional team training is needed.

Related pages

Organize feature flags
Configuration as Code reference