Organization Ruleset

Definition of an Organization Ruleset, the following properties are supported:

Key	Value	Description	Notes
include_repo_names	list[RepoNameMatcher]	List of names or patterns to include matching repositories
exclude_repo_names	list[RepoNameMatcher]	List of names or patterns to exclude matching repositories
protect_repo_names	boolean	If enabled, target repositories can only be renamed by those with bypass permission
name	string	The name of this repository ruleset
target	string	The target of this ruleset	Possible values are `branch`, `tag` or `push`
enforcement	string	The enforcement status of this ruleset	Possible values are `active`, `disabled` or `evaluate` (`evaluate` only available when enterprise billing is enabled)
bypass_actors	list[BypassActor]	List of actors able to bypass this ruleset
include_refs	list[RefMatcher]	List of refs or patterns to include matching branches
exclude_refs	list[RefMatcher]	List of refs or patterns to exclude matching branches
allows_creations	boolean	If disabled, only allows users with bypass permission to create matching refs
allows_deletions	boolean	If disabled, only allows users with bypass permission to delete matching refs
allows_updates	boolean	If disabled, only allows users with bypass permission to push matching refs
allows_force_pushes	boolean	If disabled, only allows users with bypass permission to force push matching refs
required_status_checks	StatusCheckSettings or null	If specified, status checks must pass before branches can be merged into a matching branch
requires_commit_signatures	boolean	If enabled, commits pushed to matching branches must have verified signatures
requires_linear_history	boolean	If enabled, prevent merge commits from being pushed to matching branches
requires_deployments	boolean	If enabled, environments must be successfully deployed to before branches can be merged into a matching branch
required_deployment_environments	list[string]	List of environments that must be successfully deployed to before branches can be merged	Only taken into account when `requires_deployments` is enabled
required_pull_request	PullRequestSettings or null	If specified, requires a pull request before merging. All commits must be made to a non-protected branch and submitted via a pull request before they can be merged into matching branches
required_merge_queue	MergeQueueSettings or null	If specified, merges must be performed via a merge queue

Rulesets can be used for use-cases (e.g. to support auto merging of pull requests) that can not be modelled with Branch Protection Rules:

define a set of required status checks
define a set of users that can bypass pull requests

Branch Protection Rules always consider the required status checks, even when directly pushing to the branch, e.g. when no pull request is required, or you can push due to a bypass allowance. This can be modelled with Rulesets though, as the bypass actors as defined for a Ruleset are taken into account for all settings (except allows_force_pushes), while the bypass allowance for Branch Protection Rules only apply for pull requests in general.

Jsonnet Function¶

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

Embedded Models¶

Status Check Settings¶

Key	Value	Description	Notes
do_not_enforce_on_create	boolean	If enabled, allow repositories and branches to be created if a check would otherwise prohibit it
strict	boolean	If enabled, pull requests targeting a matching branch must have been tested with the latest code	This setting will not take effect unless at least one status check is enabled
status_checks	list[StatusCheck]	List of status checks that must succeed before branches can be merged

Jsonnet Function¶

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

Pull Request Settings¶

Key	Value	Description	Notes
required_approving_review_count	integer	The number or approvals required before a pull request can be merged	Allowed values in the range [0, 10]
dismisses_stale_reviews	boolean	If enabled, dismiss approved reviews automatically when a new commit is pushed
requires_code_owner_review	boolean	If enabled, require an approved review in pull requests including files with a designated code owner
requires_last_push_approval	boolean	Whether the most recent push must be approved by someone other than the person who pushed it
requires_review_thread_resolution	boolean	If enabled, all conversations on code must be resolved before a pull request can be merged into a matching branch

Jsonnet Function¶

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

Merge Queue Settings¶

Key	Value	Description	Notes
merge_method	string	Method to use when merging changes from queued pull requests	Possible values are `MERGE`, `SQUASH` or `REBASE`
build_concurrency	integer	Limit the number of queued pull requests requesting checks and workflow runs at the same time	Must be in non-negative number
min_group_size	integer	The minimum number of PRs that will be merged together in a group	Must be in non-negative number
max_group_size	integer	The maximum number of PRs that will be merged together in a group	Must be in non-negative number
wait_time_for_minimum_group_size	integer	The time in minutes the merge queue should wait after the first PR is added to the queue for the minimum group size to be met. After this time has elapsed, the minimum group size will be ignored and a smaller group will be merged	Must be in non-negative number
status_check_timeout	integer	Maximum time in minutes for a required status check to report a conclusion. After this much time has elapsed, checks that have not reported a conclusion will be assumed to have failed	Must be in non-negative number
requires_all_group_entries_to_pass_required_checks	boolean	When this setting is disabled, only the commit at the head of the merge group, i.e. the commit containing changes from all of the PRs in the group, must pass its required checks to merge

Jsonnet Function¶

orgs.newMergeQueue() {
  <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

Example usage¶

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

jsonnet

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