Organization Ruleset

Definition of an Organization 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 matching repositories: 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_workflows, 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.newOrgRuleset('<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>
}

Workflows Settings¶

Jsonnet Function¶

orgs.newWorkflows() {
  <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_workflows, 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 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, a code coverage threshold outside the range [0, 100] or an invalid workflow triggers an error
• setting a workflow whose path is not a .yml or .yaml file triggers a warning, e.g. because of an unescaped @ in the path
• referencing the repository of a workflow by its id triggers an error, otterdog shows a repository by its id only if it can not resolve its name, e.g. if the repository was deleted
• 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_code_quality, required_code_coverage or requires_license_compliance_scanning triggers an error, as they are only supported by repository rulesets
• defining organization rulesets for an organization on a non enterprise plan triggers an error

Example usage¶

The following ruleset would basically prevent force-pushes for the default branch of all repositories of the eclipse-csi GitHub organization:

orgs.newOrg('eclipse-csi') {
  ...
  rulesets: [
    orgs.newOrgRuleset('main') {
      include_repo_names: [
        "~ALL"
      ],
      include_refs+: [
        "~DEFAULT_BRANCH"
      ],
      required_pull_request: null,
      required_status_checks: null,
    },
  ],
}