Last updated Feb 5, 2025

Listing your Forge successor app on Marketplace

This page covers how to add the new Forge version of your app to your Connect app Marketplace listing.

The Forge version is added as a new version to your existing Marketplace listing, so your app will keep its existing listing with its reviews and installations.

Before proceeding, ensure you have tested the upgrade process.

Forge Apps will not work when replacing a Private Connect listing

Forge apps are not compatible with private Marketplace listings and should be shared via distribution links when distributed privately.

When an app updates from Connect to Forge, the Connect version is uninstalled (without a lifecycle event) and the latest Forge version is installed in its place. If you are seeking to test the process of upgrading your Connect app to Forge, you can imitate this by installing the previous Connect version of your app and then either:

  • installing a version of your Forge app with the same Connect app key via the CLI (with a license override if testing license state)

  • installing a version of your Forge app with the same Connect app key via a distribution link

Billing considerations

If you're listing a paid app, you must always use the development or staging environment to test your app.

All installations of paid production apps are billed. This includes:

  • if you install your production paid app on your Atlassian cloud instance

  • Forge apps installed on enterprise sandbox instances (regardless if they're installed on the enterprise's production instance).

To mitigate these, create a promotion to discount the costs.

Step 1: Request persistence of your app account, if required

If your app requests that customers modify the app account's Jira or Confluence permissions or stores data such as macro, workflow, or dashboard configuration information for the app, you may need to request persistence of your app account to Forge.

If you have not yet done this, and your app requires it, please request it now.

This cannot be done once you have listed your app on the Marketplace and must be completed prior to publishing.

Each request is manually reviewed, so to ensure that you don't have to delay publication of your app, it's useful to request this as soon as you know you need it.

Step 2: Enable sharing

If you haven't already, you also need to enable sharing on your app. This will allow you to distribute it via the developer console.

  1. Using the Forge CLI, deploy your app to the production environment.

  2. In the developer console, choose the app you want to share.

  3. Select Distribution in the left menu, and under 'Distribution controls', select Edit.

  4. Select the Sharing option, fill in the app details, and select Save changes.

Step 3: Opt in to programs for Marketplace apps (If desired)

If you would like to participate in new programs for Marketplace apps that are available to those who opt-in, please follow the instructions below.

You can join either or both (or neither) of these programs. If you join both, they'll work in conjunction with each other and your app can benefit from staged migration and changes to minor version update criteria.

Step 3.1: Staged migration from Connect to Forge

A staged migration will limit the visibility of the Update button for existing installations of your app to the provided sites. Any new installations from the marketplace will receive the Forge version of your app.

If you would like to follow a staged migration, raise a Marketplace 'Edit your listing' Support ticket.

Example

  • Summary: Staged migration rollout from Connect to Forge

  • Description: I would like to control the rollout of my migrated Connect on Forge app, by initially restricting updates to the following test sites: https://TESTINSTANCE.atlassian.net

  • App key: com.atlassian.confluence.extra.team-calendars

  • Listing management URL: https://marketplace.atlassian.com/manage/apps/12345/details

Step 3.2: Updated criteria for minor version updates, for Connect apps adopting Forge (Preview)

If you would like to participate in the Preview program that enables your app to qualify for a minor version update when updating to Forge, if the new Forge version doesn't request elevated permissions compared to the Connect version, raise a Marketplace 'Edit your listing' Support ticket.

This program applies different criteria to your app when determining whether your app updates require a major version update, and should result in fewer major version updates for your app. If the customer's current installation of your Connect app and the most recent version of your Forge app satisfy the criteria, the app can be automatically rolled out to customers without requiring admin approval, enabling your customers to access the latest functionality of your app without administrator involvement.

Example

  • Summary: Opt-in for Minor version update from Connect to Forge

  • Description: I would like to enroll in the program that enables eligible app updates to be rolled out to customers automatically as minor version updates.

  • App key: com.atlassian.confluence.extra.team-calendars

  • Listing management URL: https://marketplace.atlassian.com/manage/apps/12345/details

Step 4: 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.

Screenshot of the screen to publish a new app version in Marketplace

The Marketplace approval process can take a week or longer. While your app's approval is in progress, you will not be able to update the Connect version of your app.

Once the Forge version's Marketplace listing is approved, all customers watching the app will be notified of a new version and invited to upgrade via Connected Apps, the same as if it were a new minor or major Connect-based version of the app.

FAQ

Will I lose my existing installations and ratings?

No, the app will keep its ratings and installations. Installations will move from the Connect to the Forge version one-by-one as customers click "Upgrade" on the "Manage Apps" screen.

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

Mistakes happen. In case of an emergency, you can ask our team to manually roll back the migration. To do this, raise a Marketplace 'Edit your listing' Support ticket.

Stuck? Something not clear?

Rate this page: