Branch Protection

An overview of the integration between OpenShift CI and GitHub 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: Required Status context

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: Required absent Status context

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 not override it.
              unmanaged: true

An overview of all available settings and a more detailled 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 proection, please use unmanaged: true instead of protect: false.

Required jobsprotect: stanzaWhat branchprotector doesRequires admin
yesabsentEnforces BP for required jobsyes
yestrueEnforces BP for required jobsyes
yesfalseDoes not touch BP settingsno
noabsentDoes not touch BP settingsno
notrueEnforces BP defined by the configurationyes
nofalseEnforces BP is disabledyes