Migrate from Jira to GitLab

Moving Jira issues into self-managed GitLab next to the code: what the built-in importer carries over, what it leaves behind, and how to plan the cutover.

On this page

Migrate from Jira to GitLab: what moves and what does not

The built-in Jira importer moves each issue's title, description and labels, but it does not move assignees or comments. Any Jira history that depends on who owned an issue or what the team discussed will need a separate plan, such as exporting it to a reference archive or re-creating key threads by hand. Other unmapped Jira metadata is appended to the GitLab description as plain text, and Jira markup is not converted to GitLab Flavored Markdown, so expect formatting clean-up on the most important tickets.

The people who usually run this are engineering platform or tooling teams, because the importer requires the Maintainer or Owner role on the target GitLab project, read access to the Jira issues, and the GitLab Jira issue integration to be configured. The importer is available on GitLab Free, Premium and Ultimate, on GitLab.com, Self-Managed and Dedicated, so the tier you already run does not block the import. Confirm the exact role and integration steps against the GitLab Jira import documentation before you schedule the work.

Most of the effort is data mapping and parallel-run discipline, not the import command itself. Decide which Jira issue types, statuses and labels become GitLab labels and boards, which epics or planning structures you will rebuild, and who signs off on each mapping. Then run both trackers side by side for a defined period, with a named owner for the cutover, so that no one keeps filing work in Jira after the switch. Ask your GitLab partner or internal team to write this mapping down before the first test import.

How Jira features map to GitLab issues, boards and epics

This table compares common Jira features with their GitLab counterparts and marks each row as clean, needs rework or gap. Read it against the Jira importer's known behavior: titles, descriptions and labels come across, while assignees and comments do not. Confirm board, sprint and epic behavior in the GitLab documentation for your version before you promise it to your team.

Jira featureGitLab equivalent and import resultStatus
Issue titlesImported as GitLab issue titlesClean
Issue descriptionsImported, but Jira markup is not converted to GitLab Flavored Markdown, so formatting needs reviewNeeds rework
LabelsImported as GitLab labels; confirm that label names and colors match your existing schemeClean
Other unmapped Jira fieldsAdded to the issue description as plain text, so they remain readable but are not native GitLab fieldsNeeds rework
AssigneesNot imported; reassign issues manually or with a script after migrationGap
CommentsNot imported by the Jira importer; archive Jira comments separately if the history mattersGap
AttachmentsConfirm in the GitLab documentation whether the Jira importer carries attachments before you plan the moveNeeds rework
Workflow statuses and transitionsNot mapped to custom GitLab statuses; represent state with labels, boards or issue open and closed statusNeeds rework
EpicsEpics are a GitLab Premium and Ultimate feature; Free tier users cannot use them, and Jira epic links must be rebuiltNeeds rework
Sprints and boardsMap sprints to milestones or iterations only after confirming the GitLab documentation for your tier; rebuild boards by handNeeds rework

Which data moves, which must be exported separately

The GitLab Jira importer brings across the core issue record, but several things a team relies on sit outside it. Plan the migration around what the importer skips, what Jira's own backup covers, and which integrations must be rebuilt by hand in GitLab.

Core issue fields via the importer

The GitLab Jira importer imports each issue's title, description and labels. Other Jira metadata that has no GitLab field is appended to the description as plain text, and Jira markup is not converted to GitLab Flavored Markdown, so check how formatted descriptions look after import. Running it requires read access to Jira issues, the Maintainer or Owner role on the GitLab project, and the GitLab Jira issue integration configured for that project.

Assignees and comments need a separate route

The importer does not bring over assignees or comments. Export both from Jira before cutover, using CSV export or the Jira Cloud backup, and decide whether they live in the issue description, a linked archive or a reference document. Ask who owns the history of open discussions, since a sprint review often depends on comment threads.

Attachments and Jira Cloud backup contents

Jira Cloud backup covers work items, board and sprint data, comments, users, and project configuration such as workflows and schemes. It does not cover automation rules, third-party apps or Assets, so those need their own inventory. Plan attachments as a separate transfer and confirm with the GitLab import logs that each file reached its issue.

Workflows, schemes and automation rules

Jira workflows and permission schemes do not map one to one onto GitLab labels, boards and project roles. Automation rules and third-party app logic do not move at all, so each rule that notifies people, transitions issues or sets fields must be recreated as a GitLab workflow, webhook or CI job, or retired deliberately.

