Link Connect app to its Forge equivalent

Let workspace admins discover and install the Forge version of your Connect app in Bitbucket. Add the Forge installation link to your Connect app descriptor under the forgeAppLink key, then update installations based on whether your app is Shared or Classic.

In addition, you can register a Forge app ID in your Connect app descriptor under the forgeAppId key. This allows your Forge app installation to retrieve the clientKey of its equivalent Connect app in the same workspace using the Addon API.

1. Update Connect descriptor with Forge app link

1. Share your Forge app to get its installation link.

2. Add a forgeAppLink key to the root of your Connect app descriptor JSON, using the Forge installation link as the value. For example:

   1
   2
   {
     "key": "my-connect-app-key",
     "forgeAppLink": "https://developer.atlassian.com/console/install/my-app-id?signature=1234567890&product=bitbucket",
     ...
   }
   

2. Update installations by your Connect app type

Before updating the installations, ensure that you're serving the latest Connect app descriptor with the forgeAppLink changes. The steps to update installations differ based on whether your app is Shared or Classic.

After updating the installations, workspace admins will see a new Get the Forge app link in their Manage installed apps page. This provides a direct link to install the Forge version of your app.

Next steps

• Verify that the Get the Forge app link shows up in the workspace settings.
• Notify customers that a Forge version of the app exists, and recommend that they upgrade to it.
• Monitor installations and errors..

3. Update Connect descriptor with Forge app ID

You only need to do this if you want to access the Addon API from your Forge app installation, in order to retrieve the details of the equivalent Connect app installation.

1. Copy the full Atlassian resource identifier (ari) in the app.id field from your Forge app manifest file.

2. Add a forgeAppId key to the root of your Connect app descriptor JSON, using the ARI from above as the value. For example:

   1
   2
   {
     "key": "my-connect-app-key",
     "forgeAppId": "ari:cloud:ecosystem::app/00000000-0000-0000-0000-000000000000",
     ...
   }
   

3. Follow the instructions above to update your app installations.

Next steps

• Read the endpoint doc to learn how to make the api call for retrieving the Connect addon clientKey from your Forge app.