Import Jira issues into GitLab

What a Jira to GitLab migration involves and how much effort it takes

If your team runs issues in Jira and wants them in self-managed GitLab, the GitLab Jira importer can bring issues across, but the effort depends on field mapping, project structure, users and whether Jira stays linked after the move. The import itself is usually the smallest part of the work. No duration is given here because it depends on the size and configuration of your Jira estate, and you should confirm the importer's current behavior against the GitLab import documentation and a test run in your own environment.

Plan the move as a wider project. Jira workflows and statuses have no direct equivalent in GitLab issues, so you will decide how states, labels and boards are represented. Permissions need the same treatment: Jira project roles, groups and issue security levels must be mapped to GitLab groups, projects and member roles, and you should confirm which Jira users can be matched to GitLab accounts before import starts. Attachments, comments, custom fields and linked issues each need a check against the importer's output, because a field that does not come across cleanly can leave history incomplete. Decide the target project structure before the first import run, since re-importing into a different layout is slow to undo.

Cutover is the other half of the effort. You need to decide when Jira goes read-only, how in-flight work is moved, what happens to links from commits, branches and documentation that point at Jira keys, and whether Jira stays connected to GitLab through an integration for a transition period. Ask any partner for a written scope covering a test import, field mapping sign-off, user mapping, cutover steps and post-migration verification, and ask which of these items are one-time work and which recur, such as keeping an integration maintained through GitLab upgrades.

Which Jira issue data maps cleanly to GitLab issues

This table compares common Jira issue elements with their GitLab issue equivalents. Read the importer column as a set of expectations to check in a test import, not as a confirmed field list. The main takeaway is that core text fields usually need the least rework, while workflow states, hierarchy, people and custom data need a decision before cutover.

Jira element	GitLab equivalent	Importer behavior and rework
Summary	Issue title	Expected to carry over. Check length and special characters in a test import.
Description	Issue description	Expected to carry over. Review Jira markup, tables and links after import.
Status	Open or closed state, labels	Expected to map to open or closed only. Plan labels for in-progress states.
Priority	Labels or a custom field	Not a native GitLab issue field in most setups. Map to labels and confirm the result.
Assignee and reporter	Assignee and author	Users map through placeholder accounts. Reassign and confirm attribution after import.
Labels and components	Labels	Labels are likely to carry over. Convert components to labels or scoped labels where needed.
Sprints and epics	Milestones, iterations or epics	Needs a design decision. Confirm the target structure and that your tier supports it.
Comments and attachments	Notes and uploads	Confirm whether both import and how authorship and timestamps appear. Check size limits.
Custom fields and history	Description text, labels or archived export	Unlikely to map one to one. Decide whether to summarize, label or archive the Jira history.

Documented ways to get Jira issues into GitLab

GitLab's import documentation lists Jira issues among its supported sources, so the built-in importer is the first option to assess. The cards below cover the importer, the access it needs, the integration that keeps Jira linked after cutover, and the scripted routes to consider only when the importer does not cover a field you need.

Jira importer in the project flow

The Jira importer sits in the GitLab project import flow and creates GitLab issues from the Jira project you select. Confirm which Jira issue types, fields and attachments your GitLab version carries across, since the importer does not map every field in the same form. Record what lands in GitLab as a checklist, and have the migration owner sign it off before the cutover.

Jira access and credentials

The importer needs a Jira account with read access to every project in scope, plus the credential type your Jira edition accepts. Ask your Jira administrator to confirm the permissions on those projects and whether the account can see every issue, comment and attachment, because restricted issues are a common source of gaps. Use a service account with a named owner, and remove it once the migration is closed.

Jira integration for ongoing references

The Jira integration is a separate configuration that links a GitLab project to Jira so that commits, branches and merge requests can reference Jira keys. It does not move existing issues, so it suits teams that keep Jira as their planning system for a period. Confirm which events are sent in your GitLab version and whether comments and status changes flow in one direction only before you rely on it.

Scripted export through the API

When the importer leaves out data you need, a script can read issues from Jira and create them through the GitLab API. You build and maintain this route, so it needs a field mapping, a plan for user identities and a rerun process for failed records. Treat it as an engineering project with its own test cycle, and confirm the API endpoints and token scopes against your instance version.

Sample import before cutover

A sample import into a non-production group is the practical way to check behavior before the real move. Pick a small set of projects that includes closed issues, long comment threads, attachments, labels and linked issues, then compare counts, dates, authors and statuses against Jira. Keep the results with the migration record so the same checks can be repeated for the full run.

Network reach to Jira

The GitLab instance must reach the Jira endpoint over the network path your security team has approved, which is a common blocker in segmented or offline networks. Confirm firewall rules, proxy settings and certificate trust for the Jira host from the GitLab server before scheduling the import window. Run the import from inside the same boundary your security team already reviews.

When importing Jira issues fits and when keeping Jira with an integration fits

A team retiring Jira across every project gets the cleanest result from an import. Issues and their planning metadata move into the same system that holds code, merge requests and pipelines, so the work history sits in one place once Jira is switched off. The trade-off is that a one-time import is a snapshot, and some Jira configuration has no direct equivalent in GitLab.

What the import gains: Work items live beside repositories, merge requests and CI/CD, so references between code and issues no longer depend on a second product.
What gets lost or rebuilt: Jira workflows, automation rules, dashboards and filters do not carry over as they are. Treat each one as either a rebuild in GitLab or a retired feature, and record which.
What runs in parallel: A short freeze window in Jira, a final import run, and a comparison of issue counts, statuses and assignees against the source before the move is declared complete.
What to retain: A complete Jira export kept under your retention rules, because the import will not be the only copy of historical context you may need.

Before you set a date, confirm the supported Jira source types, field mapping and attachment handling in the GitLab import documentation for your version.

How the Jira importer handles users, statuses and history

The behavior that most often surprises teams is how Jira people become GitLab people. Confirm in the current import documentation how Jira assignees, reporters and commenters are matched to GitLab accounts, and whether that matching depends on email address, username or both. Then find out what happens to anyone with no GitLab account. Ask whether the importer assigns that history to placeholder users, leaves the author blank, or attributes everything to the account that ran the import, because each option changes what reviewers see. Map the user list before the test run, since unmatched people are the usual source of misattributed history. Reassigning placeholder authorship after the import is follow-on work, covered in the sibling topic on mapping users and contributions after a GitLab import.

Status handling is the second area to verify. GitLab issues are either open or closed, so Jira workflow statuses have to collapse into those two states, and finer distinctions such as "In review" or "Blocked" will either become labels or disappear. Confirm which Jira status categories the importer treats as closed, whether custom statuses are carried over as labels, and whether closure dates are preserved. For comments and timestamps, confirm whether the original author name and creation time appear in the imported text or only in system metadata, and whether attachments and inline images are copied at all. These answers decide how much of the Jira discussion a future reader can trust without going back to Jira.

Test with a representative project before committing to a full import. Choose one that includes every issue type in use, each workflow status, a closed issue with a resolution, comments from internal and external users, an attachment and linked issues. Compare the imported results against Jira for counts, open and closed states, timestamps, attribution and attachments, and record each difference in your cutover plan. Keep Jira readable for as long as people still need the original discussion, and name who signs off on mapping gaps before the full run. Check the importer's current scope and limits in the GitLab import documentation before you write the test plan.

Sequence for importing Jira issues, running in parallel and cutting over

This sequence moves Jira issue history into self-managed GitLab in a controlled order, with a rehearsal, an agreed parallel run and a read-only cutover. The result is a GitLab project set that the team trusts as the system of record, with Jira retained only for the agreed period.

Inventory Jira projects, fields and integrations
Your Jira administrator and the team leads list every project in scope, along with its issue types, custom fields, workflow statuses, automation rules, attachments and integrations such as Confluence links, CI webhooks or Slack notifications. The output is a written inventory that marks each item as imported, recreated in GitLab, or dropped. This step is done when every field a team relies on has a stated destination and an owner signs off on the list.
Define the GitLab project and label structure
The platform team decides how Jira projects map to GitLab projects or groups, and how statuses, priorities and issue types become labels or native GitLab fields. Naming conventions, label colors and a rule for issue iteration or milestone usage are written down before any data moves. Confirm in your own instance which field types the importer maps natively, because mapping gaps are easier to fix on paper than after a production run.
Run a sample import into a non-production instance
The team imports a representative subset of each Jira project, including issues with long comment threads, attachments, custom fields and closed history, into a non-production GitLab instance. Product owners and support staff review the results side by side with Jira and record every difference. The step closes when the review log lists each gap as fixed, accepted or handled by a manual follow-up, and the mapping document reflects those decisions.
Agree the parallel run and authoritative system per project
Leads of each team agree the length of the parallel run and state, project by project, whether Jira or GitLab is authoritative for new work during that period. Changes made in the non-authoritative system are either blocked or recorded for re-entry, and the rule is written into the cutover plan. Schedule the parallel run and the later freeze around the GitLab upgrade calendar, so that a required upgrade stop does not fall inside the cutover window.
Take a GitLab backup before the production import
The operations team takes a full GitLab backup, including the database and repository data, and confirms it can be restored by testing the restore in a separate environment. The backup also records the instance version so it can be matched to the restore target. Restore testing is complete when the team has seen the restored instance open a sample project, which gives a clean point to return to if the production import must be reversed.
Run the production import and reconcile results
The import runs project by project in the order agreed in the plan, and the operator logs the start and end time and any errors for each project. Afterward, the team compares issue counts per project and per issue type against Jira, then spot-checks a sample of issues covering comments, attachments, assignees and closed status. The step is done when counts reconcile or each variance has an explained cause recorded in the cutover log.
Cut over by making Jira read-only
On the agreed date, the Jira administrator switches each in-scope project to read-only, the team confirms that no new issues or comments can be created there, and a final delta import captures anything added after the earlier run. Teams are told where to work and how to link any remaining Jira references. The cutover is complete when a test user confirms the read-only state and the GitLab project is the only place new work is recorded.
Archive Jira after the retention window
After the retention window agreed in the plan, the Jira owner exports a final archive, retains it under your records policy, and then decommissions or archives the projects. Integrations and automation rules are removed in the same change so nothing continues to write to closed projects. Confirm the retention period and the archive format with your legal, compliance and records teams before the window begins, since those requirements set how long Jira data must remain available.

What drives the cost and duration of a Jira import

This table compares each driver of a Jira-to-GitLab import against the effort it adds and whether that effort is paid once or continues after cutover. Read the rows as the questions to answer in your scope document before asking for a quote. The main takeaway is that field mapping, history depth and integrations that depend on Jira keys usually matter more than raw issue count.

Driver	Effect on effort	One-time or recurring	How to keep it down
Number of Jira projects and issues	Raises test import runs, reconciliation checks and cutover time as volume grows	One-time	Scope out closed or stale projects and archive them outside GitLab
Custom field count and type diversity	Each custom field needs a target, a mapping decision or a label, and each field type behaves differently	One-time	Map only fields people still search or report on, and convert the rest to labels or description text
Workflow complexity	Jira statuses rarely match GitLab issue states, so status meaning must be decided and mapped to labels or boards	One-time	Agree a short status-to-label map before any test import
Attachment volume and size	Attachments are a known gap in the importer, so they need a separate transfer or link approach	One-time	Confirm current importer behavior for attachments, then decide whether to link to an archive
History depth required	Full comment and change history takes more validation than current state, and some history may not carry over	One-time	Decide which history is needed for audit or support and keep the rest in an archive
Users needing mapping	Each Jira user must be matched to a GitLab account or placeholder, and unmatched authors need review	One-time	Prepare a user list with email addresses and resolve departed users before import
Integrations that depend on Jira keys	Commit messages, build tools, dashboards and links that cite keys such as PROJ-123 need rework or a crosswalk	Recurring while links remain in use	Keep a key-to-issue crosswalk and inventory every tool that reads Jira keys
Number of parallel-run periods	Running Jira and GitLab side by side means two sources of truth and extra sync or reconciliation work	Recurring until the parallel run ends	Set a fixed end date and a single system of record for each project
Mapping design, test imports and cutover	Mapping design, repeated test imports and the final cutover account for most one-time effort	One-time	Fix the mapping before testing and freeze Jira writes for the cutover window

What usually goes wrong in Jira to GitLab imports and how to prevent it

Most failed Jira imports are not technical crashes. They are unmade decisions about fields, people, links and cutover timing that surface weeks later. The cards below pair each common failure with one preventive step to settle before the import runs.

Lost or flattened custom fields

Jira custom fields, workflow statuses and issue types do not always map one-to-one onto GitLab issue attributes, so some values can be dropped or collapsed into free text. Before any production run, build a field decision register that lists every custom field in use, its destination in GitLab (native field, label, description text or archive), and the owner who approved that choice. Then run a sample import of a representative set of issues and compare the source and target field by field.

Unmapped users without owners

Issues whose assignees, reporters or commenters cannot be matched to a GitLab account can arrive without a clear owner, which makes triage and accountability hard after cutover. Export the full list of Jira users who appear in issues over the scope period, match them to active GitLab accounts, and decide in advance how inactive or contractor accounts are handled. Confirm with your GitLab administrator how the importer treats users it cannot match in your version before you rely on it.

Broken links to Jira keys

Commit messages, branch names, merge requests, Confluence pages and runbooks often refer to Jira keys such as a project prefix and number. After import those references point at nothing or at the wrong item unless they are rewritten or redirected. Search source code, wikis and documentation for key patterns, list the references that matter for operations and audit, and agree whether they will be updated, left as historical text or linked through an integration during a transition period.

Attachments that do not transfer

Attachments are the most likely place for silent gaps. Files above a size threshold, unusual file types or attachments stored in external systems may be skipped or fail to move, and the issue text can still look complete. Measure total attachment volume and the largest files in Jira, run a sample that includes them, and check counts and checksums on the target. Keep the Jira attachment store readable until you have confirmed every file that matters is present or archived elsewhere.

Two systems accepting edits

If teams keep creating and editing issues in Jira while the import runs, the two systems diverge and the result is either duplicates or lost updates. Set a freeze date after which Jira is read-only for the imported projects, communicate it, and enforce it with permissions rather than instructions. Plan the delta handling for anything changed between the final export and the freeze, and decide which system is the record for each project from that point on.

No tested rollback

Teams often import once, discover problems, and have no clean way back to the prior state. Before importing, take a backup of the target GitLab project and retain the Jira export, then rehearse restoring the target to its pre-import state on a staging instance. Record how long the rehearsal takes and who signs off on the decision to roll back, so that a failed cutover is a planned option rather than an improvised repair.

Questions buyers ask before importing Jira issues into GitLab

What does a Jira to GitLab issue migration cost?

The cost is set by the written scope, not by a list price, and DeployOpen does not publish a price list. The main cost components are the discovery work to map Jira projects, issue types, statuses, custom fields and attachments to GitLab, the trial import and reconciliation, the cutover itself, and any custom scripting needed for fields the importer does not carry across. Most of this is one-time effort. Recurring costs sit elsewhere: your GitLab subscription tier, which the GitLab pricing page lists as Free, Premium or custom-priced Ultimate for self-managed installations, and any Jira licensing you keep during a transition period. Ask for a quote that lists each phase, the number of projects in scope, the field mapping assumptions and what the client must supply.

How long does a Jira issue import take?

No single duration applies, because the time depends on how many projects and issues are in scope, how much history and how many attachments must move, how cleanly the Jira data is organized, and how many people must approve the field mapping. A small set of projects with clear statuses can be planned quickly, while a large instance with years of workflows, custom fields and linked tools needs more discovery and more test rounds. Timing also depends on your change windows and on whether Jira stays read-only during cutover. Ask for a schedule in the written scope that separates discovery, trial import, validation, cutover and post-cutover checks, and confirm how many trial runs are included.

