I’m exploring using forge version bulk-upgrade to upgrade our app across customer installations, and I’m trying to understand the limitations and potential
gotchas, especially around major version upgrades.
A few specific questions:
What happens if there were significant changes between the major versions, like new permission scopes being added? Will the upgrade fail, or will customers be prompted to approve the new permissions?
When a bulk upgrade happens, do customers or their admins see any notification or approval screen? Or does it happen silently in the background?
Are there any other reasons why a bulk upgrade might not work or should be avoided?
What happens if there were significant changes between the major versions, like new permission scopes being added? Will the upgrade fail, or will customers be prompted to approve the new permissions?
If the target major version introduces new scopes or egress permissions that constitute a privilege escalation, the bulk upgrade will be blocked entirely. It will not fail mid-process. The platform performs a pre-validation check that compares the scopes between the source and target versions. If an escalation is detected, the upgrade path will not be made available. In this case site admin has to manually accept and update the app in Connected Apps page.
When a bulk upgrade happens, do customers or their admins see any notification or approval screen? Or does it happen silently in the background?
Bulk upgrades proceed without per-site admin approval — this is by design. Neither customers nor their administrators will see an approval screen or consent prompt. Installations are upgraded silently to the new major version. This is permitted only because the platform has already verified that no privilege escalation is involved.
Are there any other reasons why a bulk upgrade might not work or should be avoided?
Cross-major upgrades are blocked by default — you need to pass the --major flag explicitly to allow v1 → v2 upgrades.
No rollback — once done, you can’t undo it via the CLI. You’d have to deploy a fix and upgrade again.
Different app environments — source and target versions must be in the same environment.
Very few admins actually update apps on a regular basis. As soon as you add a new permission or egress (which is sometimes unavoidable), you will likely leave behind most of your customers on an older version either permanently or for an extended time, with very little means to encourage them to update.
We moved an app from Connect-on-Forge to Forge, and as part of this move we now store config data for the app in Forge KV (previously stored in a Postgres db that we hosted externally), which required the addition of storage:app scope (a permission elevation over the previous version).
So far, less than 2% of our install base is on the Forge version, meaning that our Connect infrastructure must remain in place and costing us money, and there is no sight yet of when (if ever) we will be able to decommission it.
Yep, I’ve been banging on about this for years. Backporting is not a solution. Bulk-upgrade is not a solution. Atlassian signals a complete misunderstanding of the problem when these two are referenced.
The direct casual line of events that will play out for every app:
Major version triggered for whatever reason (typically a deprecation).
After 12 months you’ll have 70-90% of installs on the outdated version.
The longer end-users remain stuck on old apps the less they will use them.
Most admins do not manually update apps but they do routinely cull unused apps to cut costs - if you’ve ever had a support ticket asking about usage that’s what that is.
Result: very low app usage, zombie apps and revenue losses marketplace-wide.
First happened to me with UI Kit 1 apps I built on Forge. The forced migration to UI Kit 2 also came with a forced permission scope change.
It’s inevitable that every marketplace app will have a major version event sometime in the future with the changing nature of Forge and the granular scopes.
Rolling Releases (EAP) is a partial solution but merely shifts the need for an admin to manually update an app to the admin needing to manually approve permissions.
Currently there is no admin notification system in place and partners report that in-app messaging doesn’t work. “We’ll improve this in the future” is not a viable answer from Atlassian if retroactive changes cannot be made to any Forge app that enters this state.
I’ve completely exhausted all contacts and channels to express this existential risk.
Concur with you @nathanwaters. It appears the people making this decision are solving for a different problem.
I find it bemusing that admins can install a marketplace app without once looking at the scopes, but somehow that fine grained list of permissions they don’t understand and never saw is part of an immutable contract.