What we learned migrating Jira and Confluence, and how it can help with your move to the cloud

This is a story from a recent cloud migration Teams, Work supported as an external technical expert. The one that didn’t go exactly as planned, but ultimately led to a successful outcome and a set of valuable lessons.

I’m sharing these insights and practical recommendations so that you can plan and execute your cloud migration with more control and confidence.

When migration becomes an urgent business problem¶

“No seats left. People starting this month can’t get access. We have to resolve this ASAP.”

That was the problem that led a 250-user logistics software company to reach out for help with an urgent migration of Jira and Confluence. They hit the user limit on a perpetual license, and although new hires had already been onboarded to the team, they could not be added to Jira or Confluence.

At this point, migration stopped being a roadmap item and became an immediate operational problem. The stakes were high, with little room for error.

Teams, Work helped them complete the migration in under 7 weeks, from the first conversation to the moment when the whole organization went live in the cloud. The total investment for our services was under €10,000 for an 11-day engagement.

A quick look at the migration scope¶

Our client had the following setup:

• 250 users on each Jira and Confluence instance
• 2 apps to migrate: Zephyr and draw.io
• 90 Jira projects on the source instance and 25 already in Cloud
• 160 Confluence spaces on the source instance and 30 already in Cloud

We started by categorizing all on-premises data into three tiers:

• Standard. Projects and spaces without app dependencies or blockers. They could be easily migrated to the cloud.
• Constrained. Projects or spaces that used Zephyr or draw.io and required additional preparation before the migration.
• Double-blocked. Projects with both apps, and the heaviest Confluence spaces (over 200 diagrams and test plans).

This categorization was crucial. It helped us migrate part of the teams in the first two weeks, unblocking new employee onboarding before the full migration was complete. This was a quick and efficient win that reduced pressure on the license ceiling mid-project.

Identify data you can migrate first to unblock some of your teams early on.

We decided to run the migration in agile cycles: dry run → review → fix → real import. The entire migration took two full cycles total, starting with a canary wave and finishing with the full organization cutover over the weekend.

Press enter or click to view image in full sizeThis is what our migration process looked like

Team setup that kept us moving¶

For this migration, we chose to work as a single team on a Time and Materials (T&M) basis, rather than in a strict client–consultant model.

Why so? The client’s team had strong, experienced admins, agile coaches, and program managers. These people understood their systems well, had dealt with different use cases, knew how to get things done, and could quickly escalate issues internally.

To make this work, we needed to establish a clear separation of responsibilities:

• Teams, Work was responsible for the technical strategy, migration planning, constraint removal, on-call execution, and troubleshooting.
• The client remained a delivery owner, making all decisions, approvals, and user communications, and was also responsible for final internal readiness.

This allowed us to move faster and respond quickly when things didn’t go as planned.

📌 Takeaways for your migration

You cannot predict every problem or hiccup, but you can be ready to respond promptly when it happens. Here’s what helps minimize the impact and keep things under control:

• Understand your team first. Do you have admins who know your system? Do you know people who can own communication and approvals, someone decisive in the group, someone decisive in the group with the agency to make the call when it matters? If yes, you don’t need one person to do everything. Rely on the right people to fill the gaps.
• Name your risks and their owners early. App developer response times, internal approvals, or UAT sign-offs — these are schedule risks outside the migration team’s control. Identify them before the project starts and factor them into your mitigation or acceptance plans.
• Go incremental, test early, and don’t avoid risks. Move your easiest team first and get fast feedback from your early cloud adopters, but don’t play it too safe. Pick your riskiest projects early, too. Find your power users and involve them: discover the hard problems in the first week, not after you migrate.

The part that made it challenging¶

As you might have guessed, it was the app migration. The customer had thousands of content diagrams and specifications in draw.io, and all of their QA test plans were in Zephyr.

What made this specifically non-trivial:

• Zephyr had no clean migration path from the Server version and required an upgrade first.
• draw.io had ~16,000 diagram pages across 154 spaces, with no native migration tool available.

On top of that, the customer’s team had no prior experience in cloud migration.

The draw.io issue: when a successful migration still felt off¶

Migrating draw.io looked like the easier constraint going in: you export a page from the server, import it to the cloud, and then trigger a reindex for page IDs. Technically straightforward.

What we didn’t anticipate was that the cloud app would render slightly differently from the server version. There was no data loss, only small visual changes. But for users who worked with the app daily, it looked unfamiliar and sometimes felt like the experience was broken.

