Rulesets or branch protection rules¶

GitHub offers two mechanisms to protect branches: branch protection rules and rulesets. Both are supported by GitHub and by otterdog. GitHub describes rulesets as a more flexible way to manage protections and provides a tool to convert branch protection rules to rulesets, but branch protection rules are not deprecated. Tag protection rules, on the other hand, have been retired by GitHub and replaced by tag rulesets, see Protecting tags and releases.

This guide compares both mechanisms and lists what otterdog supports. To migrate existing rules, see Migrating to rulesets.

Comparison¶

See About rulesets and About protected branches for a complete description.

Rulesets can protect the same branch several times, e.g. an organization ruleset defines a common baseline and a repository ruleset adds the checks of the repository:

orgs.newOrg('my-project', 'my-org') {
  settings+: {
    plan: "enterprise", // (1)!
  },
  rulesets+: [
    orgs.newOrgRuleset('baseline') {
      include_repo_names+: [
        "~ALL",
      ],
      include_refs+: [
        "~DEFAULT_BRANCH",
      ],
      required_pull_request: null, // (2)!
      required_status_checks: null,
    },
  ],
  _repositories+:: [
    orgs.newRepo('my-repo') {
      rulesets: [
        orgs.newRepoRuleset('default-branch') {
          include_refs+: [
            "~DEFAULT_BRANCH",
          ],
          required_pull_request+: {
            required_approving_review_count: 1,
          },
          required_status_checks+: {
            status_checks+: [
              "build",
            ],
          },
        },
      ],
    },
  ],
}

1. Read-only property that reflects the billing plan of the organization. Otterdog currently only accepts organization rulesets for organizations on the enterprise plan.
2. The baseline blocks force pushes and deletions of the default branch in all repositories.

Open in the Playground

Availability by GitHub plan¶

validate warns about the rules of a ruleset that require a higher plan than the plan of the organization in its configuration, it does not warn if neither the configuration nor its default configuration sets plan, see Organization Settings. validate reports push rules for a public repository as an error, whatever the plan. Plans change over time, check the GitHub documentation before relying on a feature: About rulesets, Organization rulesets for GitHub Team, Managing a merge queue.

Otterdog specifics¶

Otterdog does not support all features of rulesets. The following table lists the rules that can be configured:

The following features cannot be configured with otterdog:

• the parameter update_allows_fetch_and_merge of the rule restricting updates and the required reviewers of the rule requiring a pull request
• targeting the repositories of an organization ruleset by custom properties, only repository names are supported
• deploy keys as bypass actors

When to prefer rulesets¶

Rulesets are the better fit when:

• several protections must apply to the same branch, e.g. an organization baseline and repository specifics
• tags must be protected
• pull requests should go through a merge queue
• exceptions must be explicit and visible, e.g. a release app or a team that may only bypass through pull requests
• a protection should be tested before it is enforced, with the evaluate enforcement
• the protection should follow the default branch, even if it is renamed

When branch protection rules remain a good choice¶

• Existing rules that meet the needs of the project: there is no deprecation that requires migrating them.
• Otterdog has no ruleset equivalent for restricting who can dismiss reviews (restricts_review_dismissals) and for allowing fork syncing on a locked branch (lock_allows_fetch_and_merge).