How to choose and enforce a suitable branching strategy for your repository.
As a repository maintainer you are responsible for choosing and enforcing a branching strategy for your repository.
Recommended branching model patterns explained in under 7 minutes!
We recommend you choose one of:
- Reviewed Source : Simple pull request based workflow where expert code maintainers review all changes before release.
- Audited Source : Ensures history is immutable for audit, but changes don’t require approval before release.
- Multiple Team Source : A derivative of GitFlow to provide each team with their own develop branch.
Branch protection is a feature provided by GitHub to apply rules to repository branches. For example to limit those able to push commits to the branch, or enforcing approval rules before merge.
You use branch protection in your repository to enforce your choice of branching strategy for your contributors. There are 3 ways to configure branch protection rules:
- Manually apply per-repository in the GitHub repository settings.
- RECOMMENDED: Configure using the Codebase Governor.
- Automate it yourself via the GitHub API.
Simple Codebase Governor setup instructions for each recommended branching strategy:
Using the Codebase Governor
branch-protections key enables you:
- to specify default rules across all repositories in capability using the
- to specify a particular set of rules for an individual repository using the repository config file.
Branching strategy is a complex topic. Useful further reading is:
- Martin Fowler: Patterns for Managing Source Code Branches
- Atlassian: Comparing Workflows
- GitHub Flow
- GitLab Flow
- Trunk Based Development (DORA)
- A production application uses Reviewed Source.
- A testing tool or docs site uses Audited Source.
- A busy stage 3 inner source repo uses Multiple Team Source.
Read more detailed examples and reasoning on the branching examples page.