PowerShell script to migrate Azure DevOps work items to GitHub Issues
- Install az devops and github cli where this is running (ie: action or locally; GitHub-hosted runners already have)
- In GitHub, create a label for EACH work item type that is being migrated (as lower case)
- ie: "user story", "bug", "task", "feature"
- Define under what area path you want to migrate
- You can modify the WIQL if you want to use a different way to migrate work items, such as
[TAG] = "migrate"
- You can modify the WIQL if you want to use a different way to migrate work items, such as
- Title
- Description (or for a bug, repro steps and/or system info)
- State (if the work item is done / closed, it will be closed in GitHub)
- It will try to assign the work item to the correct user in GitHub - based on ADO email before the
@
- This uses the
-gh_update_assigned_to
and-gh_assigned_to_user_suffix
options - Users have to be added to GitHub org
- This uses the
- Migrate acceptance criteria as part of issue body (if present)
- Adds in the following as a comment to the issue:
- Original work item url
- Basic details in a collapsed markdown table
- Entire work item as JSON in a collapsed section
- Creates tag "copied-to-github" and a comment on the ADO work item with
-$ado_production_run $true"
. The tag prevents duplicate copying.
- Provide user mapping option
- Created date/update dates
The recommendation is to use a GitHub App to run the migration - a GitHub app has higher rate limits than using a user PAT.
- Create GitHub App with (can use this reference). Use the following permissions:
- Repo:
Contents:Read
- Repo:
Issues:Read and write
- Org:
Members:Read
- Repo:
- Create Private Key for GitHub App
- Obtain App ID and Installation ID - see the instructions for using smee.io
- Create the following action secrets:
ADO_PAT
: Azure DevOps PAT with appropriate permissions to read work itemsPRIVATE_KEY
: The contents of the private key created and downloaded in step #2
- Use the action and update the App ID and Installation ID obtained in step #3
- Update any defaults in the action (ie: Azure DevOps organization and project, GitHub organization and repo)
- Ensure the action exists in the repo's default branch
- Run the workflow
Using the GitHub app might be better so you don't reach a limit on your GitHub account on creating new issues ๐
./ado_workitems_to_github_issues.ps1 `
-ado_pat "abc" `
-ado_org "jjohanning0798" `
-ado_project "PartsUnlimited" `
-ado_area_path "PartsUnlimited\migrate" `
-ado_migrate_closed_workitems $false `
-ado_production_run $false `
-gh_pat "ghp_xxx" `
-gh_org "joshjohanning-org" `
-gh_repo "migrate-ado-workitems" `
-gh_update_assigned_to $true `
-gh_assigned_to_user_suffix "" `
-gh_add_ado_comments $true
Parameter | Required | Default | Description |
---|---|---|---|
-ado_pat |
Yes | Azure DevOps Personal Access Token (PAT) with appropriate permissions to read work items (and update, with -ado_production_run $true ) |
|
-ado_org |
Yes | Azure DevOps organization to migrate from | |
-ado_project |
Yes | Azure DevOps project to migrate from | |
-ado_area_path |
Yes | Azure DevOps area path to migrate from - uses the UNDER operator |
|
-ado_migrate_closed_workitems |
No | $false |
Switch to migrate closed/resoled/done/removed work items |
-ado_production_run |
No | $false |
Switch to add copied-to-github tag and comment on ADO work item |
-gh_pat |
Yes | GitHub Personal Access Token (PAT) with appropriate permissions to read/write issues | |
-gh_org |
Yes | GitHub organization to migrate work items to | |
-gh_repo |
Yes | GitHub repo to migrate work items to | |
-gh_update_assigned_to |
No | $false |
Switch to update the GitHub issue's assignee based on the username portion of an email address (before the @ sign) |
-gh_assigned_to_user_suffix |
No | "" |
Used in conjunction with -gh_update_assigned_to , used to suffix the username, e.g. if using GitHub Enterprise Managed User (EMU) instance |
-gh_add_ado_comments |
No | $false |
Switch to add ADO comments as a section with the migrated work item |
- Note: With
-gh_update_assigned_to $true
, you/your users will receive a lot of emails from GitHub when the user is assigned to the issue