gh-migrate-rulesets

A GitHub gh CLI extension to create a report containing repository rulesets for a single repository, list of repositories, and/or organization, as well as create repository rulesets from a file.

Note

The authenticated user must be an organization owner and a GitHub Personal Access Token needs the admin:read scope at the organization level to use this CLI extension to it's fullest.

Installation

1. Install the gh CLI - see the installation instructions.

2. Install the extension:

   gh extension install katiem0/gh-migrate-rulesets

For more information: gh extension install.

Usage

The gh-migrate-rulesets extension supports GitHub.com and GitHub Enterprise Server, through the use of --hostname and the following commands:

$ gh migrate-rulesets -h
List and create repository/organization level rulesets for repositories in an organization.

Usage:
  migrate-rules [command]

Available Commands:
  create      Create repository rulesets
  list        Generate a report of rulesets for repositories and/or organization.

Flags:
  -h, --help   help for migrate-rules

Use "migrate-rules [command] --help" for more information about a command.

List Repository Rulesets

The gh migrate-rulesets list command will create a csv report of repository rulesets for the specified <organization> and/or [repo ..] list, with the ability to specify the --host-name and --token associated to a Server instance. If only <organization> is provided, all repositories will be used.

To specify the type of ruleset to list, setting the --ruleType flag will either list:

• all: Organization level, and repository level rulesets
• repoOnly: Repository level rulesets for list of repos or all repos under <organization>
• orgOnly: Organization level rulesets only

$ gh migrate-rulesets list -h
Generate a report of rulesets for a list of repositories and/or organization.

Usage:
  migrate-rules list [flags] <organization> [repo ...]

Flags:
  -d, --debug                To debug logging
  -h, --help                 help for list
      --hostname string      GitHub Enterprise Server hostname (default "github.com")
  -o, --output-file string   Name of file to write CSV list to (default "ruleset-20240819094546.csv")
  -r, --ruleType string      List rulesets for a specific application or all: {all|repoOnly|orgOnly} (default "all")
  -t, --token string         GitHub Personal Access Token (default "gh auth token")

The output csv file contains the following information:

Click to Expand output csv file contents

