Skip to content

Commit

Permalink
Merge pull request #5 from joshjohanning/update-readme
Browse files Browse the repository at this point in the history 
Update readme
  • Loading branch information
@joshjohanning
joshjohanning authored Oct 20, 2022
2 parents 8d7f199 + 70f0723 commit 5f68866
Show file tree
Hide file tree
Showing 3 changed files with 68 additions and 16 deletions.
26 changes: 23 additions & 3 deletions .github/workflows/migrate-work-items.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,10 +11,20 @@ on:
description: 'ado-project'
required: true
default: 'PartsUnlimited'
ado-tag:
description: 'ADO tag to migrate'
ado_area_path:
description: 'ADO area path to migrate - uses the UNDER operator'
required: true
default: 'migrate'
ado_migrate_closed_workitems:
description: 'Migrate closed work items'
required: true
type: boolean
default: 'true'
ado_production_run:
description: tag migrated work items with migrated-to-github and add discussion comment
required: true
type: boolean
default: 'true'
gh-org:
description: 'gh-org'
required: true
Expand Down Expand Up @@ -58,9 +68,19 @@ jobs:
# run migration script
# cleaning up bools
$ado_migrate_closed_workitems=$false
$ado_production_run=$false
$gh_update_assigned_to=$false
$gh_add_ado_comments=$false
if("${{ github.event.inputs.ado_migrate_closed_workitems }}" -eq "true") {
$ado_migrate_closed_workitems=$true
}
if("${{ github.event.inputs.ado_production_run }}" -eq "true") {
$ado_production_run=$true
}
if("${{ github.event.inputs.gh_update_assigned_to }}" -eq "true") {
$gh_update_assigned_to=$true
}
Expand All @@ -69,5 +89,5 @@ jobs:
$gh_add_ado_comments=$true
}
./ado_workitems_to_github_issues.ps1 -ado_pat "${{ SECRETS.ADO_PAT }}" -ado_org "${{ github.event.inputs.ado-org }}" -ado_project "${{ github.event.inputs.ado-project }}" -ado_tag "${{ github.event.inputs.ado-tag }}" -gh_pat "${{ steps.get_installation_token.outputs.token }}" -gh_org "${{ github.event.inputs.gh-org }}" -gh_repo "${{ github.event.inputs.gh-repo }}" -gh_update_assigned_to $gh_update_assigned_to -gh_assigned_to_user_suffix "${{ github.event.inputs.gh_assigned_to_user_suffix }}" -gh_add_ado_comments $gh_add_ado_comments
./ado_workitems_to_github_issues.ps1 -ado_pat "${{ SECRETS.ADO_PAT }}" -ado_org "${{ github.event.inputs.ado-org }}" -ado_project "${{ github.event.inputs.ado-project }}" -ado_area_path "${{ github.event.inputs.ado_area_path }}" -ado_migrate_closed_workitems $ado_migrate_closed_workitems -ado_production_run $ado_production_run -gh_pat "${{ steps.get_installation_token.outputs.token }}" -gh_org "${{ github.event.inputs.gh-org }}" -gh_repo "${{ github.event.inputs.gh-repo }}" -gh_update_assigned_to $gh_update_assigned_to -gh_assigned_to_user_suffix "${{ github.event.inputs.gh_assigned_to_user_suffix }}" -gh_add_ado_comments $gh_add_ado_comments
52 changes: 42 additions & 10 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,31 +1,32 @@
# ado_workitems_to_github_issues

## Notes

Just a heads up, if you have the `-gh_update_assigned_to` flag set to `$true`, you/your users will receive a lot of emails.
PowerShell script to migrate Azure DevOps work items to GitHub Issues

### Prerequisites

