Branch Protection
Why protecting your main branch is essential for FlagShark to work effectively and how to configure it.
Branch protection rules are a critical part of using FlagShark effectively. By requiring pull requests for all changes to your main branch, you ensure that every feature flag change is tracked, reviewed, and documented.
Why Branch Protection Matters
FlagShark monitors your repositories by watching pull request events. When you push directly to your main branch, FlagShark has no way to:
- Detect new feature flags being added
- Track when flags are removed
- Provide PR comments with flag summaries
- Create automated cleanup PRs
Setting Up Branch Protection
GitHub Branch Protection Rules
main (or your default branch name) as the branch name patternScreenshot needed: The branch protection settings page showing 'Require a pull request before merging' enabled for the main branchGitHub Settings → Branch protection rules
Recommended Settings
For most teams using FlagShark, we recommend:
| Setting | Recommendation | Why |
|---|---|---|
| Require pull request | Required | Essential for FlagShark tracking |
| Require approvals | 1-2 reviewers | Ensures flag changes are reviewed |
| Dismiss stale reviews | Enabled | Re-review if code changes after approval |
| Require status checks | Enabled | Ensure CI passes before merge |
| Include administrators | Enabled | No bypass for anyone |
What Happens Without Branch Protection
Without branch protection, you might encounter these issues:
Untracked Flag Additions
When someone pushes a new feature flag directly to main:
// This flag won't be tracked by FlagShark
const isNewFeature = ldClient.variation('new-feature-flag', user, false);
The flag won't appear in your dashboard, and you'll have no record of when or why it was added.
Ghost Flags in Your Codebase
If flags are removed via direct push, FlagShark still thinks they exist. You'll see "stale" flags in your dashboard that have actually been removed.
Broken Cleanup PRs
FlagShark creates automated cleanup PRs based on its knowledge of your flags. If that knowledge is out of sync with your actual code, cleanup PRs may fail or make incorrect changes.
Working with Branch Protection
For Individual Contributors
When branch protection is enabled:
git checkout -b feature/my-featuregit push -u origin feature/my-featureFor Urgent Fixes
Even urgent hotfixes should go through PRs. If you need to move quickly:
hotfix labelExceptions and Edge Cases
Automated Commits
Some tools (like dependabot or automated formatters) may need to commit directly. Configure these to:
- Open PRs instead of direct commits when possible
- Be excluded from branch protection if absolutely necessary (not recommended)
Initial Repository Setup
When first setting up a repository, you may need to push initial commits directly. Enable branch protection after your initial setup is complete.
Monorepos
If you're using a monorepo, consider whether you need FlagShark tracking on all paths or just specific directories. Branch protection should still apply to ensure consistent tracking.
Verifying Your Setup
To confirm branch protection is working:
Related Documentation
- Pull Request Workflow - Best practices for PRs with feature flags
- Connecting Repositories - Initial repository setup
- Common Issues - Troubleshooting tracking issues