gh-migrate-rulesets

README

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.

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;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.

[!NOTE] Be sure to update the repository_id in RulesWorkflows field for required workflows for the correct repository under the new Organization else the addition of this ruleset will fail.

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

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

Flags:
  -d, --debug              To debug logging
  -f, --from-file string   Path and Name of CSV file to create repository rulesets from
  -h, --help               help for create
      --hostname string    GitHub Enterprise Server hostname (default "github.com")
  -t, --token string       GitHub personal access token for organization to write to (default "gh auth token")