Track and Clean Up Feature Flags with Code References
Feature flags are a powerful way to control how users experience your product. But over time, flags that were once useful can become technical debt if they aren't cleaned up properly. That's why we're excited to introduce Code References in Bucketeer, a new feature that helps you track where feature flags are used in your codebase.
Whether you're a developer managing dozens of toggles or an open-source contributor maintaining a large project, Code References gives you the visibility and tools to keep your flags clean, useful, and safe.
Why Code References Matter
Feature flags are meant to be temporary. But in reality, many of them stick around long after they're needed. This can lead to bloated code, confusing logic, and hard-to-debug bugs. Worse, you might disable a flag thinking it's unused, only to find it was still being called in production code.
Code References solves this by:
- Scanning your codebase for usages of feature flags
- Displaying results directly in the dashboard
- Helping you identify unused flags so you can clean them up safely
This makes it easier to follow best practices for the flag lifecycle: create, use, roll out, and eventually remove.
How It Works
Bucketeer Code References is powered by a separate CLI tool that scans your codebase for feature flag usage and reports it back to the Bucketeer dashboard.
1. Set Up the CLI
Download the latest prebuilt binary from the GitHub Releases page. Binaries are available for macOS, Linux, and Windows (including .tar.gz, .deb, and .rpm formats for different architectures).
For example, on macOS (ARM64):
curl -LO https://github.com/bucketeer-io/code-refs/releases/download/v0.0.3/code-refs_0.0.3_darwin_arm64.tar.gz
tar -xzf code-refs_0.0.3_darwin_arm64.tar.gz
chmod +x bucketeer-find-code-refs
Then move the binary to your PATH if desired:
sudo mv bucketeer-find-code-refs /usr/local/bin/
2. Run the Code Reference Scan
Use the CLI to scan your codebase:
bucketeer-find-code-refs \
--apiKey="$YOUR_BUCKETEER_API_KEY_1,$YOUR_BUCKETEER_API_KEY_2" \
--apiEndpoint=$YOUR_BUCKETEER_API_ENDPOINT \
--repoName=$YOUR_REPOSITORY_NAME \
--dir="/path/to/git/repo"
This will:
- Recursively scan the specified directory
- Find all SDK-based feature flag calls
- Upload results to your Bucketeer project
3. View the Results
Go to your Bucketeer dashboard and open the Code References tab in the Feature Flag detail view.
You'll see something like this:
Each usage is shown with the file path, line number, and snippet, giving you confidence that the flag is (or isn't) still active in your code.
Best Practices for Flag Lifecycle
Code References is more than just a scanner, it's a way to build a healthier engineering culture around flags:
- Tag your flags clearly with team or feature names to track ownership and responsibility.
- Encourage your team to regularly use the CLI, especially before major refactors or releases.
- Monitor stale flags – Bucketeer automatically detects flags that haven't received requests for more than 7 days, helping you quickly identify candidates for archiving.
- Check the code references to confirm whether these stale flags are still referenced in your codebase.
- Schedule a cleanup once a flag is confirmed as unused and fully rolled out, removing it safely from your code.
Stale flags slow you down. Code References helps you stay fast and focused.
Final Thoughts
This feature has been one of the most requested by the community, and we're excited to see how it helps teams manage flags more responsibly.
We're also working on integrating Code References with GitHub Actions, so you'll be able to automatically scan your codebase during CI workflows. This means you can catch stale or missing flag references as part of every pull request, making it even easier to maintain clean, flag-aware code.
You can start using Code References today in both Bucketeer Cloud and self-hosted Bucketeer. Check out the docs here.
Happy flagging! 🚀