{"id":16805273,"url":"https://github.com/joshjohanning/ado_workitems_to_github_issues","last_synced_at":"2025-03-17T03:31:20.335Z","repository":{"id":43024237,"uuid":"468449381","full_name":"joshjohanning/ado_workitems_to_github_issues","owner":"joshjohanning","description":"Migrate Azure DevOps work items to GitHub Issues","archived":false,"fork":false,"pushed_at":"2024-11-13T23:33:08.000Z","size":34,"stargazers_count":20,"open_issues_count":2,"forks_count":12,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-02-27T17:17:46.882Z","etag":null,"topics":["azure-boards","azure-devops","github","github-issues","migration","migration-tool"],"latest_commit_sha":null,"homepage":"","language":"PowerShell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/joshjohanning.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-03-10T17:40:55.000Z","updated_at":"2024-12-30T22:26:46.000Z","dependencies_parsed_at":"2024-10-27T11:57:34.803Z","dependency_job_id":"4c687df4-b8ab-46a5-87f6-6407112974f5","html_url":"https://github.com/joshjohanning/ado_workitems_to_github_issues","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joshjohanning%2Fado_workitems_to_github_issues","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joshjohanning%2Fado_workitems_to_github_issues/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joshjohanning%2Fado_workitems_to_github_issues/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joshjohanning%2Fado_workitems_to_github_issues/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/joshjohanning","download_url":"https://codeload.github.com/joshjohanning/ado_workitems_to_github_issues/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243841203,"owners_count":20356443,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["azure-boards","azure-devops","github","github-issues","migration","migration-tool"],"created_at":"2024-10-13T09:47:41.377Z","updated_at":"2025-03-17T03:31:20.327Z","avatar_url":"https://github.com/joshjohanning.png","language":"PowerShell","readme":"# ado_workitems_to_github_issues\n\nPowerShell script to migrate Azure DevOps work items to GitHub Issues\n\n### Prerequisites\n\n1. Install az devops and github cli where this is running (ie: action or locally; GitHub-hosted runners already have)\n2. 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) \n    - ie: \"user story\", \"bug\", \"task\", \"feature\"\n3. Define under what area path you want to migrate\n    - You can modify the WIQL if you want to use a different way to migrate work items, such as `[TAG] = \"migrate\"`\n\n### Things it migrates\n\n1. Title\n2. Description (or for a bug, repro steps and/or system info)\n3. State (if the work item is done / closed, it will be closed in GitHub)\n4. It will try to assign the work item to the correct user in GitHub - based on ADO email before the `@`\n    - This uses the `-gh_update_assigned_to` and `-gh_assigned_to_user_suffix` options\n    - Users have to be added to GitHub org\n5. Migrate acceptance criteria as part of issue body (if present)\n6. Adds in the following as a comment to the issue:\n    - Original work item url \n    - Basic details in a collapsed markdown table\n    - Entire work item as JSON in a collapsed section\n7. Creates tag \"copied-to-github\" and a comment on the ADO work item with `-$ado_production_run\"`. The tag prevents duplicate copying.\n\n### To Do\n1. Provide user mapping option\n\n### Things it won't ever migrate\n1. Created date/update dates\n\n### Example\n\n- [Screenshot](https://user-images.githubusercontent.com/19912012/157745772-69f5cf75-5407-491e-a754-d94b188378ff.png)\n- [Migrated GitHub Issue](https://github.com/joshjohanning-org/migrate-ado-workitems/issues/296)\n\n## Instructions for Running in Actions\n\nThe recommendation is to use a GitHub App to run the migration - a GitHub app has higher rate limits than using a user PAT.\n\n1. Create a (classic) GitHub personal access token with at least the following scopes:\n    + `repo` (all scopes here)\n    + `read:org`\n2. Create the following action secrets:\n    + `ADO_PAT`: Azure DevOps PAT with appropriate permissions to read work items\n    + `GH_PAT`: The value of the PAT created in step #1\n3. Use the [action](.github/workflows/migrate-work-items.yml)\n4. Update any defaults in the [action](.github/workflows/migrate-work-items.yml) (ie: Azure DevOps organization and project, GitHub organization, repo, and any other defaults you want changed)\n5. Ensure the action exists in the repo's default branch\n6. Run the workflow\n\n## Instructions for Running Locally\n\nUsing the GitHub app might be better so you don't reach a limit on your GitHub account on creating new issues 😀\n\n```pwsh\n./ado_workitems_to_github_issues.ps1 `\n    -ado_pat \"abc\" `\n    -ado_org \"jjohanning0798\" `\n    -ado_project \"PartsUnlimited\" `\n    -ado_area_path \"PartsUnlimited\\migrate\" `\n    -ado_migrate_closed_workitems `\n    -ado_production_run # IMPORTANT - USING THIS WILL UPDATE THE WORK ITEM IN ADO!`\n    -gh_pat \"ghp_xxx\" `\n    -gh_org \"joshjohanning-org\" `\n    -gh_repo \"migrate-ado-workitems\" `\n    -gh_update_assigned_to `\n    -gh_assigned_to_user_suffix \"\" `\n    -gh_add_ado_comments\n```\n\n## Script Options\n\n| Parameter                       | Required | Default  | Description                                                                                                                                 |\n|---------------------------------|----------|----------|---------------------------------------------------------------------------------------------------------------------------------------------|\n| `-ado_pat`                      | Yes      |          | Azure DevOps Personal Access Token (PAT) with appropriate permissions to read work items (and update, with `-ado_production_run`)     |\n| `-ado_org`                      | Yes      |          | Azure DevOps organization to migrate from                                                                                                   |\n| `-ado_project`                  | Yes      |          | Azure DevOps project to migrate from                                                                                                        |\n| `-ado_area_path`                | Yes      |          | Azure DevOps area path to migrate from - uses the `UNDER` operator                                                                          |\n| `-ado_migrate_closed_workitems` | No       | `$false` | Switch to migrate closed/resoled/done/removed work items                                                                                    |\n| `-ado_production_run`           | No       | `$false` | Switch to add `copied-to-github` tag and comment on ADO work item                                                                           |\n| `-gh_pat`                       | Yes      |          | GitHub Personal Access Token (PAT) with appropriate permissions to read/write issues                                                        |\n| `-gh_org`                       | Yes      |          | GitHub organization to migrate work items to                                                                                                |\n| `-gh_repo`                      | Yes      |          | GitHub repo to migrate work items to                                                                                                        |\n| `-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)                          |\n| `-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 |\n| `-gh_add_ado_comments`          | No       | `$false` | Switch to add ADO comments as a section with the migrated work item                                                                     |\n\n**Note**: With `-gh_update_assigned_to`, you/your users will receive a lot of emails from GitHub when the user is assigned to the issue\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoshjohanning%2Fado_workitems_to_github_issues","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjoshjohanning%2Fado_workitems_to_github_issues","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoshjohanning%2Fado_workitems_to_github_issues/lists"}