Inspect GitHub Repository Rules with gh ruleset

You will finish with a read-only workflow for seeing which GitHub rulesets exist, what one ruleset contains, and which rules would apply to a branch. The examples use GitHub CLI 2.87.3, installed here as package gh. They inspect policy only: they do not create, edit or delete a ruleset.

Allow about ten minutes. You need GitHub CLI, an authenticated account with access to the target repository, and a local checkout if you want the command to infer its repository. None of the commands in this guide need sudo. Running them as root does not grant GitHub permissions and can make your CLI configuration harder to find later.

1. Confirm the installed command and authentication

Check the binary before relying on its option syntax. This is an ordinary, local read-only check:

$ gh --version
gh version 2.87.3 (2026-02-23)
https://github.com/cli/cli/releases/tag/v2.87.3
$ gh auth status

The version line will differ on another machine. gh auth status should report the account and host you intend to use. If it reports no usable login, authenticate through your normal GitHub CLI process before continuing. Do not paste an access token into a shell command or commit it to a script.

2. Choose the repository explicitly when needed

From a Git checkout connected to GitHub, gh ruleset uses the current repository by default. An explicit --repo removes ambiguity and is safer in scripts:

$ gh ruleset list --repo OWNER/REPO
NAME                         ID
Require review               123456
Protect the release branch   234567

The names, IDs and table layout depend on the repository. A repository with no visible rulesets may produce an empty list rather than an error. The command's global -R and --repo flags accept [HOST/]OWNER/REPO.

Do not treat the list as a complete description of branch behaviour yet. Rulesets can be configured at a higher level, and the list command includes applicable parent rulesets by default. That default is useful for an effective view, but it can surprise you when you are looking for rules configured directly in one repository.

3. Separate local rulesets from inherited rulesets

Run the same listing twice when ownership matters:

$ gh ruleset list --repo OWNER/REPO --parents
$ gh ruleset list --repo OWNER/REPO --no-parents

--parents is the default. --no-parents limits the result to rulesets configured in the selected repository, or in the selected organisation when --org is used. Comparing the outputs helps explain why a repository appears to have a rule that nobody configured there.

For a larger repository, limit the number of rows returned:

$ gh ruleset list --repo OWNER/REPO --limit 100

The installed command defaults to a maximum of 30 rulesets. Increasing the limit does not change GitHub policy; it only changes how many records the command requests for display.

4. View one ruleset by ID

Copy an ID from the list, then request its details. Keep the repository selector in the command so that a copied ID is not accidentally looked up against the current checkout:

$ gh ruleset view 123456 --repo OWNER/REPO
Name: Require review
Target: branch
Enforcement status: active
Rules:
  ...

The exact fields and values vary with the ruleset. If you omit the ID, gh ruleset view starts an interactive selection from rulesets that apply to the current repository. That is convenient at a terminal, but it is a poor fit for repeatable notes or scripts.

Use --no-parents when you specifically need a locally configured ruleset. Use --org ORG_NAME for an organisation-level ruleset ID. Do not guess whether an ID belongs to a repository or organisation: select the scope that owns it and verify the returned name and target before drawing conclusions.

To open the ruleset in GitHub's web interface rather than print its details, add --web:

$ gh ruleset view 123456 --repo OWNER/REPO --web

This launches a browser and can expose information to anyone who can see your screen. It still does not edit the ruleset.

5. Check the effective rules for a branch

Use check when the question is not "what is this ruleset?" but "what would apply to this branch?" The branch name does not need to exist:

$ gh ruleset check feature/audit-logging --repo OWNER/REPO
Rules that apply to feature/audit-logging:
  ...

All returned rules are relevant to the requested branch, regardless of where they are configured. This makes the command useful before opening a pull request or designing a branch name. It does not simulate a pull request, merge, or workflow run, and it does not prove that every later GitHub operation will succeed.

If you want the repository's default branch instead of a named branch, use --default:

$ gh ruleset check --default --repo OWNER/REPO

With no branch and no --default, the command checks the current local branch. That is an easy distraction trap: a detached HEAD or an old checkout can answer a different question from the one you intended. Name the branch explicitly when the result will guide a review or deployment decision.

6. Investigate failures without changing policy

A non-zero result usually means the request could not be completed, not that the branch has no rules. Check these in order:

1. Confirm the repository spelling and host with an explicit --repo.
2. Run gh auth status and check that the active account can access the repository.
3. List rulesets before viewing an ID, because IDs are easy to copy from the wrong repository.
4. Compare --parents with --no-parents when an inherited rule is the likely explanation.
5. Run the local syntax check again if the failure happened before any network request: gh ruleset check --help.

Organisation-wide listing has an extra access boundary. The installed help states that gh ruleset list --org ORG_NAME needs the admin:org scope. Treat refreshing that scope as a security-sensitive credential change. Do it only under your organisation's access policy, and never work around a denied request by copying somebody else's token.

These commands are observational, so there is no undo operation. If you used --web, close the browser tab when finished. If you refreshed credentials while troubleshooting, follow your normal token-revocation process rather than deleting random files from the CLI configuration directory.