Guide to Migrating Issues from Bitbucket Cloud to Jira Cloud
Platform Notice: Cloud Only - This article only applies to Atlassian apps on the cloud platform.
Summary
This guide provides step-by-step instructions for migrating issues from Bitbucket Cloud's built-in issue tracker to Jira Cloud. Bitbucket Cloud includes a built-in issue migration feature that allows repository administrators to copy issues directly into a new Jira Cloud project.
Use Bitbucket Cloud’s issue migration to copy repository issues into a new Jira Cloud project. This page outlines prerequisites, a clear step-by-step migration process, what to expect for assignees, attachments and comments, FAQs, and post-migration tips.
Only one issue migration to a Jira site can run at a time. Plan your window to avoid parallel runs.
Solution
Prerequisites
Administrator permissions for the Bitbucket Cloud repository and the Jira Cloud site.
Bitbucket Cloud workspace connected to the Jira Cloud site.
Run only one Bitbucket → Jira issue migration at a time.
Back up the Bitbucket issue tracker using the export feature before migration.
Step-by-Step Migration Process
Step 1: Back Up Your Bitbucket Issues (Recommended)
Navigate to the repository in Bitbucket Cloud.
Open Repository settings from the left sidebar.
Under Issues, select Import & export.
Click Start export.
Download the ZIP file when the export completes. You’ll also receive an email with a download link.
Step 2: Start the Migration
Navigate to the repository in Bitbucket Cloud.
Open Repository Settings from the left sidebar.
Under Issues, select Import & export.
Click Start migration.
Step 3: Choose the Jira Destination
Select the Jira Cloud site where the new project will be created.
If you don’t have a Jira site, create one from this screen using the Create a new site link.
Click Continue.
Step 4: Configure the Jira Project
Enter the project name for the new Jira project.
Enter the project key (for example, PROJ, MYAPP).
Click Migrate issues.
Step 5: Monitor the Migration
The migration runs in the background and may take minutes to several hours, depending on the volume and the number of Issues, and other factors.
Step 6: Verify the Migration
Log in to your Jira Cloud site.
Open the newly created project.
Verify that issues and comments are present and accurate.
Spot-check a few issues to confirm data integrity.
Step 7: Move Issues to an Existing Project (Optional)
The migration creates a new Jira project. If you need these issues in an existing project, use Jira’s bulk issue move after verification to transfer them to the desired project.
Frequently Asked Questions (FAQs)
What Happens to Assignees
Assignee mapping uses email matching. If a Bitbucket issue assignee email matches a Jira user, the destination issue is assigned to that user.
If no match is found, issues are migrated to the unassigned queue. Original assignee details are preserved in the issue description or a system comment for reference.
After migration, admins can reassign issues manually or via Jira’s bulk change.
What Happens to Attachments
File attachments on Bitbucket Cloud issues are not migrated to the corresponding Jira issues.
What Happens to Comments
All issue comments are migrated to the destination Jira issues, preserving content and chronological order.
Author attribution uses email matching. If no matching Jira account exists, comments may be attributed to the migration admin or include a note of the original author.
Formatting differences may occur (Markdown vs. Rich Text), so some issue comments may require minor cleanup.
Post-Migration Checklist
Confirm that issue counts match expectations and spot-check key items (description, comments, assignees).
Communicate the new Jira project link to the team and update the contribution docs.
If needed, bulk move issues to an existing Jira project and reassign owners using bulk change.
Tips and Best Practices
Run the export and review a sample before starting the migration to understand field mappings and attachments.
Plan a window when there is almost no activity on the Issue tracker at Bitbucket end to avoid any run time issues..
After verification, disable the Bitbucket issue tracker and add a note pointing users to Jira to prevent split tracking.
Was this helpful?