DEV Community

Nobuo Miura
Nobuo Miura

Posted on

I Got Tired of Recreating GitHub Rulesets, So I Built a GitHub CLI Extension

#showdev #github #go #cli

Every time I created a new repository, I found myself configuring the same rules for its default branch again:

  • Require changes to go through pull requests
  • Block force pushes
  • Prevent branch deletion
  • Require status checks when needed

None of this is difficult for a single repository. But as the number of repositories grows, repeatedly opening the same settings page and recreating the same ruleset becomes tedious. It also becomes harder to tell which repositories still share the same configuration.

I wanted a way to save one repository ruleset as a reusable template, apply it elsewhere, and check whether the deployed rulesets still matched it.

So I built gh-rulekit, an open-source GitHub CLI extension for saving, editing, and reusing repository rulesets.

GitHub logo nobuo-miura / gh-rulekit

GitHub CLI extension to save, edit, and bulk-apply repository rulesets across all your repos

gh-rulekit

English | 日本語

A gh extension for saving GitHub repository rulesets locally, editing them, and applying the same ruleset across multiple repositories.

Features

  • Export repository rulesets to a local library
  • Review and edit saved rulesets as JSON
  • Preview changes before applying them
  • Create or update a ruleset in one or many repositories
  • Compare repository rulesets with locally saved versions

Requirements

  • GitHub CLI installed and authenticated with gh auth login
  • Read access to repositories you export or inspect
  • Repository admin access, or a custom role with permission to edit repository rules, when applying rulesets
  • Go is required only when installing from source

Install

From a release (recommended)

After the first release with prebuilt binaries is published:

gh extension install nobuo-miura/gh-rulekit
Enter fullscreen mode Exit fullscreen mode

From source

git clone https://github.com/nobuo-miura/gh-rulekit.git
cd gh-rulekit
go build -o gh-rulekit .
gh extension install .
Enter fullscreen mode Exit fullscreen mode

Quick start

# 1. Save one ruleset under a convenient local name
gh rulekit
…
Enter fullscreen mode Exit fullscreen mode
View on GitHub

What gh-rulekit Does

gh-rulekit provides a small local library for GitHub repository rulesets. It can:

  • Export an existing repository ruleset
  • Store and edit the exported ruleset as JSON
  • Preview target repositories and whether each ruleset will be created or updated
  • Apply the same ruleset to one or many repositories
  • Compare rulesets on GitHub with locally saved versions

The basic workflow looks like this:

# 1. Save a ruleset under a convenient local name
gh rulekit export owner/source-repo --name main --as protect-default

# 2. Preview the targets and actions
gh rulekit apply protect-default --all --dry-run

# 3. Apply the ruleset
gh rulekit apply protect-default --all

# 4. Check whether the deployed rulesets still match
gh rulekit status
Enter fullscreen mode Exit fullscreen mode

Installation

gh-rulekit requires GitHub CLI and an authenticated session created with gh auth login.

Install the extension with:

gh extension install nobuo-miura/gh-rulekit
Enter fullscreen mode Exit fullscreen mode

Then check the available commands:

gh rulekit --help
Enter fullscreen mode Exit fullscreen mode

The help text follows your locale: Japanese locales receive Japanese help, while other locales receive English help.

Exporting a Ruleset

Start by creating the ruleset you want in one repository through GitHub. Then export it into the local library.

For example, this command exports the main ruleset from owner/source-repo and saves it locally as protect-default:

gh rulekit export owner/source-repo --name main --as protect-default
Enter fullscreen mode Exit fullscreen mode

The --as option changes only the name in the local library. It does not rename the ruleset on GitHub. When the saved ruleset is applied elsewhere, its GitHub name remains main.

You can inspect and manage saved rulesets with:

gh rulekit list
gh rulekit show protect-default
gh rulekit edit protect-default
Enter fullscreen mode Exit fullscreen mode

edit opens the JSON file in $EDITOR and validates the file after it is saved. This makes it possible to review or adjust the API representation directly without maintaining a separate configuration format.

Previewing a Bulk Apply

Applying configuration across many repositories is useful, but it is also an operation worth reviewing first.

With --dry-run, gh-rulekit lists each target and shows whether it would create a new ruleset or update an existing ruleset with the same name. It does not modify anything.

gh rulekit apply protect-default --all --dry-run
Enter fullscreen mode Exit fullscreen mode

Targets can be filtered by visibility:

gh rulekit apply protect-default --all --public --dry-run
gh rulekit apply protect-default --all --private --dry-run
Enter fullscreen mode Exit fullscreen mode

You can also target an organization:

gh rulekit apply protect-default --all --owner my-org --dry-run
Enter fullscreen mode Exit fullscreen mode

Archived repositories are skipped because they are read-only.

Always review the output of --dry-run before using --all. A bulk apply can modify many repositories.

Applying the Ruleset

After reviewing the targets, remove --dry-run to apply the ruleset:

gh rulekit apply protect-default --all
Enter fullscreen mode Exit fullscreen mode

If a repository already has a ruleset with the same GitHub name, gh-rulekit updates it. Otherwise, it creates a new one.

To change only one repository, use --repo:

gh rulekit apply protect-default --repo owner/repo
Enter fullscreen mode Exit fullscreen mode

Rulesets that target GitHub's ~DEFAULT_BRANCH placeholder can be reused without knowing whether each repository uses main, master, or another default branch name. There is no need to rewrite the saved JSON for every repository.

Detecting Configuration Drift

Bulk application solves only half of the problem. I also wanted to know whether repository rulesets still matched the version I had saved locally.

The status command compares ruleset contents with the local library:

gh rulekit status
Enter fullscreen mode Exit fullscreen mode

Its output uses three states:

  • == local:<name> — the content matches a locally saved ruleset
  • != local:<name> — a local ruleset with the same name exists, but its content differs
  • -- (no local match) — no corresponding local ruleset was found

The first comparison is content-based, so it can find a match even when the local saved name differs from the ruleset name on GitHub.

To inspect a single repository:

gh rulekit status --repo owner/repo
Enter fullscreen mode Exit fullscreen mode

This provides a quick way to spot repositories whose settings have diverged after a manual change.

Why Not Use Organization Rulesets?

GitHub already supports organization-level rulesets, and they are the natural choice when you want centralized enforcement across repositories in one organization and your plan supports them.

gh-rulekit is aimed at a different set of cases:

  • You maintain multiple repositories under a personal account
  • You want to reuse a repository ruleset across different owners or organizations
  • You want the ruleset available locally as editable JSON
  • You want to compare current repository settings with a saved reference

It does not replace GitHub Rulesets. It makes repository-level rulesets easier to save, reuse, and inspect.

Notes for v0.1.0

  • Exporting and inspecting rulesets requires read access to the target repositories
  • Applying rulesets requires repository admin access or a custom role with permission to edit repository rules
  • Rulesets on private repositories require an eligible GitHub paid plan
  • --dry-run previews targets and create/update actions, but it does not show a field-by-field diff
  • A bulk operation continues after individual failures and reports a non-zero exit status at the end
  • Successful changes are not automatically rolled back if another repository fails

For a first run, I recommend filtering the targets, checking --dry-run, and applying the ruleset to a small number of repositories before using it more broadly.

Closing

gh-rulekit came from a very small annoyance: configuring the same default-branch rules every time I created a repository.

The settings themselves were not complicated. They were simply repetitive. Turning that repetition into a reusable CLI workflow has made creating and reviewing repositories much easier for me.

gh-rulekit is still at v0.1.0. If you try it and find a bug or have an idea for improving the workflow, feedback and issues are welcome.

GitHub logo nobuo-miura / gh-rulekit

GitHub CLI extension to save, edit, and bulk-apply repository rulesets across all your repos

gh-rulekit

English | 日本語

A gh extension for saving GitHub repository rulesets locally, editing them, and applying the same ruleset across multiple repositories.

Features

  • Export repository rulesets to a local library
  • Review and edit saved rulesets as JSON
  • Preview changes before applying them
  • Create or update a ruleset in one or many repositories
  • Compare repository rulesets with locally saved versions

Requirements

  • GitHub CLI installed and authenticated with gh auth login
  • Read access to repositories you export or inspect
  • Repository admin access, or a custom role with permission to edit repository rules, when applying rulesets
  • Go is required only when installing from source

Install

From a release (recommended)

After the first release with prebuilt binaries is published:

gh extension install nobuo-miura/gh-rulekit
Enter fullscreen mode Exit fullscreen mode

From source

git clone https://github.com/nobuo-miura/gh-rulekit.git
cd gh-rulekit
go build -o gh-rulekit .
gh extension install .
Enter fullscreen mode Exit fullscreen mode

Quick start

# 1. Save one ruleset under a convenient local name
gh rulekit
…
Enter fullscreen mode Exit fullscreen mode
View on GitHub

Top comments (0)