1. Install az devops and github cli where this is running (ie: action or locally; GitHub-hosted runners already have)
2. Create a label for EACH work item type that is being migrated (as lower case)
2. In GitHub, [create a label](https://docs.github.com/en/issues/using-labels-and-milestones-to-track-work/managing-labels) for EACH work item type that is being migrated (as lower case)
- ie: "user story", "bug", "task", "feature"
3. 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"
3. 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"`

### Things it migrates

1. Title
2. Description (or for a bug, repro steps and/or system info)
3. State (if the work item is done / closed, it will be closed in GitHub)
4. 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
6. Migrate acceptance criteria as part of issue body (if present)
7. Adds in the following as a comment to the issue:
5. Migrate acceptance criteria as part of issue body (if present)
6. 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
7. Creates tag "copied-to-github" and a comment on the ADO work item with `-$ado_production_run $true"`. The tag prevents duplicate copying.

### To Do
1. Create a comment on the Azure DevOps work item that says "Migrated to GitHub Issue #"
1. Provide user mapping option

### Things it won't ever migrate
1. Created date/update dates
Expand Down Expand Up @@ -58,5 +59,36 @@ The recommendation is to use a GitHub App to run the migration - a GitHub app ha
Using the GitHub app might be better so you don't reach a limit on your GitHub account on creating new issues 😀

```pwsh
./ado_workitems_to_github_issues.ps1 -ado_pat "xxx" -ado_org "jjohanning0798" -ado_project "PartsUnlimited" -ado_area_path "PartsUnlimited\migrate" -gh_pat "ghp_xxx" -gh_org "joshjohanning-org" -gh_repo "migrate-ado-workitems" -gh_update_assigned_to $true -gh_assigned_to_user_suffix "_corp" -gh_add_ado_comments $true
./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
```

## Script Options

| 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
6 changes: 3 additions & 3 deletions ado_workitems_to_github_issues.ps1
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@
# - You can modify the WIQL if you want to use a different way to migrate work items, such as [TAG] = "migrate"

# How to run:
# ./ado_workitems_to_github_issues.ps1 -ado_pat "xxx" -ado_org "jjohanning0798" -ado_project "PartsUnlimited" -ado_area_path "PartsUnlimited\migrate" -ado_migrate_closed_workitems $false -ado_production_run $true -gh_pat "xxx" -gh_org "joshjohanning-org" -gh_repo "migrate-ado-workitems" -gh_update_assigned_to $true -gh_assigned_to_user_suffix "_corp" -gh_migrate_ado_comments $true
# ./ado_workitems_to_github_issues.ps1 -ado_pat "xxx" -ado_org "jjohanning0798" -ado_project "PartsUnlimited" -ado_area_path "PartsUnlimited\migrate" -ado_migrate_closed_workitems $false -ado_production_run $true -gh_pat "xxx" -gh_org "joshjohanning-org" -gh_repo "migrate-ado-workitems" -gh_update_assigned_to $true -gh_assigned_to_user_suffix "_corp" -gh_add_ado_comments $true

#
# Things it migrates:
Expand Down Expand Up @@ -44,7 +44,7 @@ param (
[string]$gh_repo, # GitHub repository to create the issues in
[bool]$gh_update_assigned_to = $false, # try to update the assigned to field in GitHub
[string]$gh_assigned_to_user_suffix = "", # the emu suffix, ie: "_corp"
[bool]$gh_migrate_ado_comments = $false # try to get ado comments
[bool]$gh_add_ado_comments = $false # try to get ado comments
)

# Set the auth token for az commands
Expand Down Expand Up @@ -133,7 +133,7 @@ ForEach($workitem in $query) {
$original_workitem_json_end | Add-Content -Path ./temp_comment_body.txt -Encoding ASCII;

# getting comments if enabled
if($gh_migrate_ado_comments -eq $true) {
if($gh_add_ado_comments -eq $true) {
$headers = New-Object "System.Collections.Generic.Dictionary[[String],[String]]"
$base64 = [Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes(":$ado_pat"))
$headers.Add("Authorization", "Basic $base64")
Expand Down

0 comments on commit 5f68866

Please sign in to comment.