Field Name	Description
RulesetLevel	Indicates whether the ruleset is at the organization or repository level.
RepositoryName	If repository level ruleset, the name of the repository where the data is extracted from. For Organization rulesets, this is `N/A`.
RuleID	Unique identifier for the rule.
RulesetName	Name of the ruleset.
Target	Indicates the type of ruleset, can be `branch`, `tag`, or `push`.
Enforcement	Enforcement level of the ruleset (e.g., `active`, `evaluate`, or `disabled`).
BypassActors	Actors who can bypass the ruleset, specified in the format `ID;Role;Name;Condition`.
ConditionsRefNameInclude	Array of `ref` names to include in the ruleset conditions.
ConditionsRefNameExclude	Array of `ref` names to exclude from the ruleset conditions.
ConditionsRepoNameInclude	Array of repository names to include in the ruleset conditions.
ConditionsRepoNameExclude	Array of repository names to exclude from the ruleset conditions.
ConditionsRepoNameProtected	Indicates whether renaming of target repositories is prevented.
ConditionRepoPropertyInclude	Array of repository properties values to include in the ruleset conditions.
ConditionRepoPropertyExclude	Array of repository properties values to exclude from the ruleset conditions.
RulesCreation	Only allow users with bypass permission to create matching refs.
RulesUpdate	Only allow users with bypass permissions to delete matching refs.
RulesDeletion	Prevent merge commits from being pushed to matching refs.
RulesRequiredLinearHistory	Prevent merge commits from being pushed to matching refs.
RulesMergeQueue	Merges must be performed via a merge queue. In the format `check_response_timeout_minutes|grouping_strategy|max_entries_to_build|max_entries_to_merge|merge_method|min_entries_to_merge|min_entries_to_merge_wait_minutes`
RulesRequiredDeployments	Choose which environments must be successfully deployed to before refs can be pushed into a ref that matches this rule. Includes `required_deployment_environments` array.
RulesRequiredSignatures	Commits pushed to matching refs must have verified signatures.
RulesPullRequest	Require all commits be made to a non-target branch and submitted via a pull request before they can be merged. In the format `dismiss_stale_reviews_on_push|require_code_owner_review|require_last_push_approval|required_approving_review_count|required_review_thread_resolution`
RulesRequiredStatusChecks	Choose which status checks must pass before the ref is updated. An array of required status check rules, in the format `do_not_enforce_on_create|required_status_checks:{context|integration}|strict_required_status_checks_policy`
RulesNonFastForward	Prevent users with push access from force pushing to refs.
RulesCommitMessagePattern	Indicates commit message patterns and matching. In the format `Name|Negate|Operator|Pattern`
RulesCommitAuthorEmailPattern	Indicates commit author email patterns and matching. In the format `Name|Negate|Operator|Pattern`
RulesCommitterEmailPattern	Indicates committer email patterns and matching. In the format `Name|Negate|Operator|Pattern`
RulesBranchNamePattern	Indicates branch name patterns and matching. In the format `Name|Negate|Operator|Pattern`
RulesTagNamePattern	Indicates tag name patterns and matching. In the format `Name|Negate|Operator|Pattern`
RulesFilePathRestriction	Prevent commits that include changes in specified file paths from being pushed to the commit graph.
RulesFilePathLength	Prevent commits that include file paths that exceed a specified character limit from being pushed to the commit graph.
RulesFileExtensionRestriction	Restrictions on file extensions for the ruleset.
RulesMaxFileSize	Maximum file size allowed to be pushed to the commit.
RulesWorkflows	Require all changes made to a targeted branch to pass the specified workflows before they can be merged. An array of workflow rules, in the format `do_not_enforce_on_create|workflows:{Path|ref|repository_id|sha}`
RulesCodeScanning	Choose which tools must provide code scanning results before the reference is updated. An array of code scanning rules in the format `{Tool|SecurityAlertsThreshold|AlertsThreshold}`
CreatedAt	Timestamp of when the ruleset was created.
UpdatedAt	Timestamp of when the ruleset was last updated.

Create Repository Rulesets

Repository Rulesets can be created from a csv file using --from-file following the format outlined in gh-migrate-rulesets list, or specifying the --source-org and/or --repos to retrieve rulesets from.

Warning

If your rulesets include the following rules, ensure that the csv has been updated to point to the updated information under your organization:

• Bypass Actors: Update Actor ID for Teams, Roles, and Integrations
• Status Checks: Ensure Context name exists and update Integration ID
• Code Scanning: Ensure Tool name exists
• Workflows: Update Repository ID to point to the correct repo/workflow
• Required Deployments: Ensure deployment names exist for the repository

$ gh migrate-rulesets create -h                                                   
Create repository rulesets at the repo and/or org level from a file or list.

Usage:
  migrate-rules create [flags] <organization>

Flags:
  -d, --debug                    To debug logging
  -f, --from-file string         Path and Name of CSV file to create rulesets from
  -h, --help                     help for create
      --hostname string          GitHub Enterprise Server hostname (default "github.com")
  -R, --repos strings            List of repositories names to recreate rulesets for separated by commas (i.e. repo1,repo2,repo3)
  -r, --ruleType string          List rulesets for a specific application or all: {all|repoOnly|orgOnly} (default "all")
      --source-hostname string   GitHub Enterprise Server hostname where rulesets are copied from (default "github.com")
  -s, --source-org string        Name of the Source Organization to copy rulesets from
  -p, --source-pat string        GitHub personal access token for Source Organization (default "gh auth token")
  -t, --token string             GitHub personal access token for organization to write to (default "gh auth token")

If specifying --source-org and/or --repos, the CLI extension will attempt to map the object based on name to the new ID under the target organization:

• Bypass Actors
  • Teams
  • Custom Repository Roles
  • Integrations
• Status Checks
  • Context
• Required Workflow
  • Repository

Note

If a ruleset fails to be created, a ruleset's Source, Name, and Error will be written to a csv file in the current directory with the name format <org>-ruleset-errors-<date>.csv.