Pipelines, merge requests and commit links

Jira links to commits, branches and pull requests live in Jira's development panel, and the importer does not rebuild them. Plan to rebuild CI pipelines, merge request references and Git commit links in GitLab, and test that issue keys in commit messages still resolve. Confirm the Jira integration settings on the GitLab project before any link check.

Access and self-managed runtime

Self-managed GitLab needs its own identity setup, project roles and backup routine before data arrives. Confirm who holds the Maintainer or Owner role for each project during the import, and document where backups and restores of the GitLab instance are tested, since the imported issues are only as recoverable as the instance behind them.

How the importer maps a Jira project into a GitLab project

GitLab's Jira importer maps each Jira issue to a GitLab issue and carries over three things: the title, the description and the labels. Anything else Jira holds for that issue that has no GitLab field is appended to the GitLab description as plain text. Assignees and comments are not imported, so the reader should plan to export or record them separately if they matter for audit or handover. Jira markup is also not converted to GitLab Flavored Markdown, so headings, tables, panels and mentions in Jira descriptions will arrive as raw text and may need a cleanup pass on important issues.

Run a test import into a throwaway GitLab project on a non-production instance before any real cutover. The importer needs read access to the Jira issues, the Maintainer or Owner role on the target GitLab project, and the GitLab Jira issue integration configured. Confirm these with the GitLab documentation for your version, then compare a sample of issues side by side: titles, label sets, description length, the appended metadata block, and how long descriptions with embedded tables or code render. Check the resulting issue count against the Jira project filter you used, because the reader should confirm which issue types and closed items are included before counting anything as complete.

Record a mapping decision for every Jira issue type and every workflow status before the cutover. For each issue type, decide whether it becomes a GitLab issue, a label, or is archived outside GitLab, and document the label naming convention used. For each status, decide whether it maps to an open or closed GitLab issue, or to a scoped label, since GitLab does not reproduce Jira workflows. Do not assume a one-to-one board or sprint mapping: confirm with the GitLab documentation exactly what the importer creates, and document any board, sprint or epic structure you will rebuild by hand in GitLab after the import.

The migration sequence from Jira inventory to decommission

This sequence moves Jira issue data into self-managed GitLab in controlled stages, so each step produces evidence the team can check before it relies on the next one. The result is a GitLab project that holds the working backlog, a documented source of truth during transition, and an archived Jira export that stays available after write access ends.

  1. Inventory projects, workflows, labels and integrations

    List every Jira project that will move, and for each one record its issue types, workflow statuses, labels, custom fields, boards, epics and the integrations or automation rules that feed or read it. Identify which fields the GitLab Jira importer carries over (titles, descriptions and labels) and which it does not (assignees and comments), so the team knows what must be preserved another way. Confirm with your Jira administrator which projects are active and which can be archived. The output is a field mapping sheet and a list of integrations to rebuild in GitLab. The step is done when every active project has a mapping row and an owner has signed off on what is out of scope.

  2. Run a pilot import into a sandbox project

    Create a sandbox project in your self-managed GitLab instance and run the Jira importer against a copy of one representative Jira project. The account running the import needs read access to the Jira issues, the Maintainer or Owner role on the GitLab project and the GitLab Jira issue integration configured. Compare a sample of imported issues against Jira for title accuracy, description content, label mapping and the plain-text metadata appended to descriptions, since Jira markup is not converted to GitLab Flavored Markdown. The output is a pilot report listing what arrived, what was lost, and the fixes needed. Repeat the pilot if the mapping sheet changes.

  3. Rebuild boards, epics and labels in GitLab

    Using the pilot report, recreate the working structure in GitLab: labels that match the Jira label set, issue boards that mirror the Jira board columns, and epics where the team uses them, which requires a GitLab tier that includes epics. Decide how assignees and comment history will be preserved, for example by linking the original Jira key in the issue description or by keeping the Jira export as a reference. Document each rule in a cutover-ready configuration note. The output is a tested GitLab project configuration and a short guide for engineers on where historical context now lives. The step is done when a team member can locate a migrated issue and its original Jira reference in under a minute during a review.

  4. Operate a parallel run with a defined source of truth

    For a fixed period agreed by the project owners, teams work in both Jira and GitLab, but only one system is authoritative for each project at any time. Write the rule down: for example, new work is created in GitLab while Jira remains read-only for reference, or the reverse for a single team. Track discrepancies in a shared log, and fix mapping gaps in the sandbox configuration before the production import. The output is a parallel run log and an updated mapping sheet. The step is complete when the log shows no unresolved mapping defects for two consecutive review cycles and the owners agree to proceed.

  5. Execute cutover with a freeze window and final import

    Announce a freeze window during which no one edits the Jira projects being moved. Run a final import, then run the incremental import for issues changed since the earlier pass, and verify counts and sampled issues against the source. Switch every team's links, bookmarks and integrations to GitLab, and confirm that CI pipelines and merge requests reference the new issue keys where relevant. The output is a cutover runbook with timestamps, responsible owners, rollback steps and verification results. Keep the runbook with the Jira export so the sequence can be audited later.

  6. Decommission Jira write access and archive exports

    After cutover is verified, remove write permissions from the migrated Jira projects and disable their automation rules and integrations so no new data is created there. Take a full export of the projects before access is removed, including attachments and comments, and store it in your own retained archive with checksums and access controls that match your data classification rules. Atlassian's cloud backup does not cover automation rules, third-party apps or Assets, so record those configurations separately. The output is an archive of the Jira export, a decommission record and a list of retained configuration. The step is complete when an independent reviewer can open the archive and confirm its contents against the inventory from the first step.

How the move changes for Jira Cloud and Jira Data Center teams

Jira Cloud customers depend on what Atlassian's export tools expose. Backup for cloud covers work items, board and sprint data, comments, users and project configuration such as workflows and schemes, but it does not include automation rules, third-party apps or Assets. Those gaps mean that rules and app-driven behavior must be rebuilt in GitLab by hand, and that the export you take is the boundary of what can be migrated. The GitLab importer reads issues through the Jira integration, so your starting point is the data Jira Cloud can give you, not the full contents of the instance.

  • Backup coverage: Work items, comments and project configuration are included, but automation rules, third-party apps and Assets are not.
  • Importer input: The GitLab Jira importer brings over titles, descriptions and labels only, so comments and assignees need a separate archive.
  • Rebuilt behavior: Automations, app integrations and workflow logic must be recreated as GitLab labels, boards, CI jobs or webhooks.
  • Access requirements: The migrating user needs read access to Jira issues plus the Maintainer or Owner role on the GitLab project.

Before committing to a date, confirm with Atlassian which export formats and limits apply to your Cloud plan and list every automation and app your team relies on.

Running self-managed GitLab after the import

The first decision after the import is how GitLab will be installed and kept current, because that choice sets the upgrade and recovery work your team carries every month. GitLab documents several installation methods: the Linux package, which bundles PostgreSQL, Redis and Sidekiq and is described as the most mature and scalable option, the Helm chart, the GitLab Operator, Docker and installation from source. For a team that does not already run Kubernetes for stateful services, the Linux package is the simplest starting point to evaluate. Confirm with your platform team which method matches your existing automation, backup tooling and monitoring before the Jira import is scheduled.

Plan the upgrade cadence before go-live, not after. GitLab ships a major release each year, a minor release on the third Thursday of each month and patch releases twice a month, and it maintains the three most recent minor lines. Bug fixes are backported only to the current stable release, while security fixes also reach the previous two monthly releases, so a deployment that falls behind can lose fixes. Upgrades must pass through required upgrade stops, which since GitLab 17.5 fall at versions x.2, x.5, x.8 and x.11. Check the GitLab upgrade paths documentation for each stop, and schedule a staging upgrade rehearsal in every quarter. For air-gapped networks, GitLab documents offline installation, and the team should confirm how security scanners and GitLab Duo Self-Hosted receive updates in that environment.

Size the deployment from user count and API load, not from the size of the Jira instance. GitLab's reference architectures run from 1,000 users at 20 API requests per second to 50,000 users at 1,000 requests per second, and the documentation generally recommends a high availability design from 3,000 users. Under those architectures, stateful components such as PostgreSQL and Redis are not supported inside Kubernetes, so a Kubernetes deployment usually means the Cloud Native Hybrid pattern with stateful services on virtual machines or managed services. Before sign-off, the team should confirm backup and restore procedures against the GitLab backup and restore documentation, test a full restore, and decide whether GitLab Geo is needed for a second site, since each of these carries its own infrastructure and staffing cost.

