Introduction to FlagShark
Learn what FlagShark is, how it works, and why automated feature flag management matters for your team.
FlagShark is an automated feature flag management system that integrates with GitHub to detect, track, and help clean up feature flags throughout their lifecycle. It works by analyzing your pull requests to identify when flags are added or removed from your codebase.
What is FlagShark?
Feature flags are powerful tools for controlling feature rollouts, but they come with a hidden cost: technical debt. The vast majority of flags outlive their purpose — they keep evaluating, keep gating dead code paths, and keep growing in number. Over time that adds up to slower builds, harder onboarding, and increasingly tangled conditionals.
FlagShark solves this problem by:
- Automatically detecting feature flags when they're added in pull requests
- Tracking the lifecycle of each flag from creation to removal
- Alerting your team when flags become stale
- Creating cleanup PRs to help you remove dead code
How It Works
FlagShark integrates with your GitHub repositories through a GitHub App. It uses a two-phase architecture:
On a pull request, FlagShark:
- Analyzes the diff to find any feature flag additions or removals
- Posts a preview comment on the PR summarizing what it found
The PR comment is a preview only — flags are not added to your dashboard inventory yet.
When code lands on the default branch (via merge or direct push), FlagShark:
- Detects flag changes from the push diff
- Persists them to inventory — this is when flags appear in your dashboard and lifecycle tracking begins
- Monitors for staleness based on your configured thresholds
When a flag has been in production long enough (configurable per workspace), FlagShark can automatically create a cleanup PR to remove it.
Key Concepts
Feature Flags
A feature flag (also called a feature toggle) is a technique that allows you to enable or disable features in your application without deploying new code. Common use cases include:
- Gradual rollouts - Release features to a percentage of users
- A/B testing - Test different variations with different users
- Kill switches - Quickly disable features if issues arise
- Environment toggles - Enable features only in certain environments
Flag Lifecycle
Every feature flag goes through a lifecycle:
- Created - The flag is added to the codebase
- Active - The flag is being used to control a feature
- Stale - The flag hasn't been modified recently and may be ready for cleanup
- Removed - The flag and its associated code have been cleaned up
FlagShark tracks this entire lifecycle automatically.
Supported Providers
FlagShark auto-detects flags from 13 providers — LaunchDarkly, Unleash, Flipt, Split.io, PostHog, Flagsmith, ConfigCat, Statsig, GrowthBook, DevCycle, Eppo, Optimizely, and a generic/custom provider for in-house flag systems. No configuration needed for the named providers; for custom wrappers see Configuration.
Why Automated Management Matters
Manual feature flag management doesn't scale. As your codebase grows, keeping track of which flags are still needed becomes increasingly difficult. The result?
- Code complexity - Nested conditionals and dead code paths
- Slower onboarding - New developers struggle to understand what's active
- Testing overhead - More code paths mean more test cases
- Performance impact - Unused flag checks still execute
FlagShark automates the tedious parts of flag management so your team can focus on building features, not maintaining flags.
Three Ways to Try It
FlagShark ships three on-ramps. Pick the one that matches what you want right now — they all use the same detection engine, so the results are consistent across them.
1. The CLI — zero friction, no account
npx flagshark scan runs the FlagShark scanner against your local checkout and prints a stale-flag report. Nothing leaves your machine, no signup, no telemetry. The fastest way to find out whether you have a flag debt problem at all.
2. The GitHub Action — in your CI, no account
Drop a workflow file into .github/workflows/. The Action runs the same scanner inside GitHub Actions, posts a comment on every PR, and can fail the build if your flag health drops below a threshold you set.
3. The GitHub App + Dashboard — full SaaS
Install the GitHub App and FlagShark tracks every flag in your repos over time, opens cleanup PRs when flags go stale, and notifies your team. This is the path that gives you continuous lifecycle tracking and automated cleanup.
→ Install the GitHub App, then open a test PR to verify
.flagshark.yml config.