Repository Ruleset

Definition of a Repository Ruleset, the following properties are supported:

Rulesets support use-cases that can not be modelled with Branch Protection Rules, e.g. bypass actors that are exempted from all rules of a ruleset, while the bypass allowances of a Branch Protection Rule only lift the pull request requirement and required status checks still apply. See Rulesets or branch protection rules for a comparison and the features of rulesets that are not supported, and Protecting branches for examples, e.g. restricting the files that can be pushed with a ruleset with target push.

A ruleset with target push checks the content of every push, to any ref of the repository: GitHub only supports the push rules in it, restricted_file_paths, max_file_path_length, restricted_file_extensions and max_file_size. The rules protecting branches or blocking the merge of pull requests, e.g. requires_linear_history or required_code_scanning, have to be defined in a separate ruleset with target branch.

A rule missing from a ruleset, e.g. because the default template predates it, is not managed: plan reports no difference for it and apply keeps its current setting on GitHub, including its exceptions, e.g. restricted_file_paths_exceptions, while a rule set to its disabled value, e.g. null, is removed.

Jsonnet Function¶

orgs.newRepoRuleset('<name>') {
  <key>: <value>
}

Embedded Models¶

Status Check Settings¶

Jsonnet Function¶

orgs.newStatusChecks() {
  <key>: <value>
}

Pull Request Settings¶

Jsonnet Function¶

orgs.newPullRequest() {
  <key>: <value>
}

Merge Queue Settings¶

Jsonnet Function¶

orgs.newMergeQueue() {
  <key>: <value>
}

Copilot Code Review Settings¶

Jsonnet Function¶

orgs.newCopilotCodeReview() {
  <key>: <value>
}

Pattern Settings¶

Jsonnet Function¶

orgs.newPattern() {
  <key>: <value>
}

Code Scanning Settings¶

Jsonnet Function¶

orgs.newCodeScanning() {
  <key>: <value>
}

Code Quality Settings¶

Jsonnet Function¶

orgs.newCodeQuality() {
  <key>: <value>
}

Code Coverage Settings¶

Jsonnet Function¶

orgs.newCodeCoverage() {
  <key>: <value>
}

Validation rules¶

• setting enforcement to evaluate for an organization on a non enterprise plan triggers an error
• setting target must be one of branch, tag or push, any other value triggers an error
• setting restricted_file_paths, max_file_path_length, restricted_file_extensions or max_file_size for a ruleset whose target is not push triggers an error
• setting a rule that rulesets with target push do not support, e.g. copilot_code_review or commit_message_pattern, for a ruleset with target push triggers an error, a warning for the rules allows_*, requires_*, required_pull_request, required_status_checks and required_merge_queue
• setting a rule required before merging a pull request, e.g. copilot_code_review or required_code_scanning, for a ruleset with target tag triggers an error
• setting branch_name_pattern for a ruleset whose target is not branch, or tag_name_pattern for a ruleset whose target is not tag triggers an error
• setting include_refs or exclude_refs for a ruleset with target push triggers a warning, as push rulesets apply to all refs of a repository
• setting restricted_file_paths, max_file_path_length, restricted_file_extensions or max_file_size for a ruleset of a public repository triggers an error, as GitHub only supports push rules for private and internal repositories
• setting max_file_path_length outside the range [0, 32767], max_file_size outside the range [0, 100], or more than 200 entries or an entry longer than 200 characters in the lists of the push rules triggers an error
• setting restricted_file_paths_exceptions while restricted_file_paths is empty, or max_file_size_exceptions while max_file_size is 0 triggers a warning
• setting an invalid operator, an empty pattern, an invalid code scanning tool or threshold, an invalid code quality severity or a code coverage threshold outside the range [0, 100] triggers an error
• setting a push rule, required_code_quality or required_code_coverage for an organization on a free plan triggers a warning, as they require at least GitHub Team
• setting a pattern, e.g. commit_message_pattern, or requires_license_compliance_scanning for an organization on a non enterprise plan triggers a warning, as they require GitHub Enterprise
• setting required_workflows triggers an error, as it is only supported by organization rulesets, see Organization Ruleset

Example usage¶

orgs.newOrg('adoptium') {
  ...
  _repositories+:: [
    ...
    orgs.newRepo('adoptium.net') {
      description: "Adoptium Website",
      homepage: "https://adoptium.net",
      ...
      rulesets: [
        orgs.newRepoRuleset('main') {
          bypass_actors+: [
            "@adoptium/project-leads",
          ],
          include_refs+: [
            "~DEFAULT_BRANCH"
          ],
          required_pull_request+: {
            required_approving_review_count: 0,
          },
          required_status_checks+: {
            strict: true,
            status_checks+: [
              "build"
            ],
          },
          required_merge_queue: orgs.newMergeQueue() {
            merge_method: "REBASE"
          }
        },
      ],
    },
  ],
}