About required access for GitHub Enterprise Importer
To protect your data, GitHub enforces specific access requirements to use GitHub Enterprise Importer. These requirements vary based on the task you are trying to perform. To prevent errors, you should review this article carefully and verify that you meet all of the requirements for the task you want to complete.
To migrate a repository from Bitbucket Server to GitHub, you need sufficient access to both the source (your Bitbucket Server instance) and the destination (an organization on GitHub). To have sufficient access, you'll need all of the following things.
- A required role in the destination organization on GitHub
- A personal access token that can access the destination organization on GitHub
- The personal access token must have all the required scopes, which depend on your role and the task you want to complete.
- If the destination organization uses SAML single sign-on for GitHub, you must authorize the personal access token for SSO.
- On Bitbucket Server, required permissions and SFTP or SMB access
Additionally, if you use IP allow lists in the destination organization, you may need to configure the allow lists to allow access by GitHub Enterprise Importer.
About the migrator role
To remove the need for organization owners to complete migrations, GitHub includes a distinct role for using GitHub Enterprise Importer. Granting the migrator role allows you to designate other teams or individuals to handle your migrations. You can only grant the migrator role for an organization on GitHub.com.
You can grant the migrator role to an individual user or a team. We strongly recommend that you assign the migrator role to a team. Then, you can further customize who can run a migration by adjusting team membership. For more information about changing team membership, see "Adding organization members to a team" or "Removing organization members from a team."
Warning
When you grant the migrator role in an organization to a user or team, you are granting them the ability to import or export any repository in that organization.
To grant the migrator role, see "Granting the migrator role."
After you grant the migrator role, make sure the migrator uses a personal access token that meets all the requirements for running migrations.
Required roles for GitHub
For the destination organization on GitHub, different roles are required for different tasks.
The following table lists which tasks can be performed by which role.
Task | Organization owner | Migrator |
---|---|---|
Assigning the migrator role for repository migrations | ||
Running a repository migration | ||
Downloading a migration log | ||
Reclaiming mannequins |
Required scopes for personal access tokens
To run a migration, you need a personal access token that can access the destination organization on GitHub.
The scopes that are required for your GitHub personal access token (classic) depend on your role and the task you want to complete.
Note: You can only use a personal access token (classic), not a fine-grained personal access token. This means that you cannot use GitHub Enterprise Importer if your organization uses the "Restrict personal access tokens (classic) from accessing your organizations" policy. For more information, see "Enforcing policies for personal access tokens in your enterprise."
Task | Organization owner | Migrator |
---|---|---|
Assigning the migrator role for repository migrations | admin:org | |
Running a repository migration (destination organization) | repo , admin:org , workflow | repo , read:org , workflow |
Downloading a migration log | repo , admin:org , workflow | repo , read:org , workflow |
Reclaiming mannequins | admin:org |
Required permissions for Bitbucket Server
To migrate from Bitbucket Server, you need:
- The username and password of a Bitbucket Server account that has admin or super admin permissions
- If your Bitbucket Server instances runs on Linux, SFTP access to the Bitbucket Server instance (see "SSH keys"). In general, if you can access the server via SSH, then you can also use SFTP.
- If your Bitbucket Server instance runs on Windows, file sharing (SMB) access to the Bitbucket Server instance
SSH keys
If your Bitbucket Server instance runs on Linux, you must use an SSH key that meets the following requirements:
- Does not have a passphrase
- Uses one of the following ciphers
aes256-ctr
3des-cbc
aes128-cbc
aes192-cbc
aes256-cbc
blowfish-cbc
twofish-cbc
twofish192-cbc
twofish128-cbc
twofish256-cbc
arcfour
arcfour128
arcfour256
cast128-cbc
aes128-ctr
aes192-ctr
If you receive an error like cipher name aes256-ctr for openssh key file is not supported
when running a migration, your SSH private key uses an unsupported cipher. For more information about how to generate a compatible private key, see "Troubleshooting your migration with GitHub Enterprise Importer."
Granting the migrator role
To allow someone other than an organization owner to run a migration or download migration logs, you can grant the migrator role to a user or team. For more information, see "About the migrator role."
You can grant the migrator role using either the BBS2GH extension of the GitHub CLI or the GraphQL API.
- "Granting the migrator role with the BBS2GH extension"
- "Granting the migrator role with the GraphQL API"
Granting the migrator role with the BBS2GH extension
To grant the migrator role using the CLI, you must have installed the BBS2GH extension of the GitHub CLI. For more information, see "Migrating repositories from Bitbucket Server to GitHub Enterprise Cloud."
-
On GitHub, create and record a personal access token that meets all the requirements for granting the migrator role. For more information, see "Creating a personal access token for GitHub Enterprise Importer."
-
Set the personal access token as an environment variable, replacing TOKEN in the commands below with the personal access token you recorded above.
-
If you're using Terminal, use the
export
command.Shell export GH_PAT="TOKEN"
export GH_PAT="TOKEN"
-
If you're using PowerShell, use the
$env
command.Shell $env:GH_PAT="TOKEN"
$env:GH_PAT="TOKEN"
-
-
Use the
gh bbs2gh grant-migrator-role
command, replacing ORGANIZATION with the organization you want to grant the migrator role for, ACTOR with the user or team name, and TYPE withUSER
orTEAM
.Shell gh bbs2gh grant-migrator-role --github-org ORGANIZATION --actor ACTOR --actor-type TYPE
gh bbs2gh grant-migrator-role --github-org ORGANIZATION --actor ACTOR --actor-type TYPE
Granting the migrator role with the GraphQL API
You can use the grantMigratorRole
GraphQL mutation to assign the migrator role and the revokeMigratorRole
mutation to revoke the migrator role.
You must use a personal access token (PAT) that meets all access requirements. For more information, see the "Required scopes for personal access tokens."
grantMigratorRole
mutation
This GraphQL mutation sets the migration role.
mutation grantMigratorRole (
$organizationId: ID!,
$actor: String!,
$actor_type: ActorType!
) {
grantMigratorRole( input: {
organizationId: $organizationId,
actor: $actor,
actorType: $actor_type
})
{ success }
}
Query variable | Description |
---|---|
organizationId | The ownerId (or organization ID) for your organization, from the GetOrgInfo query. |
actor | The team or username who you want to assign the migration role to. |
actor_type | Specify whether the migrator is a USER or TEAM . |
revokeMigratorRole
mutation
This mutation removes the migrator role.
mutation revokeMigratorRole (
$organizationId: ID!,
$actor: String!,
$actor_type: ActorType!
) {
revokeMigratorRole( input: {
organizationId: $organizationId,
actor: $actor,
actorType: $actor_type
})
{ success }
}
Creating a personal access token for GitHub Enterprise Importer
- Verify that you have a sufficient role for the task you want to complete. For more information, see "Required roles."
- Create a personal access token (classic), making sure to grant all the scopes required for the task you want to complete. You can only use a personal access token (classic), not a fine-grained personal access token. For more information, "Managing your personal access tokens" and "Required scopes for personal access token."
- If SAML single sign-on is enforced for the organization(s) you need to access, authorize the personal access token for SSO. For more information, see "Authorizing a personal access token for use with SAML single sign-on."
Configuring IP allow lists for migrations
If the destination of your migration uses an IP allow list (either GitHub's IP allow list feature or your identity provider's (IdP) IP allow list restrictions), you need to configure IP allow lists on GitHub.
- If you use GitHub's IP allow list feature, you must add the GitHub IP ranges below to the allow list for the destination organization.
- If you use your IdP's IP allow list to restrict access to your enterprise on GitHub, you should disable these restrictions in your enterprise account settings until after your migration is complete.
For more information, see "Managing allowed IP addresses for your organization" and "Restricting network traffic to your enterprise with an IP allow list."
Identifying GitHub's IP ranges
You'll need to add the following IP ranges to your IP allowlist(s):
- 192.30.252.0/22
- 185.199.108.0/22
- 140.82.112.0/20
- 143.55.64.0/20
- 40.71.233.224/28
- 2a0a:a440::/29
- 2606:50c0::/32
- 20.125.12.8/29 (active from 00:00 UTC on November 8, 2023)
You can get an up-to-date list of IP ranges used by GitHub Enterprise Importer at any time with the "Get GitHub meta information" endpoint of the REST API.
The github_enterprise_importer
key in the response contains a list of IP ranges used for migrations.
For more information, see "REST API endpoints for meta data."