RFC-122: Cloud Site Migration Mode

General Request for Comments (RFC)
, , ,
1

RFCs are a way for Atlassian to share what we’re working on with our valued developer community.

It’s a document for building shared understanding of a topic. It expresses a technical solution, but can also communicate how it should be built or even document standards. The most important aspect of an RFC is that a written specification facilitates feedback and drives consensus. It is not a tool for approving or committing to ideas, but more so a collaborative practice to shape an idea and to find serious flaws early.

Please respect our community guidelines: keep it welcoming and safe by commenting on the idea not the people (especially the author); keep it tidy by keeping on topic; empower the community by keeping comments constructive. Thanks!

Project Summary

Atlassian is exploring introducing “App Migrations – Cloud Product Migration Mode”, which would provide apps an expanded set of permissions during server-to-cloud migrations. The goal is to reduce the number of failed app migrations caused by differences in how permissions are handled between Atlassian’s server and cloud products.

We are exploring automatically enabling a new migration mode on the destination cloud site for the duration of a server-to-cloud migration, and then disabling it once the migration is complete.

  • Publish: 29 December 2025

  • Discuss: Until 26 January 2026

  • Resolve: Estimated to be by 9 February 2026

Problem

Atlassian is developing a migration mode for Confluence that will be activated automatically on a destination cloud site when a server-to-cloud migration runs.

In today’s model, apps participating in server-to-cloud migrations are often denied access to restricted content that they still need to read or update as part of the migration. A common example is when an app needs to transform IDs or URLs in macros that change as content is moved from server to cloud. Similar issues arise whenever an app needs to adjust data it owns within a space that is restricted to it in cloud.

Because those permissions are stricter in cloud than on server, app developers can’t reliably perform all the transformations they need, even though they are responsible for the data.

This gap is most clearly visible in the long-running issue MIG-837. By addressing this problem, we aim to:

  • reduce friction and failure rates in app migrations

  • improve migration reliability for customers and app developers

  • remove a long-standing pain point that app developers have had to work around themselves

Who are we solving for?

App Developers

We want to:

  • Allow apps installed on a destination cloud site to access restricted content for the duration of a server-to-cloud migration, where that access is required to complete the app’s migration logic. This should:

    • reduce failure modes that app developers currently cannot mitigate due to cloud permission constraints

Customers

We want to:

  • Reduce the number of failed or partially-complete migrations, especially during test runs

  • Reduce the manual effort required to coordinate with Atlassian and app developers support to repair or re-run migrations

Proposed Solution

This section is work in progress and we are especially interested in feedback from app developers on the approach and scope.

At a high level, Atlassian intends to:

  1. Automatically detect when a space migration (server-to-cloud) begins.

  2. Enable migration mode on the destination cloud site for the relevant apps.

  3. Keep migration mode active:

    • from completion of the space migration,

    • until all apps involved in the migration have reached a “settled” state (no further migration activity),

    • or up to a maximum of 14 days after the app migration started — whichever comes first.

  4. Disable migration mode once these conditions are met.

While migration mode is active, installed apps will be granted temporary, scoped access to content that would otherwise be restricted at the user level, so that they can identify and modify the content they own or depend on for migration.

We want to minimise the scope of this access while still ensuring that app developers have the permissions they need to complete migrations successfully. Our current proposal is that an app should be able to access content under migration mode when at least one of the following is true:

  1. The app has a macro on a page → the app should have access to that page.

  2. The app owns custom content on a page → the app should have access to that page.

  3. The app owns a content property → the app should have access to that content property (and whatever is minimally required to read/update it).

The intent is that migration mode:

  • is orchestrated entirely by Atlassian and compatible with all existing CCMA integrated app migrations,

  • is time-bound and automatically cleaned up,

  • is scoped to content the app already owns or is clearly associated with, and

  • is only used to support migration-related operations, not ongoing runtime behaviour.

We will refine the exact rules and technical implementation based on feedback to this RFC.

Asks

We welcome any feedback and we are particularly interested in input from app developers on the following:

  1. Does this approach address the core issues behind MIG-837 for your app(s)?

    • Are there specific failure modes you see today that this proposal would not resolve?

  2. What types of content does your app need access to during a migration?

    • Pages with your macros?

    • Custom content you own?

    • Content properties?

    • Any other Confluence entities or data types that would need to be in scope?

  3. Are there additional constraints or safeguards you think we should include?

    • For example, further scoping rules, audit requirements, or visibility for customers app developers.

  4. Are there scenarios where this migration mode would still not be sufficient to complete your migrations?

    • If so, what additional capabilities would be required?

Your feedback will help us tune the scope of migration mode and ensure it provides enough access to be useful, while remaining safe and predictable for customers.

1 Like
2

Hi @AlanOoi, thanks for the RFC.
This would probably solve a lot of the issues we’ve encountered.

We do need access (read & write) to Confluence pages containing our macros (For us, the macro keys are different on DC and cloud by the way), and content properties.

Remarks:

  1. Disabling migration mode when the app is settled might not be enough.

Due to the nature of migrations in a forge backend that time out after 15mn, we might be forced to mark the migration as settled while the work continues in a background job (https://developer.atlassian.com/platform/forge/runtime-reference/async-events-api/#async-events-api).

We would need an additional API to disable “migration mode” once the migration is truly complete.

  1. While we would probably not have a use for it, I could see a scenario where apps would like to know that they are in “migration mode”.

For instance: Showing a warning when the app permissions are not sufficient after the migration period has passed

Regards, Corentin.

1 Like
3

Hi @AlanOoi

This is a great start. Thanks for putting this into an RFC!

The “scoping of content” piece should also include real-world cases where different models are used on DC vs Cloud. The RFC assumes a 1:1 mapping between DC/Cloud macros, custom content and content properties, but this is not necessarily the case. For example, a DC app might store metadata about content objects in its own ActiveObjects table. On cloud, this could be transformed to store data in-app and thus be represented as a content property associated with specific content.

Possibilities for solving this problem might include:

  • asking the apps themselves to declare (via CCMA) the content IDs and other objects that they need to be able to manipulate on Cloud, or
  • just allow apps to access all content in the space during the migration window. I understand the intent behind the minimization of scope, but apps can access 100% of this pre-migrated data anyway on DC, so maybe this is less of a concern? This behaviour could be mitigated somewhat by only providing this scope of access for API calls that include the migration header, so as to prevent regular app code path from triggering this extended access.

Apps may also need to write to arbitrary space properties, despite there not necessarily being a 1:1 map on the DC side.

4 Likes
4

Hi @Corentin :waving_hand:

Thank you for your comments and the useful information :slight_smile:

We would need an additional API to disable “migration mode” once the migration is truly complete.

My ideal scenario would be that all of the tasks necessary for migration would be done before settling a migration – but I appreciate the limitation you have mentioned here. The introduction of an additional mechanism to decouple the disabling migration mode from the settling of transfers definitely seems viable.

I would love to know more about how you are handling migrations today to forge as it will certainly help not just here, but also future forge migration efforts. However, this may be slightly off topic for the current RFC and I will reach out across another line of communication instead :slight_smile:

Thank you again for the comments!

5

Hi @scott.dudley

I’m glad to hear that this resonates with you :slight_smile:

The “scoping of content” piece should also include real-world cases where different models are used on DC vs Cloud.

I believe this is the part of the RFC where we will most benefit from yours and others feedback.

Considering just the two options you listed there (roughly “apps declare content for modification” vs “complete access”), could you provide an indication as to which one you believe would address your needs? and the needs of others if you have any insight to share on that :slight_smile:?

Thanks again!

6

Hi @AlanOoi

First of all, thank you for the RFC. This is an important topic for us.

From our side, some questions arise regarding the scope of the proposed restrictions:
Regarding point 2

  1. The app owns custom content on a page → the app should have access to that page.

what does “owns custom content on a page” mean exactly?
During the migration process, we create new custom content on the migrated pages. Since in Data Center there is no concept of custom content as such, it is unclear what is meant when stating that the app “owns custom content on a page.”

Additionally, point 3 appears to contradict point 2:

  1. The app owns a content property → the app should have access to that content property (and whatever is minimally required to read or update it).

Granting access only to the content property would not make sense. We understand that if we need to create a content property, we should also have permissions on the pages where those properties are created.

As @scott.dudley remarks, it seems that the RFC assumes a 1:1 mapping between DC/Cloud macros, custom content and content properties, we think that the CCMA must be adapted to real-world cases, such as the creation of new custom content or content properties.

Instead of proposing the 3 points scope restrictions, in the same way the rate limit is adjusted within the migration process, the permissions scope should also be adjusted for the apps in the process.

I hope this helps us improve the migration process.

3 Likes
7

Hi @JosebaAlonso

Thank you for your engagement on this RFC.

As I mentioned earlier, this was the area we felt we needed the most feedback from the community and we’re glad to have received your thoughts on it.

Based on your feedback, we are leaning towards adopting the suggestions here to provide unfettered access into the restricted spaces for the duration that the cloud site is in the migration mode. We believe that should address the initial assumptions in the RFC about a 1:1 mapping between DC/Cloud content. Concretely, we believe it should allow for the creation of new content where needed as part of a migration.

I hope this helps address your concerns and thank you again for the feedback and engagement.

8

Getting back to this after the holidays:

Either “declare content” or “complete access” would work for me.

The “declare content” might be a trickier to implement on your side (and on the declaration side). For example, the permissions would need to extend to the ability to create related objects (such as creating new content properties on existing contentIds). You would also need to find some way to allow apps to declare “we need to be able to create arbitrary space properties”.

So long as this were implemented properly, either option could work…but “complete access” is certainly less hassle for everyone involved and there are fewer edge cases.

1 Like