Repository ruleset

Repository ruleset

The rules module defines a ruleset as named rules that GitHub enforces on the branches, tags or pushes of a repository, or of every repository in an organization or enterprise that it targets.¹ The schema models it as GhaRepositoryRuleset.

What the class records

• ruleset_source_type and ruleset_source say what owns the ruleset: a Repository, an Organization or an Enterprise, and its name, such as <owner>/<repo>.
• ruleset_target says what the ruleset applies to: branch, which is GitHub’s default, tag, or push, by the files a push changes.
• enforcement is active, evaluate or disabled. evaluate reports but does not enforce, so administrators can test the rules, and only GitHub Enterprise has it.
• ref_name_include names the refs it applies to, as names or patterns such as refs/heads/main, ~DEFAULT_BRANCH or ~ALL, and ref_name_exclude the refs it leaves out.
• bypass_actors lists who may bypass it. Each actor has an actor_type, such as Team, RepositoryRole, Integration or OrganizationAdmin, an actor_id where the type takes one, and a bypass_mode, such as always, pull_request or exempt, with always as GitHub’s default.
• rule_types lists the type of each rule, such as deletion, non_fast_forward, pull_request or required_status_checks.
• requires_check names the required status checks that its required_status_checks rule requires. Of the rules’ parameters, only those are modelled.

A comment says that SLSA’s Source track calls such rules technical controls on protected named references, and asks that their meaning be documented and their enforcement recorded in attestations, which the slsa schema models.

docs/index.md says that no tool checks that a ruleset whose requires_check names a check lists required_status_checks among its rule_types.²

In this repository

SECURITY.md says that a ruleset on main, a repository setting rather than a file, blocks deletion and force-pushes and keeps the history linear.³

Footnotes

1. src/github_actions/schema/github_actions_rules.yaml, GhaRepositoryRuleset, GhaBypassActor and the enums ↩

2. docs/index.md, the Validating data section ↩

3. SECURITY.md, the paragraph after the table ↩