gh-rule-kit

README

gh-rule-kit

gh extension of github rules api

Installation

gh extension install srz-zumix/gh-rule-kit

Shell Completion

Workaround Available! While gh CLI doesn't natively support extension completion, we provide a patch script that enables it.

Prerequisites: Before setting up gh-rule-kit completion, ensure gh CLI completion is configured for your shell. See gh completion documentation for setup instructions.

For detailed installation instructions and setup for each shell, see the Shell Completion Guide.

Global Options

All commands support the following global options:

• --read-only: Run in read-only mode (prevent write operations). When enabled, commands that would modify resources (create, update, delete, import, migrate) will be blocked, allowing safe inspection and testing without making actual changes.
• -L, --log-level <level>: Set log level: {debug|info|warn|error} (default: "info")

Commands

Branch Protection Rules

Delete branch protection settings

gh rule-kit repo branch-protection delete <branch> [-R <repo>]

Remove the protection settings from a branch. If repo is not specified, the current repository will be used.

Options:

• -R, --repo <repo>: The repository in the format 'owner/repo' (optional, defaults to current repository)

Get branch protection settings

gh rule-kit repo branch-protection get <branch> [-R <repo>]

Get the protection settings for a specific branch. If repo is not specified, the current repository will be used.

Options:

• -R, --repo <repo>: The repository in the format 'owner/repo' (optional, defaults to current repository)

List protected branches

gh rule-kit repo branch-protection list [-R <repo>]

List all protected branches for a repository. If repo is not specified, the current repository will be used.

Options:

• -R, --repo <repo>: The repository in the format 'owner/repo' (optional, defaults to current repository)

Tag Protection Rules

Delete tag protection settings

gh rule-kit repo tag-protection delete <pattern> [-R <repo>]

Remove the protection settings from a tag pattern. If repo is not specified, the current repository will be used.

Options:

• -R, --repo <repo>: The repository in the format 'owner/repo' (optional, defaults to current repository)

Get tag protection settings

gh rule-kit repo tag-protection get <pattern> [-R <repo>]

Get the protection settings for a specific tag pattern. If repo is not specified, the current repository will be used.

Options:

• -R, --repo <repo>: The repository in the format 'owner/repo' (optional, defaults to current repository)

List tag protection settings

gh rule-kit repo tag-protection list [-R <repo>]

List all tag protection settings for a repository. If repo is not specified, the current repository will be used.

Options:

• -R, --repo <repo>: The repository in the format 'owner/repo' (optional, defaults to current repository)

Repository Rulesets

Delete a repository ruleset

gh rule-kit repo delete <ruleset-id> [-R <repo>]

Delete a specific repository ruleset by its ID. If repo is not specified, the current repository will be used.

Options:

• -R, --repo <repo>: The repository in the format 'owner/repo' (optional, defaults to current repository)

Export a repository ruleset to JSON file

gh rule-kit repo export <ruleset-id> [-R <repo>] [-o <output>] [-p]

Export a specific repository ruleset by its ID to a JSON file. If repo is not specified, the current repository will be used. The exported JSON can be used for backup or to import into another repository.

Options:

• -p, --includes-parent: Include parent rulesets (default: false)
• -o, --output <output>: Output file path (optional, defaults to stdout)
• -R, --repo <repo>: The repository in the format 'owner/repo' (optional, defaults to current repository)

Get a repository ruleset

gh rule-kit repo get <ruleset-id> [-R <repo>] [-p]

Get detailed information about a specific repository ruleset by its ID. If repo is not specified, the current repository will be used.

Options:

• -p, --includes-parent: Include parent rulesets (default: false)
• -R, --repo <repo>: The repository in the format 'owner/repo' (optional, defaults to current repository)

Import a repository ruleset from JSON file

gh rule-kit repo import <input> [-R <repo>] [-c] [--usermap <file>]

Import a repository ruleset from a JSON file. If repo is not specified, the current repository will be used. Use --create-if-none flag to create a new ruleset if it does not exist. When --usermap is specified, source user logins in User-type bypass actors are automatically converted to destination logins using the mapping file (as produced by 'user map' in gh-team-kit).

Options:

