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?
4 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?
2 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.

3 Likes