Branch Protection

What Is Branch Protection?

Branch protection is a repository setting that enforces certain rules when trying to merge to a protected branch. See the GitHub documentation for more details.

What Do We Use It For?

We use it to enforce that mandatory jobs succeed before allowing a merge. These jobs are marked as Required in their GitHub status context. Sample:

If you open a new Pull Request to a branch that has required jobs, these jobs will initially be marked as Required - Context Expected. Sample:

This status is generated by GitHub and means that Prow didn’t report the job as running yet.

Additionally, the branch protection settings are interpreted by the merge automation tide in order to determine if jobs that are not managed by Prow should be considered merge blocking.

How Do We Set up Branch Protection?

Branch Protection requires no manual set-up for repositories with presubmit jobs. When a mandatory presubmit job is added or removed from a repository, automation will ensure that the GitHub Branch Protection settings are updated as well.

Branch protection is configured by a job that runs periodically every six hours. You can see here when it last ran. The implication of this is that when you add/remove a mandatory job, it may take up to six hours for this change to show up in GitHub.

The openshift-merge-robot that configures the branch protection needs admin permissions.

Is It Possible to Disable the Branch Protection for My Repository or Require Jobs That Are Not Managed by Prow?

Yes, these settings are configured in the Prow config.

The basic structure looks like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

branch-protection:
  orgs:
    << org >>:
      repos:
        << repo >>:
          # Protect all branches
          protect: true
          # This external check must pass before merging is allowed
          required_status_checks:
            contexts:
            - my-other-ci-system
          branches:
            << branch >>:
              # Do not protect this branch. This setting can be set
              # for the org, repo or branch. Set it at the highest level
              # that makes sense. Lower levels can override it.
              unmanaged: true

An overview of all available settings and a more detailed explanation can be found in the upstream documentation.

Notes on protect: false

Unfortunately, setting up protect: false may have unexpected effects because of how it interacts with Prow jobs required for merges. OpenShift CI is by default configured to enforce branch protection for all branches that have at least one required Prow job. If protect: false is configured for such a branch, branchprotector will not manage its branch protection settings. However, if there is not a required Prow job on a branch, protect: false causes branchprotector to ensure the branch protection is disabled on the branch (and therefore, the openshift-merge-robot account needs the admin permissions that are necessary for this operation).

If your goal is to not have Prow manage the branch protection, please use unmanaged: true instead of protect: false.