gh-ruleset

List all rulesets for the current repository

$ gh [[rs|ruleset]] [[ls|list]]

$ gh [[rs|ruleset]] [[ls|list]] [[-o|--org]] [organization_name]

$ gh [[rs|ruleset]] check

$ gh [[rs|ruleset]] check [branch_name] [[-R|--repo]] [owner]/[repo]

$ gh [[rs|ruleset]] view

$ gh [[rs|ruleset]] view [ruleset_id]

$ gh [[rs|ruleset]] view [ruleset_id] [[-o|--org]] [organization_name]

$ gh [[rs|ruleset]] [[ls|list]] [[-R|--repo]] [owner]/[repo] [[-w|--web]]

gh ruleset <command> [flags]

Available commands:
  create      Create a repository ruleset
  delete      Delete a repository ruleset
  list         List repository rulesets
  update      Update a repository ruleset
  view         View a repository ruleset

For more details on a specific command, use gh ruleset <command> --help.

<ruleset_id>
    The ID of the ruleset to view, update, or delete. (Argument for view, update, delete)

--repo <[HOST/]OWNER/REPO>
    Specify the repository to operate on. Defaults to the current repository. (Applies to all subcommands)

--limit <int>
    Maximum number of rulesets to list. Default is 30. (Applies to list)

--confirm
    Confirm deletion without a prompt. (Applies to delete)

--name <string>
    The name of the ruleset. (Applies to create, update)

--target <target>
    The target of the ruleset, either BRANCH or TAG. (Applies to create, update)

--source <source_id_or_login_or_name>
    The source of the ruleset (e.g., repository ID, user login, or organization name). (Applies to create)

--enforcement <enforcement>
    The enforcement status: active, evaluate, or disabled. (Applies to create, update)

--bypass-actors <actor_id_or_login>
    Comma-separated list of actor IDs or logins allowed to bypass the ruleset. (Applies to create, update)

--bypass-mode <mode>
    The bypass mode for actors: ALWAYS or PULL_REQUEST. (Applies to create, update)

--conditions <json>
    JSON string defining the conditions under which the ruleset applies. (Applies to create, update)

--rules <json>
    JSON string defining the specific rules to enforce. (Applies to create, update)

GitHub repository rulesets enable administrators to enforce a consistent set of policies across branches and tags, enhancing code quality and security. The gh ruleset command, part of the GitHub CLI, provides a powerful interface to programmatically interact with these rulesets directly from the command line. It allows users to list existing rulesets, view their detailed configurations, create new ones, update their settings, and delete them.

This command streamlines the management of complex branch protection rules, facilitating automation and ensuring compliance with organizational standards without needing to navigate the web UI. It supports defining rules for various aspects like required pull request reviews, commit signing, specific commit message formats, and more.

Using gh ruleset requires appropriate permissions (e.g., admin or owner) for the target repository. The --conditions and --rules flags require complex JSON input, which can be challenging to construct and escape correctly directly on the command line, especially for intricate rulesets. It is often recommended to prepare these JSON structures in a separate file and then use command substitution (e.g., "$(cat file.json)") to pass them to the command. Overlapping rulesets or rulesets interacting with legacy branch protection rules can lead to unexpected behavior; understanding their precedence is crucial.

The --conditions and --rules flags accept a JSON string that defines the specific criteria and actions for a ruleset. For complex configurations, it is highly recommended to construct this JSON in a separate file and then pass it to the command line using command substitution to avoid quoting issues and improve readability. For example:
gh ruleset create --name "My Ruleset" --target BRANCH --source <repo_id> --enforcement active --conditions "$(cat conditions.json)" --rules "$(cat rules.json)"

A ruleset is comprised of several key components: a name for identification, an enforcement status (active, evaluate, disabled), a target (BRANCH or TAG), optional bypass actors who can override the ruleset, conditions that determine when the ruleset applies (e.g., `ref_name/include`), and the actual rules which define the policies (e.g., `required_pull_request_reviews`, `required_signatures`). A thorough understanding of these components and their JSON structure is essential for effective ruleset management.

GitHub introduced repository rulesets as a more flexible and powerful alternative to the older "protected branches" feature, allowing for more granular and centralized control over repository interactions. The gh ruleset command was subsequently added to the GitHub CLI to empower users to manage these rulesets programmatically, integrating this advanced capability directly into developer workflows. This evolution reflects GitHub's commitment to providing robust policy enforcement tools for modern development practices.

gh repo(1), gh pr(1), git push(1), gh secret(1)