Atlassian Migrations — The Three Pre-Migration Fires Nobody Talks About
Mihai Perdum
Author
10 min readMay 15, 2026
In my first post, I argued that waiting for perfection is the most expensive mistake an organization can make. In my second post, I told the story of an app migration that should have been a footnote and became a six-month exorcism.
This post is different. This one is a letter — written half to my future self, half to every Data Center admin reading this — about three things you should be fixing in your instance right now, before someone like me shows up to migrate it.
I've just come off a migration that put me through hell. I'm not going to spend this post unpacking why — the why is a tangle of platform divergence, tooling maturity, vendor variability, timeline pressure, and a dozen other things that no single party fully owns. What I want to do instead is give you the practical takeaways: three specific areas where I keep watching migrations get harder than they need to be, and what you can do in your own instance, today, to make those areas easier for whoever migrates you next.
If you're a DC admin or an org admin sitting on an instance you plan to migrate in the next two years — and given the March 2029 deadline, that should be most of you — read this carefully. Acting on these now is the cheapest work you will ever do. Acting on them under migration pressure, with a consultant's clock ticking, is the most expensive.
Fire One: Your Permission Schemes Are a Crime Scene
Here's what almost any DC instance that's been operating for more than a few years looks like under the hood.
Dozens of permission schemes. Dozens more issue security schemes. Many attached to projects that haven't been touched in years. Permission grants pointing at groups that no longer exist. Security levels with conditions referencing custom fields that were deleted long ago. Project roles populated by single users who left the company years prior. And on top of all of that — no admin in the organization can comprehensively see every project. Not even the senior Jira admins. Issue security levels get used to silo information so aggressively that the people responsible for running the platform end up locked out of half of it.
This is not unusual. This is the baseline of mature DC instances, and it's nobody's fault in particular. Permissions sediment like geology — every layer represents a different organizational moment, a different security review, a different stakeholder request. Nobody throws anything away because nobody can prove it's safe to throw away.
Here's the problem for me, the migrator. When I start moving projects to Cloud, I need to be able to inspect what's actually there. I need to verify data integrity, check that workflows fire, confirm that custom fields populate correctly, validate that issue counts match between source and target. If I can't see issues because some forgotten security scheme is hiding them from every account except a former employee's, I'm flying blind. I have two options: spend days untangling the permissions to gain visibility, or migrate without verification and hope nothing is broken on the other side. Both are bad. Both cost you money.
And here's the kicker — the Jira Cloud Migration Assistant doesn't fix this for you. Atlassian's own documentation is explicit that permission schemes with the same name as schemes in your Cloud target will get renamed during migration. Issue security level permissions that reference unsupported custom field types simply don't migrate at all. You'll arrive in Cloud with a permissions structure that is worse than what you had, because now it's the same mess plus a layer of migration-induced inconsistency on top.
What you should do, today:
Inventory everything. Permission schemes, issue security schemes, project roles, group memberships. Build a list. You can do this with the REST API or with a Marketplace utility. Don't skip the boring step.
Find the orphans. Schemes attached to no projects. Security levels with no issues. Permission grants pointed at groups that don't exist. Atlassian has shipped cleanup utilities in Jira Cloud specifically for this — "remove unused issue security levels" and "remove unused groups or single users from a grant" — but you should be doing this work in DC before migration so you're not carrying garbage across.
Create a "platform admin" group with broad visibility. This is the recommendation I give every client and the one they push back on the hardest. You need a group — call it jira-platform-admins, call it whatever — that has Browse Project on every project and is included in every issue security level. Yes, this trades a small amount of security compartmentalization for operational sanity. No, that trade is not optional if you want a clean migration.
That last point deserves more attention because I get pushback on it constantly. Security-conscious organizations bristle at the idea of any group having visibility into every issue. I understand the reflex. But here's the thing: your platform administrators already have the ability to grant themselves any permission they want. They can edit permission schemes. They can modify security levels. The compartmentalization you think you have is illusory at the admin layer. What you actually have is a system where admins have to go through the motions of granting themselves access — which doesn't make you more secure, it just makes operations slower and makes auditing harder, because the access grants are scattered across schemes instead of consolidated in one well-documented group.
This is not the most secure recommendation I will ever make. I'm aware. But permissions should be a fundamentally basic concept in an instance you intend to operate. If your senior admins can't see what they're administering, the security model has failed in a different way — by becoming opaque to the people responsible for it. Pick your poison.
Fire Two: Your Assets Workspace Is Quietly Catastrophic
This one hurt the most, and I have to start with a correction — because most of the migration writing online about Assets is out of date, and I don't want to add to that pile.
For years, the consensus on Assets (formerly Insight) migration was that it was "mostly manual." Atlassian's own knowledge base said exactly that. The path was: export your objects to CSV, manually rebuild your schema configuration in Cloud, re-import the CSVs, manually rebuild references, manually re-upload attachments, manually rewire issue-to-object links, manually recreate automation. For an enterprise Assets workspace, that wasn't a migration. It was a year-long rebuild dressed up as a migration.
That story changed late last year. With JCMA 1.12.48 — released in the back half of 2025 — Atlassian shipped Assets as a first-class, JCMA-integrated migration target. Object schemas, object types, objects, attachments, object avatars, object history, references, statuses, icons, and the custom-field links between work items and Assets objects now all move through the standard migration assistant pipeline. It's a real, automated path. Credit where it's due: it's a meaningful improvement over the CSV-by-hand era.
But it is, in everything except the marketing label, a beta. The capability is fresh. The published limits are significant. The behavior in the field is exactly what you'd expect from a feature that just shipped. Atlassian's own documentation lists, in plain English, the constraints I want you to read carefully:
AQL query attribute names may not be automatically sanitized during migration. Plan for query rework on the other side.
A single Asset object custom field on a work item can reference a maximum of 20 objects. Anything beyond that is dropped silently. If your CMDB has work items that reference more than 20 assets through a single field, you have a problem the migration will not warn you about.
Object history migrates, but is capped at 100 old/new value entries per history entry. Anything older than that cap is gone.
Cloud enforces a maximum of 2 unique constraints per object type, and duplication within a unique constraint is not allowed. This is the one that will burn you. Hold onto it — I'll come back to it.
Name and Description fields cap at 255 characters. Regex validation fields in object type attributes cap at 128. Long names get truncated.
Read those limits carefully. They are the limits of a feature that just shipped. They will improve over time. But if your migration is in the next twelve months, your migration is running on the beta version of this capability, regardless of what Atlassian labels it on the page.
I just came off a migration where the new JCMA Assets path was, on paper, exactly the right tool — and where it failed in practice on the one thing that mattered most: rebuilding the links between work items and Assets objects. The migration completed successfully according to JCMA's own report. Objects landed in Cloud. Schemas rebuilt themselves. Object history came across within the documented caps. The custom field references between work items and assets — the part that makes Assets actually useful as a CMDB rather than a static database — did not consistently resolve. Some did. Many did not. A meaningful fraction of work items arrived in Cloud with their Asset references empty, partial, or pointed at the wrong objects entirely.
This is where I built LeanZero's Atlassian Asset Migrator (open source, MIT-licensed) to step in. It is not a replacement for the new JCMA Assets capability — it is an alternative path for exactly the failure mode I just described. It does schema-aware object migration with explicit dependency resolution, attribute mapping with type conversions, cross-schema reference preservation, attachment uploads, ticket-to-asset connection restoration as a discrete validatable step, and resumable operations so a multi-hour migration doesn't restart from zero when something fails partway through.
The honest limitation I need to declare up front, because the tradeoff matters: the LeanZero tool does not migrate object history. The new JCMA path does, within the 100-entries cap. Mine does not. If history is mission-critical for your auditors and you're inside JCMA's caps, the JCMA path may be the right call. If your real risk is the work-item-to-Asset links — which, in my recent experience, is where the new JCMA path most reliably falls down — the LeanZero tool gives you a way to rebuild those connections deterministically and validate them.
But the tool isn't the whole story. The tool helps. The tool does not save you from the deeper problem.
The deeper problem is duplicate object names, and the new JCMA path made it worse, not better — because of the Cloud-side unique-constraint enforcement I flagged in the limits list above. Assets in DC has historically been tolerant of objects with the same display name across object types and even within the same object type, as long as the internal IDs differed. Operators got used to this. Schemas got built around the assumption that you could have ten objects called "Production Server" as long as each represented something different in context. Reference attributes resolved to object IDs, so duplicate names were a UX inconvenience, not a data problem.
Cloud Assets, and the migration paths that feed into it, are far less forgiving. Reference resolution leans heavily on names when source IDs can't be preserved across instances (and across instances, they generally can't be). When you migrate an object whose reference attribute points to "Production Server," and Cloud has ten objects matching that name, the resolution either picks one arbitrarily, fails outright, or — worst case — silently links to the wrong one. On top of that, the new unique-constraint enforcement in Cloud means object types that should be uniquely identifiable by some attribute combination will now outright reject duplicates that DC happily accepted. I had a migration where a meaningful fraction of the Assets-to-work-item links resolved to the wrong objects because of duplicate name collisions. We caught it. We caught it only because we'd built specific validation tooling to compare source and target reference graphs. Most migrations don't have that level of paranoia, and the errors go undetected until weeks later when somebody notices their CMDB lookups are returning nonsense.
What you should do, today:
Audit object names across your schemas. Find duplicates. Decide whether they should be deduplicated or whether the duplicates are semantically meaningful and need a disambiguating attribute added.
Add unique identifiers where they don't exist. Every object type that participates in references should have a unique key — a serial number, an asset tag, a hostname, anything stable that disambiguates. If your schema doesn't have one, add it now and backfill, while you're still in DC and the work is cheap.
Check the JCMA limits against your real data. Find work items that reference more than 20 assets through a single custom field. Find object names and descriptions exceeding 255 characters. Find regex validation fields exceeding 128. Fix them in DC before the migration runs, because JCMA will silently drop or truncate them and you will not get a useful warning.
Don't assume any single tool catches everything. Neither JCMA nor the third-party paths will warn you about every silent reference failure. If you're not running post-migration reference graph validation, you are flying blind regardless of which tool you used to move the data.
Decide your history tradeoff explicitly. If you go through JCMA, you get history capped at 100 entries per history entry. If you go through a third-party path like the LeanZero migrator, you may get more deterministic reference rebuilding but lose history entirely. Document which matters more to your auditors. Either way, write the decision down so nobody has to relitigate it under pressure mid-migration.
Fire Three: Assets Probably Carries More Than It Was Designed For
This one is the most controversial, and I'll lose some readers, but I'll stand by it.
Assets is, at its core, a configuration management database with a flexible schema engine. It excels at things like CMDBs, asset inventories, license registries, IT service catalogs, contract repositories — anything where you're modeling structured, slow-changing reference data with rich attribute relationships. It is less well-suited as a project tracker, a CRM, a ticketing pipeline, a workflow engine, or a handful of the other patterns I see it doing serious duty for in real environments.
How that happens is straightforward and very human. A team has a need. Jira's native object model doesn't quite fit. Somebody discovers Assets and finds it flexible enough to model the shape of the problem. Two years later, that workspace is tracking sales pipeline stages or HR onboarding phases or marketing campaign assets, with the operational gravity of a small ERP. Nothing went wrong in any single decision — the tool was available, it fit, the work moved.
Every time I see Assets used outside its core CMDB-style design, my migration estimate goes up by a meaningful multiple. Not because the data is unmovable — it is movable, with the right tooling — but because the data tends to be deeply entangled with the rest of the platform in ways that don't translate cleanly. Automation rules trigger off Assets attribute changes. JQL searches reference Assets object custom fields. Smart Values in workflows pull Assets data into transition logic. Reports aggregate across schemas and work items. Each one of those touchpoints is a manual rebuild in Cloud, because the function-by-function feature parity isn't there and the trigger model differs.
If your organization is going to migrate in the next two years, the conversation worth having right now is: for each Assets schema, is the data fundamentally about configuration items, infrastructure, licenses, or contracts? If yes, it stays. If no — if the schema is really doing project-tracking work, or pipeline work, or something that today might fit more naturally in a Jira project with custom issue types, in Confluence, or even in a spreadsheet — consider extracting it. Move the data to a more appropriate home. Decommission the schema in DC before migration begins.
This is the single most valuable piece of advice I can give an organization preparing to migrate, because it's the only one that meaningfully reduces scope rather than just cleaning up existing scope. Every schema you retire before migration is a schema you don't have to model, validate, reference-resolve, attach, link, and rebuild automation for in Cloud. The compounding savings are enormous.
The objection I always get: "But the teams using it will complain." Yes. Some will. They've built workflows around the tool and changing those workflows takes effort. That's a real concern and worth respecting. The counter-consideration is that migrating a schema whose fit was always slightly off, into a platform where the fit gets a little less forgiving, costs more every quarter you put it off. There's a redesign conversation in the future regardless. Doing it now, on your own timeline, with your in-house people, is dramatically cheaper than doing it mid-migration with a consultant.
The Common Thread
Read those three back to back and the pattern is plain. Permissions, Assets data shape, and Assets scope are the three areas where I most consistently see migration timelines slip and budgets balloon. They are not signs that anyone did anything wrong. They are structural realities of long-lived DC instances meeting a Cloud migration target where the platform has diverged considerably from where you started.
What you can control is whether these areas get addressed on your own schedule, in advance, with your in-house people who know the institutional history — or whether they get addressed under migration pressure, with consultants who don't, and a deadline that won't move.
The first is dramatically cheaper. The second is what happens by default.
What I Actually Tell My Clients
If you're a DC admin reading this and you're not yet in active migration planning, here's the work I want you doing in the next ninety days:
Permissions audit. Inventory permission schemes, issue security schemes, project roles. Identify the orphans. Create a platform admin group with global visibility. Document the security model so the next person who sits in your chair doesn't have to reverse-engineer it.
Assets data audit. Identify duplicate object names. Add unique identifiers to object types that participate in references. Check your data against the published JCMA Assets limits — twenty-objects-per-custom-field, 255-character name and description caps, 128-character regex caps, 100-entry history caps. Validate reference integrity. Document which schemas are mission-critical CMDB-style use cases and which schemas are doing work that might fit more naturally somewhere else.
Assets scope reduction. For every schema you classified as a candidate to move elsewhere — start the conversation with the owning team now. Find them a more appropriate tool. Migrate the data internally. Decommission the schema in DC. Every schema you retire is a schema you don't pay to migrate.
Documentation. Write down what you have. The instance that survives a migration well is the one where the institutional knowledge isn't trapped in a single admin's head.
These four streams of work will cost you, generously, three months of part-time admin time. They will save you, conservatively, three months of migration consultant time — which costs at minimum five times more per hour than your in-house admin, and doesn't come with the same institutional context.
This is the work nobody wants to do because it has no immediate payoff and no visible deliverable. It's the work that has the highest ROI of anything you will do in the next two years, and the one thing nobody on your leadership team will notice you did until you don't do it.
Do it anyway.
The migration is coming. The clock is ticking. And the cheapest hour of work in this entire transition is the hour you spend cleaning up permissions today, before someone is billing you to do it later.
I love migrations. Let's make yours one of the good ones.
303 is not an error: how an attachment migration ships zero bytes
Jira Cloud answers 303, Confluence answers 302, and an SSO-fronted Data Center answers with a login page. I measured the two Cloud cases end to end, and the failure that follows passes every audit you are likely to write.
