Rate this page:
This tutorial describes how to migrate your app from Connect to Forge via the following steps:
If you already have a migrated and tested app, you can proceed to upload this Forge app to your marketplace listing as the next version.
You'll need to set up your Forge development environment and a development site. See Getting started for step-by-step instructions on setting up Forge.
You'll also need a tool to tunnel your local app server to the internet. This tutorial will use ngrok, which can be downloaded for free from ngrok.
Note, it's not necessary to log in with an ngrok account to use the basic tunneling features.
Create a new migration branch in a local clone of your connect app.
If you have an established practice for starting up a local instance of your Connect app, you can skip to step 4.
If you don’t have an app of your own to test migrating to Forge, clone the branch of this simple sample connect app:
git clone firstname.lastname@example.org:atlassian/connect-on-forge-alpha.git -b migration
Start your internet-facing tunnel. If you’re using ngrok with the sample app, run
In a separate terminal window, start your app.
If you’re using the sample app, first edit the variable value near the top of the file to match your internet-facing tunnel URL, then run
Install the app on a test site, so that you can test migrating the installation once the app has been migrated on to Forge. If you don’t know how to set up a test site, follow this step to get a cloud development site, and this step to install your locally-running Connect app on to your development site.
Everything is now in place to begin the migration of your Connect app’s functionality to Forge.
You can migrate your Connect app functionality by making use of , re-writing with new Forge , or a combination of the two.
For more details on states of app migration, see this blog post.
An in-depth discussion of how to approach swapping your Connect modules for Forge modules is beyond the scope of this tutorial, but Connect module equivalents is a good place to start.
Re-writing with Forge modules is more work, but brings with it the convenience, increased security, and trust of Atlassian hosting and running your code for you, while taking care of authentication.
To see the sample app re-written with Forge modules, run the following commands:
git merge origin/migration-rewritten-with-forge-modules npm install
Forge also has backwards-compatibility with Connect modules, but please note there are currently gaps in what is supported. See the known limitations and known issues section for more information.
Migrating Connect modules on Forge is a more mechanical process of copying data from the Connect descriptor to the Forge file.
To see the sample app migrated using Connect modules on Forge, run the following commands:
git merge origin/migration-with-connect-modules
Regardless of which method you choose, you will need to register your Forge app and set the to match.
Run the command and provide a name for your app. This adds an to the Forge .
Edit the Forge manifest as per the example below. Adding a field indicates to Forge and Connect that this Forge app is the successor to your Connect app with the same key.
1 2 3 4
app: id: <the-unique-id-of-your-app> connect: key: <your-connect-key>
If you’re using Connect modules, you’ll also need to configure a base url. This is done by adding an entry under the top-level remotes field of your manifest, then referencing its key under . For example:
1 2 3 4 5 6 7 8
remotes: - key: connect baseUrl: https://hello-world-app.example.com app: id: ari:cloud:ecosystem::app/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee connect: key: hello-world remote: connect
Run the command, so that Forge picks up the changes to your app and creates a new version.
Note that your Forge app has three environments, , and , and each can have its own Connect key. It is recommended you edit to add a suffix to the key of the development and staging environments before deployment, so that the different environments do not clash with one another on a test site. See this script for one way to automate this step.
You’re now ready to migrate an existing connect installation over to the Forge version. This is as simple as running and targeting the existing Atlassian site. The sync process will note the matching keys and replace your Connect app with the Forge successor. In testing, some care is required to avoid overwriting the wrong app by unintentionally setting a matching key. In production, this is less of an issue because Atlassian Marketplace ensures that each app’s key is unique.
Once you have run , you can visit the test site to inspect the result.
From this point, you can proceed to upload this Forge app to your marketplace listing as the next version.
Although these issues are known to us, we're excited to hear your feedback about how you would prefer these features work or which are the most troublesome for you.
There is no support for migrating saved modules from their Connect types to their Forge equivalents. For example, if a Connect-based Confluence macro is removed and a Forge-based macro added, all existing instances of the macro saved in pages will stop working.
Follow this Jira issue for updates on our plans to address this issue for macros.
Despite having the required scopes, your app may not be able to access restricted resources, such as team-managed projects with custom permissions, or restricted operations, such as deleting projects.
This is being actively worked on, and is captured in this Jira issue.
When updating the of your app, simply redeploying your app will not reflect these changes where the app is currently installed. You must uninstall and reinstall the app via the Forge CLI for these changes to be reflected.
Follow this Jira issue to be updated when work to support rolling updates is begun and completed.
Changes to and require a re-installation, but this is expected behavior because such changes require approval by an administrator.
An app has no direct communication path between the Forge and Connect parts of an app, although they may share data via entity or content properties.
Follow this Jira issue for updates.
Forge does not support Connect apps with internationalized content.
Follow this Jira issue for updates.
Forge does not support dynamic modules. Follow this Jira issue for updates.
Connect-on-Forge does not support user impersonation for Connect Apps. The supplied in the installation hook payload is not compatible.
There are currently no plans to address this, but there are plans to remove the need for individual user consent from Forge user impersonation.
Forge does not support Connect apps using the new data residency API.
There are currently no plans to address this, but Forge data residency support is in the works.
A paid connect app ( in the descriptor) must be replaced by a paid Forge app (), and an unpaid Connect app by an unpaid Forge app.
The licensing status of the app can not be changed until all installations have migrated to Forge.
There are currently no plans to address this, as it only affects apps that are in the process of migrating.
An update that migrates the app from Connect to Forge shows as a new installation in the audit log.
There are currently no plans to address this.
If you would like assistance in migrating your app from Connect to Forge, have feedback about Connect-to-Forge migrations, or if you discover anything unexpected during your testing, please get in touch under the Forge topic and forge-connect tag on the Atlassian Developer Community.
Rate this page: