Calibrate Your Expectations for the Jira Importer Before You Migrate to GitLab
Most migration plans oversimplify importing Jira issues into GitLab. There is a Jira Importer, but it’s not as simple as it seems.
The importer works but is more limited than most teams assume. Titles, descriptions, and labels import cleanly. Nearly everything else in a Jira issue either gets flattened into plain text or doesn’t import at all. Obviously, this is a big hurdle.
The third item in our eBook, Ten Things to Address Before You Migrate from Atlassian to GitLab, is calibrating expectations on the Jira importer. Know what it does before it becomes the plan.
What the importer moves, and what it leaves behind
Here’s what happens to each part of a Jira issue when it goes through GitLab’s built-in importer:
| Jira Data | What the importer does with it |
| Title, description, labels | Imported directly |
| All other metadata | Flattened into the description as plain text. Not structured, not searchable as fields |
| Description formatting | Not converted to GitLab Flavored Markdown, so Jira markup arrives visibly broken |
| Comments | Not imported |
| Assignees | Not imported |
| Attachments | Not covered in the importer documentation |
| Issue links, subtask relationships | Not covered |
| Status / workflow state | Not mapped |
| Sprints, story points, custom fields | Not mapped |
| Watchers, worklogs, issue history | Not covered |
The CSV import path is worse. It moves only title, description, due date, milestone, and type, GitLab’s documentation says that other columns are not imported. CSV files are also capped at 10 MB on GitLab.com.
For some projects, that’s fine. A backlog of open feature requests may only need a title and a description. For others, losing comment threads, assignees, and links between issues means losing the context altogether.
When you need the full history
If your requirements include comments with their original authors and timestamps, assignees, attachments, epic parentage, or issue links, the importer won’t get you there. You’ll need a scripted migration against the GitLab API. GitLab documents this path itself and points to three options: its Professional Services team, Jira2Lab (a Professional Services fork of the community jira2gitlab tool), or a custom script built on the REST or GraphQL API.
Jira2Lab is written in Python and can be edited, which makes it a solid starting point. Don’t expect it to fit your instance out of the box, though. Documentation is thin, and most teams should plan for a fair amount of trial-and-error customization. The best approach is to pick a representative dataset, run a test migration, and look closely at what comes out the other side.
Custom scripts give you full control, with two hard limits to plan around:
- Comment rate limits.com allows 60 comment creations per minute. That works out to roughly 86,000 comments a day, no matter how fast your script runs. For a large Jira instance, comment volume alone can set your migration timeline.
- Description length. Descriptions are capped at about one million characters. That sounds generous but long issues can hit that limit.
Whichever option you choose, know that importing Jira issues to GitLab takes more effort than it seems at face value.
Decide fidelity project by project
The most useful question isn’t “how do we move everything?” It’s “what does each project actually need?” Most organizations don’t need every Jira issue in GitLab. For each project, pick one of three levels:
- Full fidelity. Comments, authors, assignees, attachments, and links, migrated by script. Reserve this for active projects where the history drives day-to-day work.
- Title and description. The built-in importer, accepting what it leaves behind. A good fit for backlogs and lighter-weight projects.
- Read-only archive. Leave the history in a read-only Jira instance and don’t migrate it at all.
The cheapest decision is often a mix: leave closed history in a read-only Jira instance and migrate only the open work. It’s a far smaller job than moving everything at full fidelity, and teams still have the old context when they need it. Do this project-to-project instead of one plan for the whole instance.
Download the full guide
Deciding what GitLab won’t replace is step two of ten. Ten Things to Address Before You Migrate from Atlassian to GitLab covers the rest, including what to expect from the Jira importer, how to fit your custom fields into GitLab’s limits, how to rebuild workflow enforcement, and how to price the gaps before they surprise you.
If you’d like help building your inventory, GitSimple’s migration team runs this discovery work for commercial and federal organizations. Let’s talk.
Ten Things to Address Before you Migrate from Atlassian to GitLab
Get all the details, including a checklist to keep you on track!