RFC-86 Bitbucket Connect to Forge: Input on the Migration Process

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.

Project Summary

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!

Hi all - This RFC gathers input on the process of directing customers to install a new Forge version of an existing Bitbucket Connect app. This scenario applies for Forge apps that have been built as a direct equivalent to an existing Bitbucket Cloud Connect App. For clarity - this is not the same process as Jira & Confluence apps that are “incrementally migrated”. This RFC will gather feedback on a single aspect of that journey: input on the process of transitioning the installations from the Connect version of your app to a new version re-built in Forge.

  • Publish: February 20, 2025
  • Discuss: March 13, 2025
  • Resolve: March 27, 2025

Problem

The Bitbucket Cloud team is working to support partners migrating from Connect to Forge apps. Unlike Jira and Confluence, Bitbucket’s Connect implementation has differences that prevent an identical migration path. However, we want to collaborate with partners to minimize migration challenges. This RFC explores options to streamline the process. Our primary focus is simplifying the installation of Forge apps as replacements for existing Connect apps, aiming to reduce friction and enhance the overall migration experience.

Several key issues need to be addressed:

  • Customer notification: There is no way for partners to easily notify customers about the availability of the new Forge app. In-app notifications within the existing Connect app could help users stay informed about the migration.
  • Migration process: Admins must manually install the Forge app, and there is no clear path to guide them to the correct place or provide explicit instructions for the installation process.

Adopting Forge from Connect

We understand that moving an app to Forge has extra considerations, and we are looking for feedback on what is specifically relevant to your app—such as Bitbucket modules, data migration, events, and other platform-specific features. However, please be aware that this RFC is specifically related to the process of supporting customers discovery and transition their existing app installations from Connect to a Forge equivalent. Please share any requirements in regard to converting your existing Connect apps to Forge on this thread, and we will continue the conversation there.

Potential Options

This is an initial idea aimed at simplifying the installation process, which comprises two key components. We invite your feedback and suggestions to help refine this concept. We view this as a starting point for discussion and are open to exploring additional approaches.

  • “Warm-handover” for customers from Connect to Forge installation:
    • Utilizing the existing Distribution Link for their “Connect Equivalent” Forge app, partners would be able to add the link to their Connect app descriptor.
      • This would make it possible for Bitbucket systems to programmatically associate a specific Forge app distribution link with a particular Bitbucket Connect app.
    • Once complete, this association would allow us to show information (UI elements) in the current Connect app management screen via the Bitbucket Workspace settings to link users to install the Forge version.
      • This information would make it clear to the Workspace admin that action needs to be taken in order to continue using the respective app, and provide them with a direct link to the Forge app installation workflow.
  • Proactive notification to Workspace Admins of required action:
    • A UI component would be displayed in the Workspace Settings view for any workspaces that currently have Connect apps installed for which there is a registered “Forge equivalent”.
    • This notification would be used to notify Workspace admins with a message like “You have Apps installed in your Workspace that need attention,” and providing a link to the App management screen where they would be able to review any currently installed Connect apps and utilize the “warm handover” flow to the associated Forge installation.

Asks

We welcome your thoughts on this RFC and, in particular, would greatly appreciate your feedback on the following questions:

  • Which aspects of the migration process do you feel are the most “high risk” for maintaining customer engagement?
  • Are there any additional features or capabilities you would need to make the migration process smoother?
  • How can we better assist you in promoting your Forge app to existing Connect customers?
5 Likes
2

Hi @HamreetKaur, thank you for the post.

After reading this RFC, I couldn’t form a clear picture of what the happy path for migrating an application from Connect to Forge would look like without using the intermediate Connect-on-Forge stage. Could you please clarify the following questions:

  • You mentioned that the user will receive a notification indicating that a Forge version of the application is available for the given Connect application. What happens if the user installs the Forge application via the button in the notification?
    • Will the user still have the Connect application while also installing the Forge version of the application? In this case, will events from Bitbucket be sent to both the Connect and Forge applications, leading to duplication on the backend? Will the user interface display two identical application icons?
    • Or will the Connect application be automatically removed? If so, will an uninstall webhook be triggered for the Connect application and an install event for the Forge application?
  • Will we be able to match the installation of the Connect application with the installation of the Forge application to avoid losing customer data after migration?
  • Will there be any official way to transition from PvV to PvA?
2 Likes
3

Seconding @YuriKarnilaev 's questions.

