Home / Alt manpages / gh-ruleset-check(1)

  • gh-ruleset-check(1)
  • User command
  • linux

Check GitHub Branch Rules Before You Push with gh

Before you open a pull request from a branch you have not even created yet, gh ruleset check tells you which GitHub rules would apply to it. It is read-only: no branch created, no ruleset altered, no repository setting changed. Allow about five minutes if you already have GitHub CLI authentication and a repository in mind.

The route

Jump straight to the step you need, or tick off Done means at the end.

Checkpoint

Stop once the command prints the rules that apply to the branch you care about. If the result is empty or access fails, use the checks in the final section before changing anything.

1. Confirm the installed command

The examples here use GitHub CLI 2.87.3. The command is part of the gh package and runs as your own user; it does not need sudo. Check the binary and its local syntax first:

$ command -v gh
/usr/bin/gh
$ gh --version
gh version 2.87.3 (2026-02-23)
https://github.com/cli/cli/releases/tag/v2.87.3
$ gh ruleset check --help
View information about GitHub rules that apply to a given branch.

Your path and version may differ; treat the installed help as authoritative if a later package changes the command. The relevant syntax is gh ruleset check [<branch>] [flags].

2. Check the current branch

From a local checkout, run the command without a branch argument:

$ cd /path/to/your/checkout
$ gh ruleset check

With no branch name, gh uses the current branch. The output is repository-specific, so do not compare its rule names with an example from another repository; the command returns all rules that apply, regardless of where those rules are configured.

Checkpoint

Record the repository and branch before acting on the result. A branch name shown by your shell prompt is useful evidence, but verify it directly when a release or protected change depends on it:

$ git branch --show-current
feature/example-change
$ gh ruleset check

3. Inspect a planned branch before creating it

The branch argument is a name to evaluate, not a request to check out a branch. It does not need to exist, which makes the command useful when you are planning a pull request or deciding whether a naming pattern will match a ruleset:

$ gh ruleset check feature/example-change

Use the exact branch name you intend to create: GitHub ruleset targeting can depend on branch patterns, so a spelling change can produce a different result. The command does not create feature/example-change and does not modify your local checkout.

Tip

Do not put an untrusted string directly into a shell command. If the name comes from another system, keep it as one quoted argument:

$ planned_branch='feature/example-change'
$ gh ruleset check "$planned_branch"

4. Check the default branch explicitly

Use --default when the question is about the repository's default branch, regardless of which branch your checkout currently has:

$ gh ruleset check --default

This is distinct from checking a branch named main or master. The default branch is repository metadata, while those names are ordinary branch arguments; let GitHub choose the default with --default instead of guessing its name.

Checkpoint

Preparing a change for the default branch? Run both the planned branch check and the default check when they answer different questions. Rules that apply to one are not automatically a complete description of the other.

5. Select another repository

Use the inherited --repo option to inspect a repository without changing directory. Its value is [HOST/]OWNER/REPO:

$ gh ruleset check feature/example-change --repo OWNER/REPOSITORY
$ gh ruleset check --default --repo OWNER/REPOSITORY

Replace both uppercase placeholders. For a GitHub Enterprise host, include the host as documented by the option, for example github.example.com/OWNER/REPOSITORY. The selected repository must be one your authenticated account can inspect; repository selection does not grant access or change the repository.

If the repository argument contains shell metacharacters or is assembled by a script, quote the complete value:

$ target_repo='OWNER/REPOSITORY'
$ gh ruleset check --default --repo "$target_repo"

6. Open the browser view when terminal output is not enough

The --web flag opens the branch rules page in a web browser:

$ gh ruleset check feature/example-change --web
$ gh ruleset check --default --repo OWNER/REPOSITORY --web

This still performs a lookup, but adds an external browser action. Confirm the repository and branch arguments before using it, especially in a remote shell with browser forwarding. Omit --web when you need output that can be captured in a terminal log.

7. Diagnose an unexpected result

An absent branch is not an error for this command: it is deliberately evaluated as a possible branch name. A failed lookup is more likely to be caused by the repository target, authentication, network access or an incorrectly typed branch name.

First confirm the target repository without changing it:

$ gh repo view OWNER/REPOSITORY --json nameWithOwner,defaultBranchRef

If that command cannot read the repository, resolve authentication or permissions before interpreting ruleset output.

Safety warning

Do not run with elevated privileges as a workaround. sudo gh can use a different configuration and authentication context, while it does not add GitHub permissions.

When you need details about one ruleset identified in the check output, use the separate read-only command gh ruleset view. An organisation-level ruleset may require its organisation context; do not infer the ruleset's scope from its name alone.

Done means

  • You confirmed the installed gh version and help text.
  • You checked the exact branch name, or used --default for the repository's default branch.
  • You used --repo OWNER/REPOSITORY when the target was not the current checkout.
  • You understand a planned branch need not exist and that the command is read-only.
  • You kept the check unprivileged and did not alter a branch, ruleset or repository setting.