List a Forge successor to a Connect app

This page covers how to submit your Forge app to the Marketplace in order to replace your existing Connect app.

Before you begin

At this point, you should have already integrated your Connect app with Forge. See Migrate an app from Connect to Forge for detailed instructions (including known issues and limitations).

You'll also need to enable sharing on your app. This will allow you to distribute it via the developer console. See Distribute your apps for detailed instructions.

Read the following details before submitting your app to be listed on the Marketplace.

Ensure your app manages personal data appropriately

If your app stores personal data, it must comply with user privacy requirements, as set forth under applicable data protection laws; this may include the General Data Protection Regulation (GDPR).

It is your legal responsibility to provide accurate privacy and security information about your app, particularly through your app listing�s Privacy and Security tab. See Privacy and Security tab in your Marketplace listing for more information.

If your app supports data residency, you should also provide a complete list of all in-scope End User data.

Follow the Forge user privacy guidelines to implement flows to report and erase personal data as appropriate.

Use the development or staging environment to test paid apps

Forge apps can be deployed to development, staging, and production environments. If you're listing a paid app, you must always use the development or staging environment to test your app. This is because all installations of production paid apps are billed. Even if you're the app developer, if you install your production paid app on your Atlassian cloud instance just to test it, you will be charged for it.

Note that the Forge platform uses a consumption-based pricing model, offering most capabilities for free within monthly usage limits. Learn more about Forge platform pricing.

Step 1: List your app as a Forge app

Once sharing is enabled, you can publish a new app version to the Marketplace by selecting the Forge app.

Step 2: Install the Forge version

Once the Forge version's Marketplace listing is approved, install it. You can do so via Universal Plugin Manager (UPM) or Marketplace.

Option 1: UPM

You should see an available update for your Connect app in the UPM.

Select Update and refresh the page.

Option 2: Marketplace

You can install the Forge app on a new site via the Marketplace.

Troubleshooting

Forge app doesn't appear when creating a new version

When you create a new version for your existing Connect app listing and select Forge as the framework, the dropdown that lists your Forge apps may be empty. This usually means the Marketplace platform can't link your Forge app to your existing Connect listing.

To resolve this, add the app.connect.key property to your Forge app's manifest.yml file. This property tells the Marketplace platform which Connect listing your Forge app replaces.

Step 1: Find your Connect app key

Your Connect app key is the unique identifier from your existing Marketplace listing (for example, com.example.myapp). You can find it in your Connect app descriptor or in your Marketplace listing's management URL.

Step 2: Add the app.connect.key property to your manifest.yml

Open your Forge app's manifest.yml file and add a connect.key entry under app:

1
2
app:
  id: ari:cloud:ecosystem::app/cxxxxxx-xxxxx-xxxx-xxxxx-xxxxxxxxx
  connect:
    key: com.example.yourappkey

Replace com.example.yourappkey with your actual Connect app key.

Step 3: Deploy to production

Deploy the updated app to the production environment:

1
2
forge deploy -e production

Step 4: Try creating the version again

Go back to your existing Connect app's Marketplace listing, select Create a Version, and choose Forge from the framework dropdown. Your Forge app now appears in the list, and you can proceed with creating the Forge version for your listing.

FAQ

How do I rollback a Forge app to its previous Connect app version?

Mistakes happen. In case of an emergency, you can ask our team to manually rollback the migration. To do this, please raise a Marketplace Support ticket under Need help with Marketplace listing?.

How can I do a staged migration from Connect to Forge?

If you would like to follow a staged migration, please raise a Marketplace Support ticket under Need help with Marketplace listing?

Give feedback

We're excited to hear your feedback. Please join us in the Forge developer community.