@guardian/master-to-main NPM

Master to Main

A CLI tool to rename master branch to main for GitHub repos.

Quick Start

master-to-main can be installed using either npm or yarn

npm install -g @guardian/master-to-main

yarn global add @guardian/master-to-main

It can then be run as follows

$ m2m [OWNER/REPO] [TOKEN]
running command...

View all options and help information

$ m2m --help
...

View installed version

$ m2m (-v|--version)
master-to-main/0.0.0 darwin-x64 node-v14.9.0

It can also be used directly via npx

npx @guardian/master-to-main --help

Running

This tool requires two arguments.

Argument	Description
accessToken	A GitHub personal access token. See the auth section for more details
repoName	The name of the repository to migrate in the form `owner/repository`

This tool can also be run with a number of options. The following table lists them all.

Option	Short	Description	Default
from	-f	The current name of the branch	master
to	-t	The new name of the branch	main
force	-	Disable any user prompts	false
execute	-x	Execute the migration	false
verbose	-	Output debug logs	false
guardian	-	Run the guardian specific steps around build configuration. Disable using `--no-guardian`	true
issues	-	Open issues for any further changes required. Disable using `--no-guardian`	true

As well as this, the --version option can be used to display the current version install and the --help option can be used to display the help information.

Details

This tool is built on top of the oclif library to provide CLI functionality.

It interfaces with the GitHub API to carry out the necessary steps for the migration (more information below). It makes use of the octokit library.

Execution

By default, the app runs in dry run mode. This will perform GET requests and log all steps as if they were to be executed. This can be useful both to see how the process works without making changes and to run checks to reduce the chance of encountering an error partway through the process. To execute the change, pass the -x or --execute flag.

Auth

Authentication and authorisation is handled using GitHub Personal Access Tokens (PATs). You will need to provide this as the second argument (after the repo name) when you run the tool.

N.B. Treat your tokens like passwords and keep them secret. Consider using environment variables to store tokens during use and remove any tokens that are not in use.

You can create a token from the Developer settings tab within GitHub settings. For public repos, the public_repo scope will suffice. For private repos, the repo scope is needed.

It is recommended that a new token is created specifically for the purpose of running this tool, so that the token can be removed from your account immediately after the process is complete.

Steps

The process carries out the following steps in order:

Check if the repository exists (by getting the repo object)
Check that the old branch name exists
Check if the new branch name already exists
Check if the user is an admin (by getting the username from the access token and then calling the get repository permissions for user endpoint)
Get the number of open PRs and check with that user that they're happy to proceed
Rename the branch using the new rename a branch API
Check if a riff-raff.yaml file is present and open an issue if it is (unless the --no-guardian option is passed)
Check for any files that reference the old branch name and open an issue if any exist
Open an issue to cover any (other) build configuration that may need updating