Given the fact that there will be a production connect app AND forge app:

  1. Can you please detail how the vendor lists the forge equivalent on the Atlassian MP as part of the same listing as the current connect (and in some cases DC) app.
  2. Can you please elaborate on the forge-app install flow via Atlassian Marketplace and it’s little cousin the Bitbucket workspace marketplace.
  3. What are your expectations/ideas migrating a PvV connect app to forge?
4 Likes
4

Hi @HamreetKaur thanks for starting this discussion.

Our apps have mostly a file-based configuration, so both migration approaches would be fine. Although we would prefer a warm handover.

Same as @UlrichKuhnhardtIzym1 we wonder about the marketplace listing. It would be great if we could keep the same listing.

Also, please consider allowing linking multiple connect apps to one forge app as we would build one new app with the functionality of a few existing connect apps.

Thanks!

1 Like
5

Hi everyone - just a quick FYI to let you all know that we’re reviewing all the responses here and will be providing our own in the next few days. We will probably have a few additional questions following a few of the posts here, so please keep an eye out.

We will tag all relevant people as we respond to each seperate suggestion/point - so you should receive notifications for anything that requires your input.

4 Likes
6

Hello @EdmundMunday - any updates on this case? 14 days ought to be more than a few. :slight_smile:

5 Likes
7

Checking in here after a further 28 days, partly because I’ve seen threads get locked after 30 days inactivity and I want to avoid that

3 Likes
8

Hey @EdmundMunday @HamreetKaur

We are now 50 days since the last reply from Atlassian that we would get an update. I really hope that you are both ok and still working with Bitbucket Cloud, and that the silence is a sign of the hard work going into finally making PvA available for Bitbucket Cloud. :raising_hands:

9

Hi everyone, massive apologies from myself - unfortunately I had some pretty serious stuff happen in my personal life just as I landed from TEAM25, so had to disappear for a few weeks.

@UlrichKuhnhardtIzym1:

  • Proxy module + ROA:
    • Given that it’s a condition for RoA that the App doesn’t use any “Remotes”, all the App logic would need to be running inside Forge functions.
    • If the app logic is running inside a Forge function, the function can simply call the BBC API directly and hydrate whatever extra data it needs.
    • Additionally, Forge already supports the “asUser” auth mechanism to only allow API calls to access resources available to the user making the request.
  • User Profile UI Module
    • Because users exists outside the context of a specific workspace, Forge apps cannot actually operate purely in the context of a user (due to apps being installed in the context of a workspace).
    • Instead, we’ll introduce a WorkspaceSettingsAction UI module that apps can use to render a stand-alone user-specific settings modal based on the user context provided by Forge.
    • This avoids the complexity of a user-profile-specific module outside workspace context and aligns with Jira/Confluence patterns (e.g., a “My-App Settings” page in the “More” dropdown).
    • This would be in addition to a global WorkspacePage UI module that would be triggerable from the “More” dropdown in the top nav.
  • Project settings UI module.
    • Project settings is a high priority add and will be done as part of this process.
    • In addition to that , we will review all the main Project-level screens to see if there’s any other high-value locations to add UI modules.

@JanNylund:

  • The FileViewer UI Module will be added as part of this process.

@YuriKarnilaev:

  • Profile tab UI panel
    • Please see previous response.
  • Proxy Module (Can web-triggers/remotes solve this?).
    • Please see previous response.
  • Business events: repo:transfer, pullrequest:superseded, pullrequest:approved, pullrequest:unapproved
    • repo:transfer We will look at enhancing the existing repo created/deleted events to include an indication that the event occurred in response to a transfer request. There are privacy considerations that have to be factored in here due to the workspace boundaries.
    • Review Status: Current event “review status updated” doesn’t include the new status.
      • We will update this to include this information, in addition to the reviewers.
    • pullrequest:superseded is not currently available for Connect apps in Bitbucket Cloud.
      • What use-case is this needed for that would not be covered by the pullrequest:updated event?

@christian.ott:

  • Profile tab UI panel
    • Please see previous response.
  • Code Insights Annotation UI module
    • This is something we’re considering for future enhancements, but not a “must” for this program.

@joshp:

  • File viewer module: We are planning to add this as part of this program.
  • File editor module: This is not currently implemented by any publicly available Connect app, so is not considered a dependency. It is highly likely that this will be ported to Forge in the future though.
  • Global page, similar to Jira, Confluence, Compass: This will be implemented as part of this program, triggering from the global “More” dropdown in the top nav.

