GEI-Teams and Permissions

Part 5 — Teams and Permissions

This is #5 in a series of articles explaining how to use the GitHub Enterprise Importer (gei) to migrate repos from Azure DevOps to GitHub. If you have not already done so you should read this article first to get yourself set up, so you can try the examples.

Here are the preceding articles:

1. GitHub Enterprise Importer (GEI)
2. GEI-Generate Script & Inventory Report Commands
3. GEI-Migrate Repo
4. GEI-Rewire Azure Pipelines

Now that we have migrated a repo and rewired it’s pipelines lets talk about adding Teams and giving them permission to our new Repo.

To do this we need to take a look at a couple of commands in the gei including create-team and add-team-to-repo.

create-team

The create team command does just that, it creates a team in GitHub. This is one of those commands that may or may not be useful. It depends on how you provision teams in GitHub. That is a much bigger discussion. So for now lets just see what this command can do for us.

create-team has two required arguments GitHub Org and Team Name. So you can simply create a team in your Organization like this.

gh ado2gh create-team --github-org "MyShuttle" --team-name "Developers"

If you are using SAML to centrally manage access to your enterprise via an Identity Provider like AAD or Okta. You can use the idp-group argument to link the IdP group to your team automatically. Lets not get into that now here is some information About authentication for your enterprise.

gh ado2gh create-team `
  --github-org "MyShuttle" `
  --team-name "Developers" `
  --idp-group "Identity Provider Group"

add-team-to-repo

This is a useful command. The add-team-to-repo command will add a team to a repo with the permissions you specify.

The add-team-to-repo command has 4 required arguments. The GitHub Org, Repo, Team and the role you want them to have on this repo.

gh ado2gh add-team-to-repo `
    --github-org "MyShuttle" `
    --github-repo "New-ShuttleService" `
    --team "Developers" `
    --role "push"

The role must be one of the standard GitHub roles or the name of a custom role created by your org administrator.

The standard roles include:

When setting permissions using the gei tool Read is passed in as pull and Write is push. The same as the API.

I have a script for doing this with the Rest API. So if you want to use that instead take a look at this article. Granting a team permission to a GitHub repo using the API and PowerShell.

Lets add this to our main deployment script.

param (
    [Parameter(Mandatory=$true)] $ado_repo,
    [Parameter(Mandatory=$true)] $ado_project,
    $ado_build, # Only required if the build is not a determinable name
    $gh_repo # Only Required when Repo should not be prefixed with the project
)
# check to make sure we have the required Tokens for access to GitHub and AzDO
if (!$env:ADO_PAT) {
    write-host "Missing ADO_PAT Environment Variable"
    exit
}

if (!$env:GH_PAT) {
    write-host "Missing GH_PAT Environment Variable"
    exit
}

# These might need to be paramaters depending on your situation
$ado_org="dlloyd"
$gh_org="GHShuttle"
# Service Connection Id
$serviceConnectionId="TheIdCopiedFromTheServiceConnection"

# if gh_repo was supplied use that for the GitHub Repo Name 
# otherwise use the ADO repo name prefixed with the ADO Project Name
if ( !$gh_repo ) { $gh_repo="$ado_project-$ado_repo" }

# if ado_build is supplied us that for the build name
# otherwise use whatever cosistant pattern you have for pipeline names
# ie same as the repo name
if ( !$ado_build ) {$ado_build=$ado_repo}

# Make the ADO Repo read only (Optional)
gh ado2gh lock-ado-repo `
  --ado-org "$ado_org" `
  --ado-team-project "$ado_project" `
  --ado-repo "$ado_repo"

# Migrate the Repo
gh ado2gh migrate-repo `
  --ado-org "$ado_org" `
  --ado-team-project "$ado_project" `
  --ado-repo "$ado_repo" `
  --github-org "$gh_org" `
  --github-repo "$gh_repo" `
  --wait

if ($LASTEXITCODE -eq 1)
{
    write-host "Migration Failed" -ForegroundColor Red
}
else
{
  write-host "Migration Successful" -ForegroundColor Green
  # Disable the ADO repo 
  gh ado2gh disable-ado-repo `
    --ado-org "$ado_org" `
    --ado-team-project "$ado_project" `
    --ado-repo "$ado_repo"

  # Rewire the pipeline to the new build 
  gh ado2gh rewire-pipeline `
    --ado-org "$ado_org" `
    --ado-team-project "$ado_project" `
    --ado-pipeline "$ado_build" `
    --github-org "$gh_org" `
    --github-repo "$gh_repo" `
    --service-connection-id "$serviceConnectionId"

  # Create the Developers team
  gh ado2gh create-team --github-org "$gh_org" --team-name "Developers"

  # Give Developers push/write access to the repo 
  gh ado2gh add-team-to-repo `
    --github-org "$gh_org" `
    --github-repo "$gh_repo" `
    --team "Developers" `
    --role "push"

  # Create the Developers team
  gh ado2gh create-team --github-org "$gh_org" --team-name "Architects"

  # Give Architects maintain access to the repo
  gh ado2gh add-team-to-repo `
    --github-org "$gh_org" `
    --github-repo "$gh_repo" `
    --team "Architects" `
    --role "maintain"
}

Calling create-team each time is actually unnecessary. Once they are created you will likely re-use them for each repo you migrate.

However this script will still work because if the team already exists the command just lets you know, but doesn’t fail.

gh ado2gh create-team --github-org "MyShuttle" --team-name "Developers"
[3:45 PM] [INFO] You are running the latest version of the ado2gh CLI [v0.32]
[3:45 PM] [INFO] Creating GitHub team...
[3:45 PM] [INFO] GITHUB ORG: MyShuttle
[3:45 PM] [INFO] TEAM NAME: Developers
[3:45 PM] [INFO] IDP GROUP:
[3:45 PM] [INFO] Team 'Developers' already exists - New team will not be created
[3:45 PM] [INFO] No IdP Group provided, skipping the IdP linking step

There you have it a script that will:

1. Migrate a Repo from Azure DevOps to GitHub
2. Disable the old repo in Azure DevOps
3. Rewire a pipeline to the new repo in GitHub
4. Add Teams to GitHub
5. Give those teams access to the new repo