gh-migrate-teams

README

gh-migrate-teams

gh-migrate-teams is a GitHub CLI extension to assist in the migration of teams between GitHub organizations. GitHub Enterprise Importer provides an excellent feature set when migrating organizations, but there are some gaps when it comes to migrating teams. This extension aims to fill those gaps. Wether you are consolidating organizations in an EMU, or auditing teams and collaborators in an existing organization, this extension can help.

Install

gh extension install mona-actions/gh-migrate-teams

[!NOTE] If setting any environmental variables through this CLI extension, make sure to add the GHMT prefix. For example, GHMT_TOKEN instead of TOKEN.

Usage: Export

Export team membership, team repository access, and repository collaborator access to CSV files.

Usage:
  migrate-teams export [flags]

Flags:
  -f, --file-prefix string    Output filenames prefix
  -h, --help                  help for export
  -u, --hostname string       GitHub Enterprise hostname url (optional) Ex. https://github.example.com
  -o, --organization string   Organization to export
  -t, --token string          GitHub token

Usage: Sync

Recreates teams, membership, and team repo roles from a source organization to a target organization

Usage:
  migrate-teams sync [flags]

Flags:
  -h, --help                         help for sync
  -m, --mapping-file string          Mapping file path to use for mapping teams members handles
   -k, --skip-teams                   Skips adding members and repos to teams that already exist to save on API requests (default "false")
  -u, --source-hostname string       GitHub Enterprise source hostname url (optional) Ex. https://github.example.com
  -s, --source-organization string   Source Organization to sync teams from
  -a, --source-token string          Source Organization GitHub token. Scopes: read:org, read:user, user:email
  -t, --target-organization string   Target Organization to sync teams from
  -b, --target-token string          Target Organization GitHub token. Scopes: admin:org
  -z, --user-sync string             User sync mode. One of: all, disable (default "none") (default "all")

Sync by Repository List

You can also sync teams by providing a list of repositories to sync. This is useful when you want to sync a subset of repositories from the source organization to the target organization.

Usage:
  migrate-teams sync byRepos [flags]

Flags:
  -f, --from-file string             File path to use for repository list (default "repositories.txt")
  -h, --help                         help for byRepos
  -r, --include-all-repos            Include all repositories that teams had access to in source, not just those in the migration list (default "false")
  -m, --mapping-file string          Mapping file path to use for mapping teams members handles
  -k, --skip-teams                   Skips adding members and repos to teams that already exist to save on API requests (default "false")
  -u, --source-hostname string       GitHub Enterprise source hostname url (optional) Ex. https://github.example.com
  -a, --source-token string          Source Organization GitHub token. Scopes: read:org, read:user, user:email
  -i, --target-app-id string         GitHub App ID
  -l, --target-installation-id int   GitHub App Installation ID
  -t, --target-organization string   Target Organization to sync teams from
  -p, --target-private-key string    Private key for GitHub App authentication. Ideally set as an env variable: 'GHMT_TARGET_PRIVATE_KEY'
  -b, --target-token string          Target Organization GitHub token. Scopes: admin:org

[!Note] If using GitHub App authentication, the GitHub App's Private Key needs to be set as an environment variable GHMT_TARGET_PRIVATE_KEY to avoid passing it directly in the command line.

Repository List Example

owner/repo
https://github.example.com/owner/repo

Mapping File Example

A mapping file can be provided to map member handles in case they are different between source and target.

Example:

source,target
flastname,firstname.lastname

License

• MIT (c) Mona-Actions
• Contributing

Documentation

Overview

Copyright © 2023 NAME HERE <EMAIL ADDRESS>