Code references currently supports GitHub repositories only. It performs a basic text search across .ts, .tsx, and .go files using the GitHub Search API, it does not parse code or detect semantic usage. Results may include matches inside comments, strings, or unrelated code, and may miss usages in unsupported file types.
|
Code references help you track where feature flags are used in your codebase. CloudBees Unify scans your source code repositories and displays all locations where each flag is referenced, making it easier to understand flag usage and safely remove flags that are no longer needed.
How code references work
When you link components to an application, CloudBees Unify:
-
Connects to each component’s repository (GitHub).
-
Scans each repository for feature flag references.
-
Displays the references found and identifies which repository they are in.
-
Shows the results in the Feature Flag Health dashboard.
Prerequisites
Before viewing code references, the following are required:
| Requirement | Description |
|---|---|
SCM integration |
A configured GitHub integration. Refer to SCM integrations. |
Component(s) |
One or more components created in your organization. Each component is connected to a repository via an SCM integration. Components represent the services, libraries, or modules that contain your feature flag code. Refer to Components. |
Application |
An application that groups components together. Code references scan the repository associated with each linked component. Refer to Manage applications. |
Feature flag |
Create at least one feature flag created in CloudBees Unify. Refer to Create and manage flags in the UI. |
Network access |
Network connectivity between CloudBees Unify and your source code repository (for self-hosted repositories). |
Set up code references
Follow these steps to enable code references for your feature flags:
Step 1: Create or verify your SCM integration
If you have not already done so, create an SCM integration to connect CloudBees Unify to your source code repositories.
-
Navigate to .
-
Select GitHub.
-
Follow the integration setup wizard to authenticate and connect.
-
Verify that your repository appears in the list of available repositories.
Refer to SCM integrations for detailed instructions.
Step 2: Create components
Components represent the logical parts of your application that can be built, deployed, and released independently.
-
Navigate to Components.
-
Select Create component.
-
Select a repository.
The repository’s default organization is pre-selected; you may change it if needed. -
Select Create components.
-
Repeat for each component in your application.
|
Match your component names to the actual services or modules in your codebase. This makes it easier to understand which code reference belongs to which part of your application. |
Refer to Components for more details.
Step 3: Create an application and link components
An application groups components together. CloudBees Unify scans the repository associated with each linked component for code references.
-
Navigate to Applications.
-
Select Create application.
-
Enter an Application name (for example,
E-commerce Platform). -
(Optional) Enter a Description.
-
(Optional) Select Add environment to link environments where your application is deployed.
-
(Optional) Select Add repository to enable workflow orchestration (deployer workflows, staged workflows):
-
Select a repository from the list.
-
Select Add.
The application-level repository link is for workflow orchestration, not code references. Code references scan the repositories linked to each component.
-
-
Select Add component:
-
Select a component from the list.
-
Select Add.
-
Repeat to add all components that contain feature flag code.
-
-
Select Create.
|
Code references require components to be linked to the application.
|
Refer to Manage applications for more details on managing applications.
Step 4: Verify code references appear
After linking components to the application:
-
Navigate to .
-
Select a feature flag that exists in your codebase.
-
Select the Flag health tab.
-
Scroll to the Code References section.
The page displays the following information:
-
A count of references found (for example, "Review affected code (5 references)").
-
Filters for repositories, branches, and file types.
-
A list of files and line numbers where the flag is referenced.
Troubleshooting
No repositories linked to this application
Cause: No components are linked to the application or the components have no connected repositories.
Solution:
-
Navigate to Applications and select your application.
-
Select
and then Edit. -
Select Add component and link components that have repositories connected.
-
Select Save.
-
Verify each component has a repository connected via an SCM integration.
Flag is not referenced in any linked repositories
Possible causes:
-
The flag key in your code does not match the flag key in CloudBees Unify.
-
Component repositories have not been scanned yet (scans may take a few minutes).
-
The flag is not used in the linked components' code.
-
Network connectivity issues prevent CloudBees Unify from accessing component repositories.
Solutions:
-
Verify the flag key matches exactly (case-sensitive).
-
Wait a few minutes and refresh the page to allow scanning to complete.
-
Check that the flag is actually referenced in the component’s codebase:
-
Search your codebase for the flag key.
-
Verify the file is in a repository linked to a component.
-
-
For self-hosted repositories, verify network connectivity between CloudBees Unify and component repositories.
No matching references found (with filters applied)
Cause: Your current filter settings exclude all references.
Solution:
-
Clear or adjust your filters:
-
Repository filter: Select "All" or the specific repository.
-
Branch filter: Select "main" or your default branch.
-
File extension filter: Select "All" or the relevant file types.
-
-
Select Apply filters.
Code references are not updating
Possible causes:
-
The search is encountering errors when accessing the repository.
-
Repository authentication has expired.
-
CloudBees Unify does not have permission to access the repository.
Solutions:
-
Verify your SCM integration is still authenticated:
-
Navigate to .
-
Check the status of your SCM integration.
-
Re-authenticate if needed.
-
-
Check repository permissions:
-
Ensure CloudBees Unify has read access to the repository.
-
Verify the GitHub access token or OAuth app has the required scopes.
-
-
Contact your CloudBees Unify administrator if the issue persists.
Code references appear under the wrong component
Cause: The component linked to the application does not match the actual component using the flag.
Solution:
-
Navigate to Applications and select your application.
-
Select
and then Edit. -
Verify the correct components are linked.
-
Add any missing components using Add component.
-
Select Save.
Best practices
These best practices help ensure code references are accurate and complete.
Organize components by deployment unit
Create components that match how your application is actually deployed:
-
Microservices: One component per service.
-
Monolith: One component for the entire application, or separate components for major modules.
-
Multi-repo: One component per repository, or group related repositories.
This makes code references more meaningful and easier to navigate.
Use consistent flag naming
Use a consistent naming convention for feature flags in your code and in CloudBees Unify:
-
Use the same casing (kebab-case, snake_case, camelCase, etc.).
-
Avoid special characters that might be interpreted differently.
-
Document your naming convention for your team.
Link all relevant repositories
If your feature flags are used across multiple repositories, try one of the following:
-
Create separate applications for each repository.
-
Update your application to link all repositories (if your architecture supports it).
This ensures all code references are discovered.
Review code references before removing flags
Before deleting a feature flag:
-
Check the Code References section in Flag Health.
-
Verify all references have been removed from the codebase.
-
Consider the impact on deployed versions that may still reference the flag.
Code references help you avoid breaking changes when cleaning up old flags.
Next steps
Now that code references are set up:
-
Monitor flag health to track flag status and usage.
-
Review code references regularly to understand flag usage patterns.
-
Use code references to safely clean up unused flags.