Anatolii Starshekov
Apr 30, 2026
Read 10 min
The Connect to Forge migration is the biggest infrastructure shift Atlassian app vendors have faced in a decade. After 2026, the Connect framework stops receiving updates entirely: no patches, no exceptions, no "we'll look at it next quarter."
Most vendors know this. Most have a plan. And yet, project after project, we see the same Forge migration mistakes derail those plans, costing teams months of engineering time, missed deadlines, and frustrated customers.
Below are the seven traps that cause the most damage and what to do instead.
If you're still building the internal case for migration, our partners at Peakforce published a clear breakdown of why Forge migration is non-negotiable and what's at stake. Read that first if you need the executive summary. This article picks up where that one ends with what actually goes wrong on the way there.
This is the costliest mistake by a wide margin, and almost every vendor makes some version of it.
The thinking goes: "We have a working Connect app. Forge is the new framework. We just port the code over." Two engineers, a couple of sprints, done.
It doesn't work that way. Forge isn't a new SDK bolted onto Connect. It's a fundamentally different operating model. Under Connect, your backend lived wherever you wanted, your frontend talked to whatever services it needed, and Atlassian gave you a webhook and an iframe. Under Forge, your app runs inside Atlassian's infrastructure, in their sandbox, under their rules.
What this means in practice: a lot of patterns you took for granted simply don't carry over. Direct calls from your UI to your backend now need to go through Atlassian's bridge APIs. Third-party scripts loaded from a CDN may not run inside the Forge sandbox. Custom styling that depended on reading state from the parent page needs an entirely different approach.
What to do instead: plan a redesign with constraints, not a port. Map every Connect feature to its Forge equivalent (or workaround) before you write a single line of code. The teams who skip this step end up rewriting the same module two or three times.
The engineering side of Phase 1 - wrapping your Connect app with a Forge manifest - takes around two weeks of focused work. That's the number teams plan for. That's the number that ends up in the project timeline.
What gets quietly skipped: Marketplace approval can add another two weeks on top, sometimes more if your app touches anything sensitive or has complex integrations. We've seen vendors finish their code on schedule and then watch a perfectly polished app sit in queue while their go-live date drifts further away every week.
What to do instead: open the Marketplace conversation in parallel with the engineering work, not after it's finished. Submit early drafts. Build a relationship with your reviewer. The teams that pass approval on the first round are almost always the ones who started the conversation months before submission, not days.
This one bites teams on day one of production rollout.
After the Phase 1 wrap, some app installations can land in a weird state, appearing installed when they aren't, or vice versa. It complicates uninstall flows, breaks update logic, and produces support tickets that look impossible to debug because the system itself disagrees about whether the app is even there.
The fix is straightforward, but only if you catch it before customers do. Most teams don't, because their staging tests focus on functionality (does the app work?) rather than installation lifecycle (does the install state match reality?).
What to do instead: before every rollout wave, run an installation lifecycle audit on staging tenants. Install, uninstall, reinstall, upgrade, downgrade. Verify state at every step. Five extra hours of testing here saves you a weekend of emergency support work later.
Forge supports staged migration for a reason. Use it.
The temptation is to "just flip everyone over" once Phase 2 is ready. It feels cleaner. It's faster on paper. It avoids the awkwardness of running two versions of your app in parallel.
In practice, vendors who try this pay for it almost immediately. Something always breaks under real-world load that didn't show up in staging - an edge-case API behavior, a CDN dependency, a customer with an unusual configuration. When 100% of users are already on the new version, you have nowhere to roll back to without downtime.
What to do instead: migrate 5% of customers first. Watch what breaks. Fix it. Move to 20%. Then 50%. Then the rest. Yes, this means running Connect and Forge versions in parallel for several months. That's not a bug in the plan, it's how migrations are supposed to work.
Atlassian markets UI Kit as the long-term goal. It's faster to load, easier to maintain, and aligns automatically with Atlassian's design language. All true.
What's also true: only about 60% of apps can realistically reach UI Kit. The rest stay on Custom UI permanently, and there's nothing wrong with that.
UI Kit is more constrained than Custom UI by design. Complex visualizations, rich client-side interactions, custom drag-and-drop, sophisticated form workflows - UI Kit will fight you on all of them. Vendors who don't honestly evaluate this end up six weeks into a UI Kit port, hitting limitations they can't work around, and rolling back to Custom UI with nothing to show for the time.
What to do instead: before committing to UI Kit, take your most complex screen and prototype it. If you can build it in a week, UI Kit is your target. If you're fighting the framework on day three, stay on Custom UI. There's no prize for reaching UI Kit. The "Runs on Atlassian" badge can already be earned at Phase 2.
The Phase 4 vision, a fully no-egress Forge app, with backend logic and storage living entirely inside Atlassian's cloud, is genuinely impressive. Lower hosting costs, faster compliance reviews, the highest trust signal possible for enterprise customers.
But it's not the right destination for everyone, and treating it as one is expensive.
About 75% of apps can technically reach Phase 4. Some genuinely shouldn't. If your app depends on an external service that's not easily replaceable - a translation API, a payment processor, a machine-learning model you don't want to retrain on Forge — staying partially remote is the correct architectural decision, not a failure.
The decision to go fully no-egress is a business decision as much as a technical one. The badge can already be earned at Phase 2 or Phase 3 depending on how customer data is handled. We've had clients deliberately stop at Phase 3 because Phase 4 would have been a six-month project with marginal benefit. That was the right call.
What to do instead: decide your target phase before you start, based on customer demands, compliance requirements, and architectural fit. Don't drift toward Phase 4 by default just because it's labeled the "end state."
Here are the line items that get cut from migration plans almost every time, and that come back to bite teams in the final stretch:
Documentation refresh. Old install guides, support articles, onboarding emails, tutorial videos - all of them need updating. This is rarely budgeted and easily eats two weeks of someone's time.
Marketplace listing updates. Screenshots, descriptions, support links. Not glamorous, but customers see them first.
Parallel codebase maintenance. You'll be running Connect and Forge in parallel for three to six months. Bugs in either need fixing. Features added to one need parity in the other.
Customer support load. Tickets spike during rollout phases. Support needs extra capacity, and your team needs training on the Forge version before customers start asking about it.
Cross-team enablement. QA, customer success, sales - anyone who talks to customers about your app needs to understand the Forge version. Budget for it.
These extras typically add 20-30% on top of pure engineering effort. Vendors who plan for them finish on time. Vendors who don't always end up apologizing to someone in the last sprint.
# | Mistake | Cost if you make it |
|---|
# | Mistake | Cost if you make it |
|---|---|---|
1 | Treating migration as a refactor | Multiple rewrites of the same modules |
2 | Forgetting Marketplace approval time | 2-4 weeks of stalled go-live |
3 | Skipping phantom install validation | Customer support fires on rollout day |
4 | One-shot migration instead of staged | No rollback path when something breaks |
5 | Forcing UI Kit on a complex UI | 6+ weeks wasted on a port that gets rolled back |
6 | Assuming Phase 4 is the only goal | Months of work for marginal business value |
7 | Ignoring hidden costs | Final-sprint scramble, blown timeline |
Forge migration is real work. It takes time, planning, and a clear-eyed view of what's actually involved. But the mistakes above are avoidable. The vendors who plan for them ship clean migrations on schedule. The ones who don't usually find out about them at the worst possible moment.
If you're scoping a Connect to Forge migration and want a sanity check, book a 30-minute call. We'll look at your app, your Connect modules, and your timeline, and tell you honestly which of these traps you're most likely to hit.
The deadline isn't moving. The teams that start now have time to do this right.
Fill out the form, and we'll guide you through every step of the way
