Skip to content

m19c/protector

Repository files navigation

protector

branch protection as code!


Motivation

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.

Versioning

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

Getting started

  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!

Configuration

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

RuleSet

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.

Real World Example

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

Development

Workflow

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 │           │
└────────┘       │          └────────────┘           │
                 │                                   │
                 └───────────────────────────────────┘

Known limitations

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