To address this, we ran a dedicated dry run on the heaviest spaces, collected user feedback on rendering, raised support tickets with draw.io and Atlassian, and confirmed that the differences indeed were purely visual.

At that point, the migration was technically done. But we didn’t stop there.

We also wanted to ensure a better post-migration experience. So we aggregated all collected feedback, iterated on the most common issues, and used it to build an FAQ page before go-live. That single page absorbed a significant chunk of post-migration support noise.

📌 Takeaways for your migration

• Migration is not just moving data; you’re changing the entire experience. Users don’t care about page IDs. What’s important for them is that their diagrams look right and workflows feel familiar.
• Collect feedback early on and turn it into shared resources. The same five questions will come from fifty different people. Answer them once and save a lot of time later.
• Plan your communication strategy like you plan the technical migration. Banners, FAQ pages, group mentions, and a dedicated support channel are not nice-to-haves. This is how you ensure that a successful migration does feel successful and non-disruptive to people using the new tools.

The Zephyr problem we didn’t expect¶

We established and communicated one strict rule upfront: all work stops at 6 pm on Friday. Whatever is on the server at that moment is what we migrate. It was a good decision that helped avoid chaos and reduce the risk of disruptive, last-minute changes.

When the Confluence migration kicked off on Friday evening, ~50 spaces were migrating overnight. Simultaneously, we took a full Jira backup, including attachments (they are not added to a standard backup and are easy to miss). We rebuilt Jira on a replica running 10.3 LTS, restored all content, and installed Zephyr and draw.io on trial licenses. The production environment remained untouched.

Confluence migration finished overnight, and Confluence Cloud became the source of truth. Jira migration followed Saturday morning, we moved ~25 projects, and it also went smoothly.

And then Zephyr delivered the curveball.

So, what has actually happened?¶

Let’s take a step back and look at the way we approached the whole Zephyr migration.

We couldn’t migrate the app directly from Jira Data Center to cloud. The supported path required upgrading it to a newer Data Center version first. In practice, it meant upgrading the actual production instance: a new Data version, a new license, and changes on a live system. This was costly, risky, and hard to justify in the middle of a migration. So we challenged that assumption.

Instead, we spun up a Docker-based Jira Data Center trial instance — a clone, not production. Atlassian confirmed this was a valid approach as we weren’t running production on a trial license. We were simply using it to upgrade and export data. The production stayed untouched throughout.

Next, we ran a dedicated Zephyr dry run on a separate cycle, collected feedback from power users per project batch, and tracked acceptance per team before final cutover. Dry runs completed cleanly. We had every reason to expect the production run to succeed.

As you already know, it didn’t.

Every production run failed at 80% or at 95% across different batch combinations. The same result every time.

What was going on behind the scenes¶

The root cause, which we only understood after escalating to both SmartBear and Atlassian, was a platform-level change: on our cloud instance, Zephyr had been migrated from Connect to Forge.

Our dry runs ran on the Connect version, while the production was already on Forge. The two handle data inconsistency differently:

• Connect marks incomplete migrations as incomplete at a fixed 98%.
• Forge marks them as failed with a variable percentage.

The same underlying data issues, but completely different surface behaviors. This is why dry runs passed, and production failed. It wasn’t our configuration. It was a platform transition we had no visibility into, and — as SmartBear’s team confirmed — could not have anticipated or avoided.

SmartBear’s engineers did a thorough forensic analysis. The affected scope was narrow: 8 custom field values tied to test steps in one project that wasn’t included in the migration scope, and 4 orphaned attachment references that didn’t exist in the file system. These were legacy inconsistencies in the Data Center database that the cloud’s stricter data model surfaced and rejected. Both were safely ignorable. The rest of the migrated data was intact.

We ran the SQL queries provided by SmartBear to confirm exactly which test cases were affected. The affected project was already de-prioritized by the team, so we accepted the partial result and moved to acceptance testing.

Tough decisions may be necessary, so have a process in place and be ready to act fast.

With the production instance on Forge, rerunning the migration wasn’t an option. You couldn’t just add projects to an existing run, and a full redo would require starting from scratch.

We ran a decision-making session using the DACI framework. Since Zephyr affected 10 QA engineers out of 250 users, and the Data Center stayed read-only as a fallback, no one lost access to their test history. So we decided to go live and fix the issue in production with the support of SmartBear until a full handover.

