diff --git a/ado_workitems_to_github_issues.ps1 b/ado_workitems_to_github_issues.ps1
index f9d85bc..1a430d3 100644
--- a/ado_workitems_to_github_issues.ps1
+++ b/ado_workitems_to_github_issues.ps1
@@ -1,12 +1,16 @@
+#! /usr/bin/env pwsh
+
##############################################################
# Migrate Azure DevOps work items to GitHub Issues
##############################################################
# Prerequisites:
# 1. Install az devops and github cli
-# 2. create a label for EACH work item type that is being migrated (as lower case)
+# 2. [optional]Create a label 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
+# a. The ADO item type to Github label can be explicit via the config JSON key "azureDevOpsItemTypeToGitHubLabelMap"
+# b. The labels can be automatically created with `-gh_ensure_labels_exist 1` CLI option (currently the default)
+# 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"
# How to run:
@@ -17,13 +21,35 @@
# 1. Title
# 2. Description (or repro steps + system info for a bug)
# 3. State (if the work item is done / closed, it will be closed in GitHub)
+# a. The state can also be mapped to a Github V2 Project "Status" column using config JSON key "azureDevOpsStateToGitHubProjectColumnMap", however the columns must exist
# 4. It will try to assign the work item to the correct user in GitHub - based on ADO email (-gh_update_assigned_to and -gh_assigned_to_user_suffix options) - they of course have to be in GitHub already
+# a. There is also an option to explicitly map users from ADO to GitHub via the config JSON key "azureDevOpsEmailToGitHubAssigneeMap"
# 5. Migrate acceptance criteria as part of issue body (if present)
# 6. Adds in the following as a comment to the issue:
-# a. Original work item url
+# a. Original work item url
# b. Basic details in a collapsed markdown table
# c. 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.
+# d. Related items as shield.io badges (and in collapsed markdown table)
+# - Mentions parent issue from child issue for some GitHub linkage
+# 7. Milestone (from an Azure DevOps Iteration)
+# 8. Adds issue as a card to Github v2 Project (although V2 projects can have workflows themselves to add new issues)
+# a. Note that the Github PAT needs project:write scope (handled automatically via `gh auth login`)
+# 9. Labels (from Azure DevOps tags) provided they are mapped in a config JSON under the key "azureDevOpsTagsToGitHubLabelsMap"
+# 10. Creates tag "copied-to-github" and a comment on the ADO work item with `-$ado_production_run $true` . The tag prevents duplicate copying.
+#
+
+#
+# Supports partial migration / resuming previous migration
+# 1. Uses a checkpoint file (if specified) to know the ADO URL to GitHub Issue URL mappings it has migrated
+# 2. Attempts to use `az devops` and `gh` CLIs to cross reference existing issues based on title and maps to the earliest issue when found
+# - This is only performed for unmapped URLs that are not in the checkpoint - with a warning emitted, use -Debug CLI flag to see details
+# 3. Will reattempt to create an issue (every 15 mins, waiting up to 1.5 hours) to workaround GitHub API rate limit throttling
+#
+
+#
+# Notes
+# 1. Unicode such as emojis are now supported for labels, descriptions, etc as the default encoding is now UTF-8
+# 2. A temporary directory is created for errors and posted files and arranged by ADO workitem number to allow manual inspection of content after the fact, e.g. AB1.temp_issue_body.txt etc.
#
#
@@ -37,16 +63,321 @@ param (
[string]$ado_org, # Azure devops org without the URL, eg: "MyAzureDevOpsOrg"
[string]$ado_project, # Team project name that contains the work items, eg: "TailWindTraders"
[string]$ado_area_path, # Area path in Azure DevOps to migrate; uses the 'UNDER' operator)
- [bool]$ado_migrate_closed_workitems = $false, # migrate work items with the state of done, closed, resolved, and removed
- [bool]$ado_production_run = $false, # tag migrated work items with 'migrated-to-github' and add discussion comment
+ [System.ComponentModel.DefaultValueAttribute($false)]$ado_migrate_closed_workitems = $false, # migrate work items with the state of done, closed, resolved, and removed
+ [System.ComponentModel.DefaultValueAttribute($false)]$ado_production_run = $false, # tag migrated work items with 'migrated-to-github' and add discussion comment
[string]$gh_pat, # GitHub PAT
[string]$gh_org, # GitHub organization to create the issues in
[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_project_name = $null, # GitHub V2 project to associate issues with
+ [System.ComponentModel.DefaultValueAttribute($false)]$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_add_ado_comments = $false # try to get ado comments
+ [System.ComponentModel.DefaultValueAttribute($false)]$gh_add_ado_comments = $false, # try to get ado comments
+ [string]$gh_milestone_iteration_name_prefix = "", # milestone name prefix when importanting iteration names from Azure DevOps
+ [System.ComponentModel.DefaultValueAttribute($false)]$gh_ensure_labels_exist = $true, # ensure that the labels exist in the GitHub repo
+ [string[]]$gh_labels = @("ado-export 📤"), # define an array of label strings to be added to the issue
+ [string]$ado_to_gh_workitem_checkpoint_file = $null, # path to a JSON file to write the ADO work item ID and GitHub issue URL to
+ [System.ComponentModel.DefaultValueAttribute($false)]$sync_ado_iterations_to_gh_milestones = $true, # sync Azure DevOps iterations to GitHub milestones
+ [System.ComponentModel.DefaultValueAttribute($false)]$gh_mention_related_items = $false, # mention related items in the issue body, use with caution as these cannot be removed once added
+ [System.ComponentModel.DefaultValueAttribute($false)]$gh_update_existing_issues = $true, # update existing issues with new information
+ [string]$gh_archive_closed_items_label = "archive 🗃️", # marked closed items as archived the provided label, empty avoids adding a label
+ [System.ComponentModel.DefaultValueAttribute($false)]$gh_deduplicate_existing_issues = $true, # deduplicate existing issues based on title. WARNING: potentially dangerous as it will take the latest issue when deduplicating
+ [System.ComponentModel.DefaultValueAttribute($false)]$gh_wait_for_rate_limit_reset = $true, # wait for the GitHub API rate limit to reset before continuing, useful for large migrations but slow as it waits for 1 hour to allow the rate limit to reset
+ [string]$config_file = $null, # path to a JSON file to load configuration from, see MigrationConfig::ImportConfig for fields supported
+ [int32]$ado_start_workitem_id = 0 # the Azure DevOps work item ID to start from, useful for resuming a migration
)
+# set default encoding to UTF8 to be compatible with unicode characters returned from the GitHub API
+$PSDefaultParameterValues = @{ "*:Encoding" = "utf8" }
+[Console]::OutputEncoding = [Console]::InputEncoding = $OutputEncoding = [System.Text.Encoding]::UTF8
+
+$script:TEMPORARY_DIRECTORY = New-TemporaryFile | ForEach-Object {
+ Remove-Item $_ -Force; (New-Item -ItemType Directory -Path $_).FullName
+}
+Write-Debug "Temporary directory: $TEMPORARY_DIRECTORY"
+
+# save map to json
+function Save-MapToJSON() {
+ [CmdletBinding()]
+ param(
+ [Parameter(Mandatory = $true)]
+ [string]$path,
+ [Parameter(Mandatory = $true)]
+ [hashtable]$map
+ )
+ if ($path) {
+ $json = $map | ConvertTo-Json
+ $json | Out-File -FilePath $path -Encoding utf8
+ Write-Debug "Map saved to '$path'"
+ }
+}
+
+# load map from json
+function Import-MapFromJSON() {
+ [CmdletBinding()]
+ param(
+ [Parameter(Mandatory = $true)]
+ [string]$path,
+ [bool]$backup = $true,
+ [string]$encoding = "utf8"
+ )
+ # load a map from json if path exists, otherwise gracefully return an empty map
+ $map = @{}
+ if ($path -and (Test-Path -Path $path)) {
+ # construct backup path based on date
+ if ($backup) {
+ $backupPath = $path -replace "\.json$", ("_" + (Get-Date -Format "yyyyMMddHHmmss") + ".json")
+ Copy-Item -Path $path -Destination $backupPath
+ }
+ $json = Get-Content -Path $path -Raw -Encoding $encoding
+ try {
+ $obj = $json | ConvertFrom-Json
+ $obj.PSObject.Properties | ForEach-Object {
+ $map[$_.Name] = $_.Value
+ }
+ }
+ catch {
+ Write-Warning "Failed to load map from json file '$path' - using empty map..."
+ }
+ }
+ else {
+ throw "A valid path is required"
+ }
+ return $map
+}
+
+function ConvertTo-OrderedDictionary() {
+ [CmdletBinding()]
+ param(
+ [Parameter(Mandatory = $true)]
+ [object]$obj
+ )
+ $map = @{}
+ $obj.PSObject.Properties | ForEach-Object {
+ $map[$_.Name] = $_.Value
+ }
+ return $map
+}
+
+function Get-GitHubRepoInfo() {
+ param(
+ [Parameter(Mandatory = $true)]
+ [string]$org,
+ [Parameter(Mandatory = $true)]
+ [string]$repo
+ )
+ $repoInfo = gh repo view $org/$repo --json="${script:GITHUB_REPO_JSON_FIELDS}" | ConvertFrom-JSON
+ return $repoInfo
+
+}
+
+function Get-GithubProjectFromName() {
+ param(
+ [string]$projectName, # the name of the project to get the number for, e.g. "My Project"
+ [string]$githubOrg # the name of the github org to get the project number for, e.g. "MyOrg"
+ )
+ $projects = (gh project list --owner $githubOrg --format json | ConvertFrom-Json).projects
+ $project = $projects | Where-Object { $_.title -eq "$projectName" }
+ return $project
+}
+
+class GithubProject {
+ [Int32]$number
+ [System.Uri]$url
+ [string]$shortDescription
+ [bool]$public
+ [bool]$closed
+ [string]$title
+ [string]$id
+ [PSCustomObject]$items
+ [PSCustomObject]$fields
+ [PSCustomObject]$owner
+ [string]$readme
+
+ GithubProject($projectName, $githubOrg) {
+ $proj = Get-GithubProjectFromName -projectName $projectName -githubOrg $githubOrg
+ echo $proj
+ if (!$proj) {
+ $proj = gh project create --title="$projectName" --owner=$githubOrg --format=json | ConvertFrom-JSON
+ }
+
+ if (!$proj) {
+ throw "No GitHub project named '${projectName}'."
+ }
+
+ foreach ($field in $proj.PSObject.Properties) {
+ $this."$($field.Name)" = $field.Value
+ }
+ }
+}
+
+
+class MigrationState {
+ [PSCustomObject[]]$azureDevOpsItemsQuery = @()
+ [hashtable]$azureDevOpsWorkItemUrlToGitHubIssueUrlMap = @{}
+ [hashtable]$githubPullRequestInfo = @{}
+ [GithubRepository]$githubRepositoryInfo = (Get-GitHubRepoInfo -org $gh_org -repo $gh_repo)
+ [hashtable]$history = @{}
+ [GithubProject]$githubProject = [GithubProject]::new($gh_project_name, $gh_org)
+
+ [string]$PULL_REQUEST_JSON_FIELDS = "number,url,title,state,mergeable,milestone,reviews,author,assignees,body,comments,commits,changedFiles,baseRefName,headRepository,projectCards,projectItems,labels,createdAt,updatedAt"
+
+ [hashtable] GetGitHubPullRequestInfo([bool]$all = $true) {
+ $additionalFlags = "--limit 10000"
+ if ($all) {
+ additionalFlags += " --search='state:open -or state:closed -or state:merged'"
+ }
+ $pullRequestInfo = gh pr list $additionalFlags --json="$($this.PULL_REQUEST_JSON_FIELDS)" | ConvertFrom-JSON
+ $map = @{}
+ if ($pullRequestInfo) {
+ $pullRequestInfo.PSObject.Properties | ForEach-Object {
+ $map[$_.Value.url] = $this.githubPullRequestInfo[$_.Value.url] = $_.Value
+ }
+ }
+ return $map
+ }
+
+ [string] GetGitHubPullRequestState([string]$url) {
+ # check the GitHub repository information first before falling back to viewing the pr directly through the API
+ if (!$this.githubPullRequestInfo) {
+ $this.githubPullRequestInfo = $this.GetGitHubPullRequestInfo($true)
+ }
+ $state = $this.githubPullRequestInfo[$url] | Select-Object -ExpandProperty state
+ if (!$state) {
+ $pr = gh pr view $url --json "$this.PULL_REQUEST_JSON_FIELDS" | ConvertFrom-JSON
+ $this.githubPullRequestInfo[$url] = $pr # update map
+ $state = $pr.state
+ }
+ return $state
+ }
+
+ [PSCustomObject[]] GetAzureDevOpsItems(
+ $azureDevOpsAreaPath = $ado_area_path, `
+ [int32]$startWorkItemId = 0, `
+ [bool]$onlyClosedItems = $ado_migrate_closed_workitems
+ ) {
+ # get a list of board work items to migrate from Azure DevOps, but chunk in 1000 item batches
+ # add the wiql to not migrate closed work items
+ if ($onlyClosedItems -eq "1") {
+ $closedSubquery = "[State] <> 'Done' and [State] <> 'Closed' and [State] <> 'Resolved' and [State] <> 'Removed' and"
+ }
+ else {
+ $closedSubquery = "[State] != 'N/A' and"
+ }
+ $cursorId = $startWorkItemId - 0
+ $query = @()
+ while ($true) {
+ $wiql = "select [ID], [Title], [System.Tags] from workitems where [ID] > $cursorId "
+ $wiql += "and $closedSubquery [System.AreaPath] UNDER '$azureDevOpsAreaPath' "
+ $wiql += "and not [System.Tags] Contains 'copied-to-github' order by [ID] ASC";
+
+ $queryChunk = az boards query --wiql $wiql | ConvertFrom-Json
+ if (!$cursorId) {
+ $query = $queryChunk
+ }
+ else {
+ $query += $queryChunk
+ }
+
+ if ($queryChunk.Count -lt 1000) {
+ break
+ }
+ $cursorId = ($query | Measure-Object -Property id -Maximum).Maximum
+ }
+ $this.azureDevOpsItemsQuery = $query
+ return $query
+ }
+
+ static [MigrationState] ImportState([string]$path) {
+ [MigrationState]$state = [MigrationState]::new()
+ try {
+ $state.azureDevOpsWorkItemUrlToGitHubIssueUrlMap = Import-MapFromJSON -path "$path"
+ }
+ catch {
+ Write-Warning "Failed to load state from json file '$path' - using empty state..."
+ }
+ return $state
+ }
+}
+
+class MigrationConfig {
+ [hashtable]$azureDevOpsItemTypeToGitHubLabelMap = @{}
+ [hashtable]$azureDevOpsItemStateToGitHubLabelMap = @{}
+ [hashtable]$azureDevOpsStateToGitHubProjectColumnMap = @{}
+ [hashtable]$azureDevOpsEmailToGitHubAssigneeMap = @{}
+ [hashtable]$azureDevOpsTagsToGitHubLabelsMap = @{}
+ [hashtable]$vsftsRepoInternalIdMap = @{}
+
+ [void]UpdateItemStateToLabelMap([bool]$overwrite = $false) {
+ # dynamically create the map of ADO states to GitHub labels
+ foreach ($item in $this.azureDevOpsStateToGitHubProjectColumnMap.GetEnumerator()) {
+ if ($overwrite -or !$this.azureDevOpsItemStateToGitHubLabelMap[$item.Key]) {
+ $this.azureDevOpsItemStateToGitHubLabelMap[$item.Key] = $item.Value
+ }
+ }
+ }
+
+ static [MigrationConfig]ImportConfig([string]$path = "$config_file") {
+ $config = [MigrationConfig]::new()
+ try {
+ $jsonConfig = Import-MapFromJSON -path $path -ErrorAction Stop
+ }
+ catch {
+ Write-Warning "Failed to load config from json file '$path' - using empty config..."
+ $jsonConfig = @{}
+ }
+ $fields = @(
+ "azureDevOpsItemTypeToGitHubLabelMap",
+ "azureDevOpsItemStateToGitHubLabelMap",
+ "azureDevOpsStateToGitHubProjectColumnMap",
+ "azureDevOpsEmailToGitHubAssigneeMap",
+ "azureDevOpsTagsToGitHubLabelsMap",
+ "vsftsRepoInternalIdMap"
+ )
+ foreach ($field in $fields) {
+ # Do not clobber existing config data if the imported data is empty for a given field
+ if (!$jsonConfig[$field]) {
+ Write-Warning "Config field '$field' is empty"
+ $jsonConfig[$field] = @{}
+ }
+ else {
+ $config."$field" = ConvertTo-OrderedDictionary -obj $jsonConfig[$field]
+ }
+ }
+ $config.UpdateItemStateToLabelMap($false)
+ return $config
+ }
+}
+
+# Load the migration state if provided
+$script:state = [MigrationState]::ImportState("$ado_to_gh_workitem_checkpoint_file")
+
+# Load the config file if provided
+${script:config} = [MigrationConfig]::ImportConfig("$config_file")
+
+# generate a function which takes a hashtable of user email addresses to user displayNames from Azure DevOps and attempts to map them to GitHub usernames
+# This is tricky as GitHub usernames are not related to email addresses, so attempt a fuzzy match based on displayName
+function Get-MapAzureDevOpsEmailToGitHubAssigneeMap() {
+ param(
+ [Parameter(Mandatory = $true)]
+ [hashtable]$azureDevOpsUsersMap
+ )
+ $azureDevOpsEmailToGitHubAssigneeMap = @{}
+ foreach ($email in $azureDevOpsUsersMap.Keys) {
+ $displayName = $azureDevOpsUsersMap[$email]
+ $githubUsername = ${script:config}.azureDevOpsEmailToGitHubAssigneeMap[$email]
+ if ($githubUsername) {
+ $azureDevOpsEmailToGitHubAssigneeMap[$email] = $githubUsername
+ }
+ else {
+ $githubUsername = $displayName -replace " ", "-"
+ $githubUsername = $githubUsername -replace "[^a-zA-Z0-9-]", ""
+ $githubUsername = $githubUsername.ToLower()
+ $azureDevOpsEmailToGitHubAssigneeMap[$email] = $githubUsername
+ }
+ }
+ return $azureDevOpsEmailToGitHubAssigneeMap
+}
+
# Set the auth token for az commands
$env:AZURE_DEVOPS_EXT_PAT = $ado_pat;
# Set the auth token for gh commands
@@ -54,147 +385,1207 @@ $env:GH_TOKEN = $gh_pat;
az devops configure --defaults organization="https://dev.azure.com/$ado_org" project="$ado_project"
-# add the wiql to not migrate closed work items
-if (!$ado_migrate_closed_workitems) {
- $closed_wiql = "[State] <> 'Done' and [State] <> 'Closed' and [State] <> 'Resolved' and [State] <> 'Removed' and"
+# check that extensions are installed and install them if not
+$installedGitHubExtensions = gh extensions list
+foreach ($extension in @("github/gh-projects", "valeriobelli/gh-milestone")) {
+ if ($installedGitHubExtensions | Where-Object { $_ -notmatch $extension }) {
+ gh extensions install $extension
+ }
}
-$wiql = "select [ID], [Title], [System.Tags] from workitems where $closed_wiql [System.AreaPath] UNDER '$ado_area_path' and not [System.Tags] Contains 'copied-to-github' order by [ID]";
+function Convert-AzureDevOpsLinkUrl() {
+ param(
+ [Parameter(Mandatory = $true)]
+ [string]$url, # the Azure DevOps URL link to resolve
+ [bool]$useMappedUrl = $false # use the mapped issue URL rather than the original URL
+ )
-$query=az boards query --wiql $wiql | ConvertFrom-Json
+ $github_url = ${script:state}.azureDevOpsWorkItemUrlToGitHubIssueUrlMap[$url]
+ if ($useMappedUrl -and $github_url) {
+ return $github_url # used the mapped issue URL rather than the original URL
+ }
+
+ # check whether the URL is an internal API Azure DevOps URL and resolve it to a public URL
+ if ($url -match "https://dev.azure.com/" -and $url -match "/_apis/wit/workItems/") {
+ $url_encoded_ado_org = $ado_org -replace " ", "%20" -replace "#", "%23"
+ $url_encoded_ado_project = $ado_project -replace " ", "%20" -replace "#", "%23"
+ $item = Get-ItemNumberFromUrl -url $url
+ $devops_url = "https://dev.azure.com/$url_encoded_ado_org/$url_encoded_ado_project/_workitems/edit/$item"
+ return $devops_url
+ }
+
+ # check whether the URL is a valid VSTS URL by checking for "vstfs://" scheme
+ if ($url -notmatch "^vstfs:///GitHub") {
+ return $url # do not resolve non-VSTS URLs
+ }
+
+ # Step 1: Extract repository ID and commit hash from VSTS URL
+ $split_url = $url -split "/"
+ $repo_internal_id, $github_id = $split_url[-1] -split "%2f"
+
+ $github_link_type = $url -replace "vstfs:///GitHub/", "" -split "/" | Select-Object -First 1
+ $github_link_type = $github_link_type -replace "PullRequest", "PR"
+ $github_url = $null
+
+ $repo_name = ${script:config}.vsftsRepoInternalIdMap[$repo_internal_id]
+ if ($null -eq $repo_name) {
+ Write-Warning "Could not find repository name for repository internal ID $repo_internal_id"
+ return $github_url
+ }
+
+ if ($github_link_type -eq "Commit") {
+ $github_url = "https://github.com/$gh_org/$repo_name/commit/$github_id"
+ }
+ elseif ($github_link_type -eq "PR") {
+ $github_url = "https://github.com/$gh_org/$repo_name/pull/$github_id"
+ }
+ elseif ($github_link_type -eq "Issue") {
+ $github_url = "https://github.com/$gh_org/$repo_name/issues/$github_id"
+ }
+ else {
+ Write-Warning "Unknown GitHub link type $github_link_type"
+ }
+
+ return $github_url
+}
+
+function Get-AzureDevOpsUsers() {
+ $map = @{}
+ az devops user list --detect --query items | ConvertFrom-JSON | ForEach-Object {
+ $map[$_.user.principalName] = $_.user.displayName
+ }
+ return $map
+}
+
+
+$script:GITHUB_REPO_JSON_FIELDS = "name,owner,description,homepageUrl,hasIssuesEnabled,hasWikiEnabled,hasProjectsEnabled,licenseInfo,visibility,createdAt,updatedAt,primaryLanguage,openGraphImageUrl,labels,milestones"
+
+enum GithubRepoVisibility {
+ PUBLIC
+ PRIVATE
+}
+
+class GithubRepoOwner {
+ [string]$login
+ [string]$id
+
+ [string]ToString() {
+ return $this.login
+ }
+}
+
+class GithubLabel {
+ [string]$id
+ [string]$name
+ [string]$color
+ [string]$description
+
+ [string]ToString() {
+ return $this.name
+ }
+}
+
+class GithubMilestone {
+ [int32]$number
+ [string]$title
+ [string]$description
+ [System.DateTime]$dueOn
+
+ [string]ToString() {
+ return $this.title
+ }
+}
+
+
+
+class GithubRepository {
+ [string]$name
+ [GithubRepoOwner]$owner
+ [string]$description
+ [System.Uri]$homepageUrl
+ [bool]$hasIssuesEnabled
+ [bool]$hasWikiEnabled
+ [bool]$hasProjectsEnabled
+ [string]$licenseInfo
+ [GithubRepoVisibility]$visibility
+ [System.DateTime]$createdAt
+ [System.DateTime]$updatedAt
+ [PSCustomObject]$primaryLanguage
+ [System.Uri]$openGraphImageUrl
+ [GithubLabel[]]$labels
+ [GithubMilestone[]]$milestones
+
+ GitHubRepository([object]$obj) {
+ $obj.PSObject.Properties | ForEach-Object {
+ $this."$($_.Name)" = $_.Value
+ }
+ }
+
+ GithubRepository([string]$org, [string]$repo) {
+ $repoInfo = Get-GitHubRepoInfo -org $org -repo $repo
+ foreach ($field in $repoInfo.PSObject.Properties) {
+ $this."$($field.Name)" = $field.Value
+ }
+ }
+
+}
+
+
+function Get-AzureDevOpsLinkShield() {
+ param(
+ [Parameter(Mandatory = $true)]
+ [string]$url,
+ [string]$relationName
+ )
+ $resolvedUrl = Convert-AzureDevOpsLinkUrl -url $url
+
+ $label = Get-ItemNumberFromUrl -url $resolvedUrl
+ if ($label.Length -gt 7) {
+ $label = $label.Substring(0, 7) # shorten commit hash
+ }
+
+ $icon = "github"
+ $color = "whitesmoke"
+ if ($relationName -eq "GitHub Issue") {
+ $type = "issue"
+ }
+ elseif ($relationName -eq "GitHub Pull Request") {
+ $type = "pr"
+ }
+ elseif ($relationName -eq "GitHub Commit") {
+ $type = "commit"
+ }
+ else {
+ $type = $relationName.ToLower() -replace " ", "--"
+ $icon = "azure-devops"
+ $color = "0078D7"
+ $label = "AB%23$label"
+ }
+ $shield = "[]($resolvedUrl)"
+ return $shield
+}
+
+function Get-GithubOAuthTokenScopesArray() {
+ $scopes = @(curl.exe -sS -f -I -H "Authorization: token $(gh auth token)" `
+ "https://api.github.com/user" | Select-String -Pattern "^X-OAuth-Scopes: (.*)$" `
+ | ForEach-Object { $_.Matches.Groups[1].Value.Split(",") } `
+ | ForEach-Object { $_.Trim() })
+ return $scopes
+}
+
+function Test-HasGithubOAuthTokenScope() {
+ param(
+ [string]$scope # the scope to test for, e.g. "repo", "workflow", etc.
+ )
+ $items = Get-GithubOAuthTokenScopesArray
+ $items.Contains($scope)
+}
+
+function Get-CachedGitHubRepositoryMilestones() {
+ [CmdletBinding()]
+ param(
+ [Parameter(Mandatory = $true)][string]$githubOrg, # the name of the github org to get the milestones for, e.g. "MyOrg"
+ [Parameter(Mandatory = $true)][string]$githubRepo # the name of the github repo to get the milestones for, e.g. "MyRepo"
+ )
+ if (!${script:state}.githubRepositoryInfo) {
+ ${script:state}.githubRepositoryInfo = Get-GitHubRepoInfo -org $githubOrg -repo $githubRepo
+ }
+ $repoMilestones = @{}
+ ${script:state}.githubRepositoryInfo.milestones | ForEach-Object { $repoMilestones[$_.title] = $_ }
+ return $repoMilestones
+}
+
+function Get-AzureDevopsTagArray() {
+ $auth_header = "Basic $([Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes(":$ado_pat")))"
+ $url = "https://dev.azure.com/$ado_org/$ado_project/_apis/wit/tags?api-version=7.1-preview.1"
+ $headers = @{
+ "Authorization" = $auth_header
+ }
+ $response = Invoke-RestMethod -Uri $url -Headers $headers 2>$null
+ return $response.value | ForEach-Object { $_.name }
+}
+
+$script:ISSUE_JSON_FIELDS = "assignees,author,body,closed,closedAt,comments,createdAt,id,labels,milestone,number,projectCards,projectItems,reactionGroups,state,title,updatedAt,url"
+
+function Get-ExistingIssuesInformationMap() {
+ [CmdletBinding()]
+ param(
+ [int32]$limit = 5000
+ )
+ $map = @{}
+ if ($limit -gt 100) {
+ Write-Warning "Refreshing up to $limit issues from GitHub (this may take a long time)..."
+ }
+ $items = gh issue list --limit $limit --state=all --json "$script:ISSUE_JSON_FIELDS" --jq 'reduce .[] as $item ({}; .[$item.url] = $item)' | ConvertFrom-JSON
+ $items.PSObject.Properties | ForEach-Object { $map[$_.Name] = $_.Value }
+ Write-Debug "Found $($map.Count) existing issues"
+ return $map
+}
+
+
+$script:existingGitHubIssuesInformationTable = Get-ExistingIssuesInformationMap
+
+function Get-ExistingIssuesToTitleMap() {
+ $map = @{}
+ foreach ($issue in $script:existingGitHubIssuesInformationTable.Values) {
+ $map[$issue.url] = $issue.title
+ }
+ return $map
+}
+
+function Get-ExistingDevOpsUrlsToGitHubIssueUrlsMap() {
+ param(
+ [PSCustomObject[]]$azureDevOpsItemsQuery,
+ [string]$take = "first" # "first", "last" or $null
+ )
+ $issueToTitleMap = Get-ExistingIssuesToTitleMap
+ $titleToIssueMap = @{}
+ foreach ($item in $issueToTitleMap.GetEnumerator()) {
+ $titleToIssueMap[$item.Value] = $item.Key
+ }
+ if ($titleToIssueMap.Count -lt $issueToTitleMap.Count) {
+ Write-Warning "Duplicate issue titles found - deduplication will may not work correctly"
+ # count duplicate titles and list issue url for each
+ $duplicateTitles = @{}
+ foreach ($item in $issueToTitleMap.GetEnumerator()) {
+ $duplicateTitles[$item.Value] = @()
+ }
+ foreach ($item in $issueToTitleMap.GetEnumerator()) {
+ $duplicateTitles[$item.Value] += $($item.Key)
+ }
+ foreach ($item in $duplicateTitles.GetEnumerator()) {
+ if ($item.Value.Count -gt 1) {
+ Write-Host "`nDuplicate issue title '$($item.Key)' found for $($item.Value.Count) issues:" -ForegroundColor Blue
+ $_duplicatesMap = @{}
+ foreach ($issueUrl in $item.Value) {
+ $_duplicatesMap[[int]$issueUrl.Split("/")[-1]] = $issueUrl
+ }
+ $_item = 0
+ foreach ($key in $_duplicatesMap.Keys | Sort-Object $(if ($take -eq "last") { "-Descending" })) {
+ $issue = $_duplicatesMap[$key]
+ if ($_item -eq 0 -and $take) {
+ $titleToIssueMap[$item.Key] = $issue
+ }
+ if ($titleToIssueMap[$item.Key] -eq $issue) {
+ Write-Host " - $issue * (selected)" -ForegroundColor Blue
+ }
+ else {
+ Write-Host " - $issue" -ForegroundColor Blue
+ }
+ $_item++
+ }
+ }
+ }
+ }
+ $azureDevOpsItemUrlToGitHubIssueUrlMap = @{}
+ foreach ($item in ${script:state}.azureDevOpsItemsQuery) {
+ $title = $item.fields.'System.Title'
+ $issueUrl = $titleToIssueMap[$title]
+ if ($issueUrl) {
+ $azureDevOpsItemUrlToGitHubIssueUrlMap[$item.url] = $issueUrl
+ }
+ }
+ return $azureDevOpsItemUrlToGitHubIssueUrlMap
+}
+
+function Update-GitHubComment {
+ param(
+ [Parameter(Mandatory=$true)]
+ [string]$commentId,
+ [Parameter(Mandatory=$true)]
+ [string]$newComment
+ )
+
+ $escapedComment = $newComment.Replace('\', '\\').Replace('"', '\"').replace("`n", "\n").replace("`r", "")
+ $jsonPayload = "{ `"body`": `"$escapedComment`" }"
+
+ $headers = @{
+ "Authorization" = "token $gh_pat"
+ "Content-Type" = "application/json"
+ }
+
+ $url = "https://api.github.com/repos/$gh_org/$gh_repo/issues/comments/$commentId"
+
+ try {
+ Invoke-RestMethod -Uri $url -Method Patch -Body $jsonPayload -Headers $headers
+ }
+ catch {
+ Write-Output "Failed to update comment ${commentId}: $_"
+ }
+}
+
+
+$query = ${script:state}.GetAzureDevOpsItems($ado_area_path, $ado_start_workitem_id, $ado_migrate_closed_workitems)
+Write-Output "⚙️ Migration query identified $($query.Count) work items to migrate"
+
+Write-Output "🔍 Checking for existing GitHub issues..."
+$azureDevOpsItemUrlToGitHubIssueUrlMap = Get-ExistingDevOpsUrlsToGitHubIssueUrlsMap -azureDevOpsItemsQuery $query
+Write-Warning "$($azureDevOpsItemUrlToGitHubIssueUrlMap.Count) existing GitHub issues found based on title matching"
+
+# attempt to deduplicate existing issues based on title, updating the migration items map when no existing issue is found
+if ($gh_deduplicate_existing_issues -and $azureDevOpsItemUrlToGitHubIssueUrlMap.Count -gt 0) {
+ # only get the detailsId once to avoid negatively impacting performance
+ $_azureBoardId = (az boards work-item show --id $query[0].id --output json | ConvertFrom-Json).url.Split("/")[4]
+ foreach ($item in $azureDevOpsItemUrlToGitHubIssueUrlMap.GetEnumerator()) {
+ # update azureDevOpsWorkItemUrlToGitHubIssueUrlMap with existing issues
+ if (-not ${script:state}.azureDevOpsWorkItemUrlToGitHubIssueUrlMap[$item.Key]) {
+ ${script:state}.azureDevOpsWorkItemUrlToGitHubIssueUrlMap[$item.Key] = $item.Value
+ }
+
+ # attempt to create a details alias of the prior work item assuming $_azureBoardId does not change
+ $_detailsKey = $item.Key -replace "_apis", "$_azureBoardId/_apis"
+ if (-not ${script:state}.azureDevOpsWorkItemUrlToGitHubIssueUrlMap[$_detailsKey]) {
+ ${script:state}.azureDevOpsWorkItemUrlToGitHubIssueUrlMap[$_detailsKey] = $item.Value
+ }
+ }
+}
-Remove-Item -Path ./temp_comment_body.txt -ErrorAction SilentlyContinue
-Remove-Item -Path ./temp_issue_body.txt -ErrorAction SilentlyContinue
$count = 0;
-ForEach($workitem in $query) {
- $original_workitem_json_beginning="`n`nOriginal Work Item JSON
" + "`n`n" + '```json'
- $original_workitem_json_end="`n" + '```' + "`n
:information_source: Original Work Item Details
`n`n"
+ $ado_details_table = ""
+ $ado_details_table += "| Created date | Created by | Changed date | Changed By | Assigned To | State | Type | Area Path | Iteration Path|`n|---|---|---|---|---|---|---|---|---|`n"
+ $ado_details_table += "| $($details.fields."System.CreatedDate") | $($details.fields."System.CreatedBy".displayName) "
+ $ado_details_table += "| $($details.fields."System.ChangedDate") | $($details.fields."System.ChangedBy".displayName) "
+ $ado_details_table += "| $ado_assigned_to_display_name | $($details.fields."System.State") "
+ $ado_details_table += "| $($details.fields."System.WorkItemType") | $($details.fields."System.AreaPath") "
+ $ado_details_table += "| $($details.fields."System.IterationPath") |`n`n"
+ $ado_details_end = "`n`n
:card_file_box: Related Work Items
" + "`n`n"
+ $relation_details += "| Relationship | Link | Title |`n|---|---|---|`n"
+
+ foreach ($relation in $relations.GetEnumerator()) {
+ $relation_url = $relation.Key
+ $relation_name = $relation.Value
+ $relation_url = Convert-AzureDevOpsLinkUrl -url $relation_url -useMappedUrl $true
+ $relation_issue_url = ${script:state}.azureDevOpsWorkItemUrlToGitHubIssueUrlMap["$relation_url"]
+
+ $relation_title = $azureDevOpsQuery | Where-Object {
+ $_.url -eq $relation_url -or $(Convert-AzureDevOpsLinkUrl -url $_.url) -eq $relation_url
+ } | Select-Object -ExpandProperty fields | Select-Object -ExpandProperty "System.Title"
+
+ # check if the link is a GitHub link
+ if ($relation_name -match "GitHub") {
+ # extract the id, repo and org from the url
+ $split_url = $relation_url -replace "https://github.com/", "" -split "/"
+ $inferred_url_org = $split_url[0]
+ $inferred_url_repo = $split_url[1]
+ $inferred_url_id = $split_url[-1]
+ if ($gh_mention_related_items -eq $true -and -not $relation_name -match "Commit") {
+ $link_text = "${inferred_url_org}/${inferred_url_repo}#${inferred_url_id}"
+ }
+ elseif ($relation_name -match "Commit") {
+ $link_text = "${inferred_url_org}/${inferred_url_repo}@${inferred_url_id}"
+ }
+ else {
+ $link_text = "$inferred_url_org/${inferred_url_repo} ${inferred_url_id}"
+ }
+ }
+ elseif ($relation_issue_url) {
+ # always reference issues which we have already migrated
+ $link_text = "#$(Get-ItemNumberFromUrl -url $relation_issue_url)"
+ }
+ elseif ($relation_url -match "https://dev.azure.com/") {
+ $link_text = "Azure Boards AB#$(Get-ItemNumberFromUrl -url $relation_url)"
+ }
+ else {
+ $link_text = ":link: link"
+ }
+ $relation_details += "| $relation_name | [$link_text]($relation_url) | $relation_title |`n"
+ }
+ $relation_details += "`n" + "`n
Original Work Item Details
" + "`n`n"
- $ado_details_beginning | Add-Content -Path ./temp_comment_body.txt -Encoding ASCII;
- $ado_details= "| Created date | Created by | Changed date | Changed By | Assigned To | State | Type | Area Path | Iteration Path|`n|---|---|---|---|---|---|---|---|---|`n"
- $ado_details+="| $($details.fields.{System.CreatedDate}) | $($details.fields.{System.CreatedBy}.displayName) | $($details.fields.{System.ChangedDate}) | $($details.fields.{System.ChangedBy}.displayName) | $ado_assigned_to_display_name | $($details.fields.{System.State}) | $($details.fields.{System.WorkItemType}) | $($details.fields.{System.AreaPath}) | $($details.fields.{System.IterationPath}) |`n`n"
- $ado_details | Add-Content -Path ./temp_comment_body.txt -Encoding ASCII;
- $ado_details_end="`n" + "`n
:scroll: Original Work Item JSON
`n`n${fence}json`n"
+ $prettyJson = $detailsJson | ConvertFrom-Json | ConvertTo-Json -Depth 100
+ $originalWorkitemJsonEnd = "`n$fence`n`n
Work Item Comments ($($response.count))
" + "`n`n"
- $ado_original_workitem_json_beginning | Add-Content -Path ./temp_comment_body.txt -Encoding ASCII;
- ForEach($comment in $response.comments) {
- $ado_comments_details= "| Created date | Created by | JSON URL |`n|---|---|---|`n"
- $ado_comments_details+="| $($comment.createdDate) | $($comment.createdBy.displayName) | [URL]($($comment.url)) |`n`n"
- $ado_comments_details+="**Comment text**: $($comment.text)`n`n-----------`n`n"
- $ado_comments_details | Add-Content -Path ./temp_comment_body.txt -Encoding ASCII;
- }
- $ado_original_workitem_json_end="`n" + "`n
:speech_balloon: Work Item Comments ($($response.count))
" + "`n`n"
+ ForEach ($comment in $response.comments) {
+ $ado_comments_details = "| Created date | Created by | JSON URL |`n|---|---|---|`n"
+ $ado_comments_details += "| $($comment.createdDate) | $($comment.createdBy.displayName) | [URL]($($comment.url)) |`n`n"
+ $ado_comments_details += "**Comment text**: $($comment.text)`n`n-----------`n`n"
+ }
+ $ado_original_workitem_json_end = "`n" + "`n