Scripts for migrating teams and repos to a new GitHub organization

This directory contains three scripts for to help migrate teams and repositories to a new GitHub organization. Note that the purpose of this utility is to transfer teams' repos between orgs within the same GitHub enterprise account. This utility covers: three main areas:

• Creating a list of current teams: get-teams.rb
• Migrating teams: create_teams.rb
• Migrating repositories: transfer_repos.rb
• Inviting members: invite_members.rb

Setting up your environment

The scripts require a few dependencies, most notably Octokit. In order to start using these scripts, we first have to ensure Ruby is installed on your machine. You can confirm this by running ruby -v in your terminal. If you don't have Ruby installed, you can download it here for your particular OS. If running on macOS, your machine should already have Ruby installed.

The scripts also require a few Ruby gems to be installed. You can install these by running bundle install in the working directory:

1. Once you've installed Ruby, navigate to the working directory in your terminal.
2. Install bundler with gem install bundler (if running on macOS, your machine should already have Ruby installed).
3. In your terminal, run bundle install to install the dependencies.
4. This will generate a new file, Gemfile.lock, which contains the specific versions of the gems that were installed. If you're coming from the Node.js world, this Gemfile.lock file is similar to the package-lock.json file.
5. Finally, create the log directory with mkdir log to contain records of executing scripts

Create your .env file

THis script requires a few environment variables to be set. You can do this by creating a .env file in the working directory. I've created a .env.sample file to get started. Rename this file to be .env file, which should contain the following variables:

• GH_ORG= the name of the source organization, i.e. the organization from which you're transferring teams and repos
• GH_TARGET_ORG= the name of the destination organization, i.e. the organization to which you're transferring teams and repos
• GH_TOKEN= your personal access token. This should have the admin:org scope, and the user must be an org owner of both source and target orgs

Once you've finished editing these values, you should have a .env file in the working directory that looks like this:

GH_ORG=my-source-org
GH_TARGET_ORG=my-target-org
GH_TOKEN=ghp_1234abcd

For working GitHub Enterprise Server, you will need to set 2 additional environment variables based on your GHES deployment:

• GH_REST_URL= URL and path for making REST API calls
• GH_GRAPHQL_URL= URL and path for making GraphQL API calls

For example:

GH_GRAPHQL_API=https://0785a2994314098ba.example.com/api/graphql
GH_REST_API=https://0785a2994314098ba.example.com/api/v3

Migrating teams

For creating teams in the new, target organization, we'll need to create a list of the current teams in the source organization. This will be used to create the teams in the target organization, and to transfer the repositories owned by those source teams.

To start, run ruby get_teams.rb in your terminal from the working directory. This will generate a new file, teams.yml, which contains the team names and their corresponding members.

👉 Using this .yml file delete any top-level teams (and their child descendants) that you don't want to migrate.

Next, the create_teams.rb script will create new teams in the destination organization. A seperate script (see: Inviting members) will later be used to invite users to the organization and their respective team(s).

Once you've edited the teams.yml file, you can run ruby create_teams.rb again to create the teams in the destination organization.

👉 After you've successfully created teams in the target org, don't delete any teams in the source org until you're satisified and fully finished with team transfer exercise. There may be a case where we need to re-run scripts, which would depend on having an accurate source org.

Inviting members

The invite_members.rb script will invite all members of the source organization to the destination organization.

Note This script depends on the generated, and edited teams.yml file generated above.

Once you've migrated you've transferred your repos successfully, run ruby invite_members.rb in your terminal from the working directory. This will invite all members of the source organization to the destination organization.

Migrating repositories

The transfer_repos.rb script will transfer team-owned repositories from the source organization to the destination organization.

Two points to note

The transfer_repos.rb script will only transfer repositories that are owned by teams. If you want to transfer repositories that are owned by individuals, you'll have to do this manually, or we can devise a workaround for this - just let @apdarr know!

Once ready, run ruby transfer_repos.rb in your terminal from the working directory. This will start the transfer process for moving repos from source to target org. Any repos that can't be migrated due to exceptions listed here will be listed in the failed_repos.txt log file.

Additionally, the transfer_repos.rb script captures the team and user permissions on each repo in the source org. Based on the repos that have been transferred, the script then applies team and user access permissions to those repos. Note: this process will create a file called teams_access_by_repo.yaml, which is imply used by subsequent processing in the script.