What do we need from our Jira and GitLab administrators?

The work needs named administrators on both sides before it starts. On the Jira side, someone must export or grant access to the projects in scope, explain the workflow statuses and custom fields, and confirm which users and attachments are relevant. On the GitLab side, an administrator must create or confirm the target groups and projects, decide the visibility and label conventions, and handle user access so that imported issues are assigned sensibly. Both teams should agree who signs off on the mapping and who can approve the cutover date. Plan time from these people for review sessions, since most delays come from waiting on decisions about field mapping rather than from the import itself.

Can our own team run the Jira import with the GitLab importer?

Yes, a capable internal team can run the documented Jira importer, since GitLab's import documentation lists Jira issues among the supported sources. The importer is a good fit for a small number of projects where the mapping is simple and you can accept the results after a trial run. Teams usually struggle in three places: judging which Jira fields, comments, attachments and links are carried across and which are lost, reconciling statuses and labels with GitLab's model, and rehearsing the cutover so users are not working in two systems at once. Check the current importer documentation for your GitLab version before you start, and test on a copy of real data. A partner adds value mainly when the scope is large or the reconciliation rules are not obvious.

Should we keep Jira and connect it to GitLab instead?

Keep Jira with an integration when teams in other departments still depend on Jira workflows, reporting, or approvals, or when a full move would disrupt work that cannot pause. Import when you want one system for issues and code, when Jira is being retired, or when the team already works from GitLab issues and merge requests. An integration keeps history in place and links commits and merge requests to Jira keys, but two systems mean two sets of permissions, two workflow models and ongoing administration. A decision memo should compare who uses each tool, what must be reported, the cost of running both, and the exit date. DeployOpen can help define that scope in writing before any import work begins.

Which Jira data is at risk of not coming across?

Assume that some Jira data will need manual handling or custom work. Confirm in the current GitLab import documentation how the importer treats comments, attachments, issue links, custom fields, workflow statuses, sprints and users, because support can change between releases. Fields that have no clean equivalent in GitLab are the usual source of disputes, so list them early and agree what happens to each one: migrate it into a description or label, archive the original export, or leave it in Jira. Keep a read-only copy of the Jira projects for an agreed period so that anyone who needs the original record can still find it.

How do we check the imported issues after the import?

Validation should compare counts, sample records and key fields between Jira and GitLab before users rely on the data. Check the number of issues per project, a sample of issues with comments and attachments, assignees and labels, and any issues with links to other items. Ask users in each team to confirm their open work looks right, and record the agreed exceptions. Keep the validation results with the change record so that auditors and project owners can see what was checked and who accepted it. Plan a rollback point in case the trial results show a serious gap.

How DeployOpen scopes, runs and supports a Jira to GitLab migration

DeployOpen approaches Jira to GitLab issue imports as a written, fixed-scope piece of work inside your own infrastructure. We agree which projects, issue types and fields move, test the import on copies, and document what did not transfer before anything touches production.

How we scope

Inventory the Jira projects, issue types, workflows and custom fields that are in scope for import.
Agree in writing which Jira fields map to GitLab fields, labels or description text, and which stay in Jira.
Record the decision to import history, keep Jira read-only, or run an integration, with the reasons.

How we build

Configure the self-managed GitLab import settings and run test imports against a non-production project.
Check imported issue counts, comments, attachments, links and assignees against the Jira source.
Script any repeatable cleanup steps, such as label normalization, and keep them under version control.

How we hand over

Deliver a mapping document that lists each Jira field, its GitLab destination and known gaps.
Document the import runbook, the rollback approach and who approves the production cutover.
Walk your administrators and project owners through the imported projects and the open-issue cleanup steps.

How we support

Offer ongoing support and upgrades through a retainer if your GitLab instance needs continued care.
Retest the import procedure when you change GitLab versions, since importer behavior can change between releases.
Keep the mapping document current as your Jira configuration or GitLab tier changes over time.