Response to general RFC:

  • What happens if a user installs a Forge app via a Connect app notification.
    • The simple answer is that we would NOT provide any kind of automated uninstallation flow, and this would need to be managed by users/vendors.
    • The reason for this is simply that it’s extremely risky to have some kind of automated process, especially in regards to data retention etc, and would actually make MORE work for vendors.
    • It would effectively force all vendors to build some kind of “single-shot” automated migration process. Our view is that a manual uninstallation flow gives users and vendors the most flexibility, and so is preferred.
    • Vendors will need to manage de-duplication using event installation contexts or UI conditions if they do not want users to temporarily see duplicate apps in the UI.
  • How would the vendor link the new Forge equivalent app in the Atlassian MP as the Same listing as the current one.
    • TBD - we need to look into this further, but we wanted to validate the idea before going into it too far.
    • We have already started the conversation with Marketplace to understand how this would work.
    • Given all BBC apps are unpaid, this is probably less complicated than it would be if there was payment involved.
  • What would the install flow look like from the Marketplace/Bitbucket marketplace?
    • All installations would be centralised via the Atlassian Marketplace.
  • What would be the expectations around Paid-via-Vendor connect apps to Forge.
    • Given Forge supports PvV, we would expect it to operate the same as any other product.
    • Are there specific issues/scenarios you are concerned about?
  • Would we support linking multiple Connect apps to a single Forge app as an upgrade path?
    • In Bitbucket, yes - you would be able to point multiple Connect apps to a single Forge app as a “replacement”.
    • But not when it comes to actual app listings in the Marketplace. Vendors would have to pick a specific Marketplace listing that they want to “transfer” to an equivalent Forge app.
    • Ideally keeping all the reviews and history, etc that was originally there. But we would not support merging multiple Connect listings into one.
    • NOTE: Anything related to marketplace listings is still TBD.

Summary:

UI Modules - Must Have

  • Workspace Settings Action (Global dialog from a new menu item under the cog in the top-right)
  • File Viewer
  • Project Settings page
  • Global page (Global dialog from a new menu item under the “More” dropdown in the top-nav)

Events/Event modifications - Must Have

  • More data to the “status updated” event for pull requests, make sure we’re including all relevant context.

UI Modules - Should Have

  • File Editor
  • Code Annotation
  • PR Comment

App migration - Must Have

  • Some way for a Connect app to register a Forge app as it’s “replacement”.
  • Some kind of process to notify workspace admins that they have a Connect app installed that has a Forge replacement.
  • A link from the Connect app install listing to the relevant Forge app listing.

App migration - Should Have

  • A way to migrate a Marketplace listing for a current Connect app to a replacement Forge app.
6 Likes
10

@EdmundMunday I’m quite concerned about the timelines and expectations for partners migrating their apps to Forge, especially given how heavily we rely on Connect features that still need to be ported over before we can proceed on our end. How can we possibly update if the functionality is not there?

So far, in addition to what have already been reported by others here, I’ve identified the following missing functionalities that our app uses, which are available on Connect, but either not supported on Forge or lack a clear migration path:

We need a better support from Atlassian on the migration process, in terms of communication and technical support. Simply saying that Atlassian is committed, without providing effective support and not porting the features needed, is meaningless.

Can we please get an update and dates when these functionalities are expected to be available? Are the EOL dates being pushed back since the feature parity is not there yet? The only dates Atlassian has communicated so far are when things will reach EOL or will stop working.

11

@EdmundMunday I have got 2 more items that need to be addressed for a smooth forge integration

  1. Project-level branch restriction REST API is completely missing: https://jira.atlassian.com/browse/BCLOUD-22732
  2. Forge apps cannot read any workspace/repo/pr/user properties via API. Our app has everything stored as properties. How would a migration work if the Forge app cannot copy ACE app settings stored as properties?
1 Like
12

@Renato (Garcia?) - your 1st point ‘Conditional rendering using application props’ points to the same destination as your 2nd ‘Groups endpoint’. Could you clarify? I think I am facing the same problem: I noticed that forge apps can’t read properties because these endpoints do not support the required auth schemes (see here)

1 Like
13

@UlrichKuhnhardtIzym1 Thanks! I’ve fixed the links. Yep, same problem, as well as unable to it in the descriptor conditions to show/hide UI elements.