What drives the cost and duration of this migration

This table lists the factors that change what a Jira to GitLab migration costs and how long it takes, with whether each is one-time or recurring and what to request in a written quote. Use it to see which inputs your own Jira instance will set, then ask for each one to be priced separately.

DriverWhy it changes cost or effortWhat to ask for in a quote
Number of projects and issuesEach project needs its own mapping, import run and checks, and issue volume sets how long imports and reconciliation takeCount of projects and issues by type, with an import plan and a reconciliation method
Custom fields and workflowsUnmapped fields are appended to descriptions as plain text, so deep field use means more manual rework on GitLab labels, boards and epicsField inventory, list of fields to keep as labels or text, and a rule for each
Integrations to rebuildJira automations, marketplace apps and webhooks do not carry over, so each one needs a GitLab equivalent or a replacement scriptIntegration inventory with a replacement or retirement decision for each item
Attachment and comment volumeThe importer does not bring comments or assignees, so comment history needs a separate archive plan and storage sizingPlan for exporting, storing and linking archived comments and attachments
Parallel run and team countTeams that keep Jira and GitLab side by side need duplicated updates, cutover dates and retrainingParallel run length, cutover sequence and who maintains each system during it
GitLab tier choiceFree includes the Jira importer, while Premium at 29 US dollars per user per month billed annually (GitLab pricing page) adds features such as epics, and Ultimate is custom pricedPer-user list price by tier, billing term, and which epic, board and compliance features each tier covers
Hosting and operating staffSelf-managed GitLab recurs for servers or cloud, backups, upgrades on the required upgrade stops, and on-call supportHosting design, sizing for your user count, backup and restore tests, and who runs upgrades

What usually goes wrong when issues move from Jira to GitLab

The Jira importer in GitLab moves titles, descriptions and labels, and little else. The risks below come from the gaps between what Jira holds and what GitLab receives, and from running two trackers during the cutover. Each card names one risk and the check that prevents it.

Assignees and comments lost without an archive

The GitLab Jira importer does not bring over assignees or comments. Discussion history often holds the decisions behind an issue, so losing it is a real loss, not a cosmetic one. Before the import, export the full Jira history to a file your audit or records team can search, and confirm who owns that archive. Then decide whether the archived comments are linked from each migrated issue or kept only in the archive.

Jira markup rendering poorly in GitLab

Jira text is not converted to GitLab Flavored Markdown, so headings, tables, panels, code blocks and mentions can display incorrectly after import. Other unmapped Jira fields are appended to the description as plain text, which can make long issues hard to read. Pick a sample of complex issues from each project, import them to a test project, and review how they render before you run the full import.

Duplicate issues during parallel running

If teams keep creating work in Jira while the GitLab project is being prepared, the same work can appear in both systems. Two trackers with no declared source of truth lead to conflicting status and stale assignments. Name one system as the record for each project, set a freeze date for writes in Jira, and post a closed notice in the old projects that links to the new location.

Labels and statuses that do not line up

Jira workflow statuses have no direct equivalent in GitLab issue boards, and label names may collide with scoped labels or with labels already used in the GitLab project. Mismatches can hide issues from board columns or create label sprawl. Build a mapping table of every Jira status, issue type and label to a GitLab label or board list, agree it with the team leads, and run the import against a copy of the project to check the result.

Integrations missing after cutover

Jira connections to chat, CI pipelines, release tools, security scanners and custom automation do not move with the issues. Commit messages that reference Jira keys and dashboards that read Jira data can stop working on the day of cutover. Inventory every integration and automation rule in Jira, including those that the Jira Cloud backup does not cover, and assign an owner to rebuild or retire each one before the switch.

Unplanned GitLab upgrades during the project

GitLab ships a major release yearly, a minor release monthly and patch releases twice a month, and upgrades must pass through required upgrade stops. An upgrade scheduled in the middle of a migration can change import behavior or break a tested configuration. Pin the GitLab version for the migration window, read the upgrade path for each planned step, and take a backup before any upgrade.

Questions teams ask before moving Jira issues to GitLab

Is the built-in GitLab Jira importer enough to move our issues?