• -c, --create-if-none: Create a new ruleset if it does not exist (default: false)
• -R, --repo <repo>: The repository in the format 'owner/repo' (optional, defaults to current repository)
• --usermap <file>: User mapping file for User-type bypass actors in the target repository ruleset (as produced by 'user map' in gh-team-kit) (optional)

List repository rulesets

gh rule-kit repo list [-R <repo>] [-p]

List all rulesets for a repository. If repo is not specified, the current repository will be used.

Options:

• -p, --includes-parent: Include parent rulesets (default: false)
• -R, --repo <repo>: The repository in the format 'owner/repo' (optional, defaults to current repository)

Migrate repository rulesets to another repository

gh rule-kit repo migrate <dst-repo> [ruleset-id...] [-R <repo>] [--github-actions-app-id <id>] [--usermap <file>]

Migrate repository rulesets from source repository to destination repository. If ruleset IDs are not specified, all rulesets will be migrated. Source repository is specified with --repo flag, destination repository is specified as the first argument. When --usermap is specified, source user logins in User-type bypass actors are mapped to destination logins using the mapping file (as produced by 'user map' in gh-team-kit).

Options:

• --github-actions-app-id <id>: The GitHub Actions App ID for integration mapping (optional, default: 0)
• -R, --repo <repo>: The source repository in the format 'owner/repo' (optional, defaults to current repository)
• --usermap <file>: User mapping file to map source User-type bypass actor logins to destination logins (as produced by 'user map' in gh-team-kit) (optional)

Convert a branch protection rule to a ruleset

gh rule-kit repo from-branch-protection <branch> [-R <repo>] [-n] [--delete]

Convert a branch protection rule to a repository ruleset and display the result. Use --dryrun (-n) to preview the converted ruleset without creating it.

The following branch protection settings are converted:

Branch Protection Setting	Ruleset Equivalent
Require linear history	required_linear_history rule
Allow force pushes (disabled)	non_fast_forward rule
Allow deletions (disabled)	deletion rule
Block creations	creation rule
Require signed commits	required_signatures rule
Required status checks	required_status_checks rule
Required pull request reviews	pull_request rule
Require conversation resolution	required_review_thread_resolution (in pull_request rule)
Do not include administrators	Repository Admin bypass actor

Note: Push-access restrictions (Restrictions) cannot be directly converted to rulesets and are reported as warnings.

Options:

• --delete: Delete the original branch protection rule after successful conversion (default: false)
• -n, --dryrun: Print the ruleset that would be created without actually creating it (default: false)
• -R, --repo <repo>: The repository in the format 'owner/repo' (optional, defaults to current repository)

Convert a tag protection rule to a ruleset

gh rule-kit repo from-tag-protection <pattern> [-R <repo>] [-n] [--delete]

Convert a tag protection rule to a repository ruleset and display the result. Use --dryrun (-n) to preview the converted ruleset without creating it.

The converted ruleset targets refs/tags/<pattern> and applies:

• creation rule
• update rule
• deletion rule

Options:

• --delete: Delete the original tag protection rule after successful conversion (default: false)
• -n, --dryrun: Print the ruleset that would be created without actually creating it (default: false)
• -R, --repo <repo>: The repository in the format 'owner/repo' (optional, defaults to current repository)

Repository Rule Suite Insights

List repository rule suites

gh rule-kit repo insight list [-R <repo>] [--ref <ref>] [--time-period <period>] [--actor-name <name>] [--result <result>]

List all rule suites for a repository. If repo is not specified, the current repository will be used. Rule suites represent evaluations of repository rules.

Options:

• -R, --repo <repo>: The repository in the format 'owner/repo' (optional, defaults to current repository)
• --ref <ref>: Filter by ref name (e.g., 'main', 'refs/heads/main') (optional)
• --time-period <period>: Filter by time period (e.g., 'hour', 'day', 'week', 'month') (optional)
• --actor-name <name>: Filter by actor name (optional)
• --result <result>: Filter by rule suite result (e.g., 'pass', 'fail', 'bypass') (optional)

Note: This feature requires the Rule Suites API which is not yet fully implemented in go-github v73. The command structure is prepared for future implementation.

Get a repository rule suite

gh rule-kit repo insight get <rule-suite-id> [-R <repo>]

Get detailed information about a specific repository rule suite by its ID. If repo is not specified, the current repository will be used.

Options:

• -R, --repo <repo>: The repository in the format 'owner/repo' (optional, defaults to current repository)

Note: This feature requires the Rule Suites API which is not yet fully implemented in go-github v73. The command structure is prepared for future implementation.

Organization Rulesets

List organization rulesets

gh rule-kit org list [--owner <owner>]

List all rulesets for an organization. If org is not specified, the current repository's organization will be used.

Options:

• --owner <owner>: The organization name (optional, defaults to current repository's organization)

Get an organization ruleset

gh rule-kit org get <ruleset-id> [--owner <owner>]

Get detailed information about a specific organization ruleset by its ID. If org is not specified, the current repository's organization will be used.

Options:

• --owner <owner>: The organization name (optional, defaults to current repository's organization)

Export an organization ruleset to JSON file

gh rule-kit org export <ruleset-id> [--owner <owner>] [-o <output>]

Export a specific organization ruleset by its ID to a JSON file. If org is not specified, the current repository's organization will be used. The exported JSON can be used for backup or to import into another organization.

Options:

• -o, --output <output>: Output file path (optional, defaults to stdout)
• --owner <owner>: The organization name (optional, defaults to current repository's organization)

Import an organization ruleset from JSON file

gh rule-kit org import <input> [--owner <owner>] [-c] [--usermap <file>]

Import an organization ruleset from a JSON file. If org is not specified, the current repository's organization will be used. Use --create-if-none flag to create a new ruleset if it does not exist. When --usermap is specified, source user logins in User-type bypass actors are automatically converted to destination logins using the mapping file (as produced by 'user map' in gh-team-kit).

Options:

• -c, --create-if-none: Create a new ruleset if it does not exist (default: false)
• --owner <owner>: The organization name (optional, defaults to current repository's organization)
• --usermap <file>: User mapping file for User-type bypass actors in the target organization ruleset (as produced by 'user map' in gh-team-kit) (optional)

Migrate organization rulesets to another organization

gh rule-kit org migrate <[HOST/]src-org> <[HOST/]dst-org> [ruleset-id...] [--github-actions-app-id <id>] [--usermap <file>]

Migrate organization rulesets from source organization to destination organization. If ruleset IDs are not specified, all rulesets will be migrated. Source organization is specified as the first argument, destination organization is specified as the second argument. When --usermap is specified, source user logins in User-type bypass actors are mapped to destination logins using the mapping file (as produced by 'user map' in gh-team-kit).

Options:

• --github-actions-app-id <id>: The GitHub Actions App ID for integration mapping (optional, default: 0)
• --usermap <file>: User mapping file to map source User-type bypass actor logins to destination logins (as produced by 'user map' in gh-team-kit) (optional)

Delete an organization ruleset

gh rule-kit org delete <ruleset-id> [--owner <owner>]

Delete a specific organization ruleset by its ID. If org is not specified, the current repository's organization will be used.

Options:

• --owner <owner>: The organization name (optional, defaults to current repository's organization)

Organization Rule Suite Insights

List organization rule suites

gh rule-kit org insight list [--owner <owner>] [--ref <ref>] [--time-period <period>] [--actor-name <name>] [--result <result>]

List all rule suites for an organization. If org is not specified, the current repository's organization will be used. Rule suites represent evaluations of organization rules.

Options:

• --owner <owner>: The organization name (optional, defaults to current repository's organization)
• --ref <ref>: Filter by ref name (e.g., 'main', 'refs/heads/main') (optional)
• --time-period <period>: Filter by time period (e.g., 'hour', 'day', 'week', 'month') (optional)
• --actor-name <name>: Filter by actor name (optional)
• --result <result>: Filter by rule suite result (e.g., 'pass', 'fail', 'bypass') (optional)

Note: This feature requires the Rule Suites API which is not yet fully implemented in go-github v73. The command structure is prepared for future implementation.

Get an organization rule suite

gh rule-kit org insight get <rule-suite-id> [--owner <owner>]

Get detailed information about a specific organization rule suite by its ID. If org is not specified, the current repository's organization will be used.

Options:

• --owner <owner>: The organization name (optional, defaults to current repository's organization)

Note: This feature requires the Rule Suites API which is not yet fully implemented in go-github v73. The command structure is prepared for future implementation.

Documentation

Overview

Copyright © 2025 srz_zumix