📌 Takeaways for your migration

• Forge is stricter than Connect on data consistency. Orphaned references that are tolerated in your Data Center will surface as migration warnings or failures in the cloud.
• App developer SLA is a migration risk. Standard support hours may not align with your cutover window. Build that into your migration planning, and either schedule around it or have a pre-agreed escalation path.
• Verify if your marketplace apps are on Connect or Forge, and whether the platform is expected to change. Contact app vendors before your migration window so they know what’s coming and can support you if needed.
• Validate your assumptions. A full production upgrade was the assumed path to migrate. A clone was the actual, much better approach from a cost, risk, and disruption perspective (and it would have gone smoothly, if not for the platform change).
• A successful dry run is not a guarantee of successful migration. If the underlying app platform changes between test and production, the results may not match.
• Be ready to make decisions quickly when trade-offs are unavoidable. We went live with Zephyr unresolved for 10 people. But unblocked work for the remaining 240 users.
• Have a plan for failure. Define rollback strategy, set clear triggers, and agree upon owners who make the calls. In this way, you won’t have to improvise when something breaks on Saturday at 2 am.
• Set a hard content freeze and communicate it early. It will reduce the chance of last-minute changes causing avoidable issues.

The region update: a small change that took an unexpected turn¶

Before the final cutover, we wanted to switch to a cloud region that better aligned with the client’s data residency requirements. We deliberately scheduled it during the canary phase — a week before moving all 250 users — to avoid rushing it alongside the main migration.

Press enter or click to view image in full sizeChanging data residency in Atlassian Administration

What we didn’t fully anticipate: scheduling a region migration in Atlassian cloud is not a background operation. It stops everything and moves immediately.

The canary teams already using Atlassian cloud apps experienced disruption mid-workflow. Fortunately, it happened early enough to become just a helpful lesson before the larger migration. We treated it as an unplanned incident, communicated to all affected users, and used the week before full cutover to confirm stability. By the time we moved everyone, the region was settled and no longer a concern.

📌 Takeaways for your migration

• A region change is a migration event in its own right, so plan it that way. Set a dedicated window and inform your teams in advance.
• Not all Marketplace apps support every Atlassian cloud region. If you have data residency or compliance requirements, verify app-level data residency before committing to a region. Atlassian may store data in one region, but your app vendor may offer fewer options. For example, EU data residency might mean Ireland or Switzerland, depending on the app. It’s easy to check upfront and avoid a potential compliance issue before it’s too late.
• Use your canary migration phase for exactly this kind of risk. It’s better to find a disruption when it affects 10 users, not 250.

What ultimately made it work¶

It was a combination of structural decisions that were made early and held under pressure:

1. Tiered approach from day one. Categorising projects into standard, constrained, and double-blocked before touching any migration tool let us move users to the cloud early, reducing license pressure mid-project while the harder constraints were still being resolved.
2. Dedicated dry-run cycles for each constraint. Zephyr and draw.io had their own dry-run loops, separate from the main migration cadence. Bundling them would have hidden problems until the cutover weekend.
3. Clear ownership, not shared responsibility. Each area, including migration tooling, infrastructure, VM, Azure, and user communications, had one named owner. When something broke at 2 am on Saturday, nobody had to figure out who owned it.
4. We didn’t decommission the Data Center instance, keeping it read-only. The rollback option was available throughout the process. Zephyr users kept uninterrupted access to their test history on the server while cloud acceptance was underway, and such a safety net shaped every go/no-go decision.
5. We kept power users in the loop before every sign-off. Each project batch had a named reviewer who checked the dry-run output before we marked it done. That meant that detected issues surfaced in controlled conditions, not after users were already in the cloud and wondering what had gone wrong.
6. The client team carried their half. Decisions were made quickly, approvals didn’t stall, and internal communications went out on time. A technically clean migration can still fail operationally, and this one didn’t because the client team was as prepared as our team.

We can help you migrate faster¶

If you’re planning a Jira or Confluence migration, the biggest surprises can be the things that remain undocumented: app upgrade paths, region dependencies, memory constraints on VMs, and app developer response times.

We support companies with this kind of migration as a fractional expert: not doing the end-to-end delivery, but stepping in where experience matters the most.

If you’re planning a migration and want a second opinion on your approach, feel free to get in touch.