natenho/go-jira-migrate

Migrate team-managed project issues between two JIRA Cloud accounts

GO JIRA Migration Tool

This tool can migrate both company-managed and team-managed project issues between two JIRA Cloud accounts. It migrates attachments, description, comments, images, links, custom fields and so on by actually reading the original issue and creating a new one with the same details. The main purpose of this tool is the lack of support for migrating team-managed projects.

References

• CLOUD-11467 - Support the Migration of Team Managed projects
• What migrates in a cloud-to-cloud migration for Jira

Installation

These are the available installation methods:

Binaries

Download the latest binaries

Go

go install github.com/natenho/go-jira-migrate@latest

Options

  -api-key string
        API Key (to create one, visit https://tinyurl.com/jira-api-token/)
  -delete-on-error
        Define if issues migrated with errors should be deleted
  -field value
        Custom fields to read from source project (includes 'Story point estimate' and 'Flagged' by default)
  -label value
        Additional labels to assign to migrated issues (includes 'MIGRATED' label) by default
  -query string
        JQL query returning issues to be migrated from the selected project (e.g. "status != Done" to migrate only pending issues) (default "Status != Done")
  -source string
        Source JIRA URL (e.g. https://your-source-domain.atlassian.net/)
  -source-project string
        Source project key (e.g. MYPROJ)
  -sprints
        Define if sprints will be imported (default true)
  -target string
        Target JIRA URL (e.g. https://your-target-domain.atlassian.net/)
  -target-project string
        Target project key (e.g. OTHER)
  -user string
        User
  -workers int
        How many migrations should occur in parallel (default 8)

Simple example

This example is a common usage scenario, migrating all pending issues.

/go-jira-migrate -source https://SOURCE-JIRA.atlassian.net/ -target https://TARGET-JIRA.atlassian.net/ -user your-jira-user -api-key xxxxxxxxxxxxxxxxxxx -source-project SOURCE-PROJ -target-project TARGET-PROJ -query "status != Done"

Full example

This example include some additional switches and custom fields to be migrated, like issue "Story Points".

./go-jira-migrate -workers=8 -sprints=true -delete-on-error=true -source https://SOURCE-JIRA.atlassian.net/ -target https://TARGET-JIRA.atlassian.net/ -user your-jira-user -api-key xxxxxxxxxxxxxxxxxxx -source-project SOURCE-PROJ -target-project TARGET-PROJ -query "status != Done" -field "Story Points" -field "Start date" -field "Due date" -field "due" -field "duedate" -field "Due Data" -field "Issue color"

Recommendations

• Create a dedicated user for the migration, so it can be easily identified
• Make sure the user has Administrator access to the source and target JIRA projects
• Make sure at least a board exists both in source and target JIRA project
• Make sure assignees and reporters have access to the target JIRA project. The tool will do a best effort to set those.
• The target JIRA project must exist and must have the same issue types and custom fields
• Make sure that attachment upload sizes are identical between the accounts (Refer to https://support.atlassian.com/jira-cloud-administration/docs/configure-file-attachments/ to configure limits)

Features and Limitations

• Created issues in the target project will not have the same key as the source project (even if the project keys are the same)
• Created issues are enriched with migration information, so it is easy to find a issue in the new JIRA project by the old key
• The original issue will be linked to the created issue
• Comments are all made by the migration user, mentioning the original user that wrote the comment
• Created/Updated dates are lost because all issues are created at the moment of the migration

License

go-jira-migrate's Issues

Execution run into errors

Hi Natenho,

I have tried the tool on a MacBook Air (M1).

For this I had downloaded and unpacked the following file:
go-jira-migrate_1.0.11_darwin_arm64.tar.gz

In my test I wanted to migrate a team-managed project, which is not yet present in the target instance. This resulted in the following message:
2023/10/04 10:31:59 Create metadata not found for AM at target.atlassian.net, make sure the current user has access to create issues

After that, I had also created a team-managed project in the target instance and wanted to migrate there, but the following message came up:

panic: runtime error: index out of range [0] with length 0

goroutine 1 [running]:
github.com/natenho/go-jira-migrate/migration.getBoard(0x14000132000?, {0x16bd339e0, 0x2})
	/home/runner/work/go-jira-migrate/go-jira-migrate/migration/migrator.go:254 +0xf0
github.com/natenho/go-jira-migrate/migration.(*migrator).Execute(0x14000132000, {0x104307200, 0xe})
	/home/runner/work/go-jira-migrate/go-jira-migrate/migration/migrator.go:178 +0x134
main.main()
	/home/runner/work/go-jira-migrate/go-jira-migrate/main.go:93 +0x7a4

Cheers
Frank

Doesn't Work

Hi, We have tried to run your tool, however it doesn't appear to work? following the instructions of download the binaries and run does nothing, could you please advise on what we should do? Or step by step process on how to use this?

Support for OS X

Hi, would it be possible to include a binary for use on OS X and arm64 architecture?