It is enough for teams that need titles, descriptions and labels carried over, and that can accept the rest as text in the description. The importer brings each issue's title, description and labels, and it appends other unmapped Jira metadata to the description as plain text. It does not convert Jira markup to GitLab Flavored Markdown, so formatting, macros and embedded content usually need a review pass. Teams with attachments, workflow history, automation rules or cross-project links should confirm in a test project what survives before they commit to the importer alone.

What happens to assignees and comments during a Jira to GitLab import?

The importer does not bring over assignees or comments. Ownership and discussion history therefore need a separate plan. Common approaches include exporting comments from Jira into a reference file, recording the responsible person in the issue description, and assigning owners again in GitLab after import. Your team should decide which open issues need full discussion history and which can be closed or archived in Jira with a link to the new GitLab issue.

Do we need GitLab Premium to use epics after the migration?

Epics are a paid feature, so a team that depends on them will need a Premium or Ultimate subscription on a self-managed instance. The GitLab pricing page lists Premium at 29 US dollars per user per month billed annually, and Ultimate is custom priced. The Free tier can still hold issues, labels and boards, so a team can import first and decide on epics later. Confirm current tier contents on the pricing page before you budget, because feature placement changes between releases.

What access must our team provide before the import can run?

The person running the import needs the Maintainer or Owner role on the target GitLab project, read access to the Jira issues, and the GitLab Jira issue integration configured for that project. Your Jira administrator should confirm which projects and issue types are readable by that account, and which fields carry the data you need. Agree on who approves the mapping of Jira statuses and labels to GitLab labels before anyone runs a test import.

How long does a migration usually take, and what drives the duration?

No duration is fixed by the importer itself, so the timeline depends on your environment. The main drivers are the number of projects and issues, how many fields need manual mapping, how much history must be rebuilt by hand, and how many people must review the results. Ask any provider for a written schedule tied to a defined scope, and ask your own team to measure a test import on one project before estimating the rest.

Can our engineering team run the migration without outside help?

Yes, a team with GitLab administration skills and someone who knows the Jira configuration can run a small migration alone. The work is mostly export, test import, mapping review and cleanup, and it becomes harder as the number of projects, integrations and reporting needs grows. Teams that lack a Jira or GitLab administrator, or that must keep data inside a controlled environment, often bring in help for planning, testing and documentation.

How does a fixed-scope DeployOpen engagement differ from a retainer?

A fixed-scope engagement covers a defined set of work, such as planning the mapping, running the import in an agreed environment, hardening the GitLab instance and documenting the result. Scope, deliverables and timelines are agreed in writing before work starts, and a quote follows from that written scope. A retainer covers ongoing support, upgrades and continuous testing after the migration. Ask for a written scope for either option, and confirm which items sit inside each, including backups and upgrade paths on your own infrastructure.

How DeployOpen scopes and runs the migration

DeployOpen plans and implements self-hosted open-source platforms inside your own cloud accounts, data centers or air-gapped networks. For a move from Jira to GitLab, we start with a written scope that covers which Jira projects, issue data and boards come across, then build, test, document and hand over the GitLab side in your environment.

How we scope

  • Inventory which Jira projects, issue types, labels and boards must move and which can be retired.
  • Confirm the Jira access, GitLab Maintainer or Owner role and Jira integration each import needs.
  • Agree in writing which metadata is kept as description text and which assignee or comment history is rebuilt or archived.

How we build

  • Install self-managed GitLab in your environment using the installation method your infrastructure team has chosen.
  • Run a test import into a staging group, then check titles, descriptions, labels and epic structure against the Jira source.
  • Map Jira boards and epics to GitLab boards and epics, and document any workflow fields that need manual handling.

How we hand over

  • Deliver a written record of the mapping, the import steps and the exceptions found during testing.
  • Document the backup and restore procedure for the GitLab instance and the Jira archive kept for reference.
  • Walk your engineering and platform teams through the GitLab project structure and the ongoing Jira retirement plan.

How we support

  • Engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts.
  • Ongoing support, GitLab upgrades that follow the required upgrade stops, and continuous testing are available as a retainer.
  • Ask for a quote based on your written scope, since DeployOpen does not publish a price list.

Talk to our team.

Tell us what you're working on, whether it's a deployment, an audit, a security test or a cyber range. You'll speak with an engineer who can help you scope it.

  • 30-minute call: free, with no obligation.
  • NDA on request: we can sign before you share details.
  • Clear next steps: a scope and plan after the call.