branch protection as code!
In larger organizations / projects, not everyone can access the configuration of a repository. Therefore, engineers are not able to see and edit the current Branch Protection Rules. This can lead to confusion. Good documentation might reduce the lack of clarity but also requires effort to keep up to date.
Keeping the protection rules as close to the source code as possible clarifies the way how the team actually works.
protector versions are defined as vx.y.z
, where x
is the major version, y
is the minor version, and z
is the patch version, following Semantic Versioning terminology.
To support multiple versions at the same time and also to keep things simple, protector uses release branches for the most recent two major releases. Fixes (e.g. security, bugs etc.) may be backported to those branches.
Version | Status |
---|---|
v1 |
Active |
v2 |
Inactive |
-
To use protector, a custom personal access token with the scopes
repo
and optionally,read:org
, is required. Follow the steps described on Creating a personal access token. -
Next up: Creating encrypted secrets for a repository / Creating encrypted secrets for an organization to create a secret called
PROTECTOR_TOKEN
. -
Create a new workflow file (e.g.
.github/workflows/enforce-protection.yml
).name: protector on: push jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 - uses: m19c/protector@v1 with: token: ${{ secrets.PROTECTOR_TOKEN }}
-
Generate a
protector.yml
file inside.github/
. It is also possible to configure the location of your configuration file by passingconfig
(with: { config: "path/to/my/config.yml" }
).patterns: - dev - master allowsDeletions: false overrides: dev: requiresLinearHistory: true master: isAdminEnforced: true reviewDismissalActors: - @m19c
-
Push the changes.
-
Profit!
Property | Description | Example |
---|---|---|
patterns |
List of patterns to match the actual branches. | ['dev', 'master'] |
... |
Any of RuleSet. | - |
overrides |
Map of RuleSet overrides to be more specific in certain cases. | - |
Property | Type | Description |
---|---|---|
allowsDeletions |
boolean |
Can this branch be deleted. |
allowsForcePushes |
boolean |
Are force pushes allowed on this branch. |
dismissesStaleReviews |
boolean |
Will new commits pushed to matching branches dismiss pull request review approvals. |
isAdminEnforced |
boolean |
Can admins overwrite branch protection. |
requiredApprovingReviewCount |
boolean |
Number of approving reviews required to update matching branches. |
requiresApprovingReviews |
boolean |
Are approving reviews required to update matching branches. |
requiresCodeOwnerReviews |
boolean |
Are reviews from code owners required to update matching branches. |
requiresCommitSignatures |
boolean |
Are commits required to be signed. |
requiresLinearHistory |
boolean |
Are merge commits prohibited from being pushed to this branch. |
restrictsReviewDismissals |
boolean |
Is dismissal of pull request reviews restricted. |
restrictsPushes |
boolean |
Is pushing to matching branches restricted. |
requiredStatusCheckContexts |
boolean |
List of required status check contexts that must pass for commits to be accepted to matching branches. |
requiresStatusChecks |
boolean |
Are status checks required to update matching branches. |
requiresStrictStatusChecks |
Array<string> |
Are branches required to be up to date before merging. |
reviewDismissalActors |
Array<string> |
A list of User (@<username> ) and / or Team (#<team> ) allowed to dismiss pull requests. |
pushActors |
Array<string> |
A list of User (@<username> ) and / or Team (#<team> ) allowed to push to matching branches. |
patterns:
- dev
- staging
- master
allowsDeletions: false
allowsForcePushes: false
dismissesStaleReviews: true
isAdminEnforced: true
requiredApprovingReviewCount: 1
requiresApprovingReviews: true
requiresCodeOwnerReviews: true
requiresCommitSignatures: true
requiresLinearHistory: true
restrictsReviewDismissals: false
restrictsPushes: true
pushActors:
- '#developer'
requiresStatusChecks: true
requiredStatusCheckContexts:
- continuous-integration/jenkins/branch
requiresStrictStatusChecks: true
reviewDismissalActors:
- '#developer'
overrides:
master:
requiredApprovingReviewCount: 2
protector requires both the action itself and a config file. The configuration describes whether or not a branch should be considered and how the branch should be protected.
┌───────────────GITHUB──────────────┐
│ │
│ ┌───────────┐ │
│ │ PROTECTOR │ │
│ │ ACTION │◄────R/W──┐ │
│ └───────────┘ │ │
│ ▲ ▼ │
│ │ ┌─────┐ │
│ │ │ API │ │
│ TRIGGER └─────┘ │
│ │ │
│ │ │
┌────────┐ │ ┌─┴──────────┐ │
│ CHANGE ├───── PUSH───────►│ REPOSITORY │ │
└────────┘ │ └────────────┘ │
│ │
└───────────────────────────────────┘
- Both
reviewDismissalActors
as well aspushActors
are limited to100
items. reviewDismissalActors
andpushActors
can only hold Teams / Users.- Some options are only available for organizations either with or without Team / Enterprise plan.
- Strict pattern checks: GitHub offers dynamic branch matching, for example
v*
will match branches likev1
,v2
and so on. However,protector
is only able to match patterns equally.