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.

1. 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.

2. Next up: Creating encrypted secrets for a repository / Creating encrypted secrets for an organization to create a secret called PROTECTOR_TOKEN.

3. 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 }}

4. Generate a protector.yml file inside .github/. It is also possible to configure the location of your configuration file by passing config (with: { config: "path/to/my/config.yml" }).

   patterns:
     - dev
     - master
   
   allowsDeletions: false
   
   overrides:
     dev:
       requiresLinearHistory: true
     master:
       isAdminEnforced: true
       reviewDismissalActors:
         - @m19c

5. Push the changes.

6. Profit!

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 as pushActors are limited to 100 items.
• reviewDismissalActors and pushActors 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 like v1, v2 and so on. However, protector is only able to match patterns equally.