Upgrading and versioning cloud apps

You can upgrade your app any time once it's listed in the Marketplace as either an approved public app or a private listing.

Almost all changes you make to your app will be to code inside your app's web app. For example, tweaking the look of a web panel, adding a configuration option, or catching a previously unhandled exception can all be done by writing and deploying new code to your servers. Users see these changes as soon as you update your web app.

In many cases (e.g., catching an exception or adding a configuration option) there isn't an immediate reason why end-users should be aware of the change. When you change your descriptor file or deploy your Forge app to production, we automatically update your app’s version and build number in the Marketplace.

Upgrading Connect apps

Automatic app polling and versioning

We automatically detect updates to Atlassian Connect apps with a polling service. We poll the app descriptor URL that you included when you submitted your listing every 5 hours. When we detect a change, we automatically update your app in the Atlassian Marketplace with a new version. The way we increment your app’s version number depends on the changes made to your descriptor.

We poll and update your app so that you can easily release fixes and new features, without having to manually create new version entries on Marketplace. We want to ensure that customers get the latest version of your app with as little delay as possible — Connect apps should seem like web services, not versioned software.

When you change your app descriptor, these changes are automatically deployed to customer instances within a day--unless they require manual customer approval. Here's how it works:

Major, minor, and micro version update definitions

New app versions are published to the Marketplace within five hours of making changes to your Atlassian Connect descriptor. Customers automatically receive updates via the UPM within 24 hours. Any change to your service that does not alter your app descriptor will be immediately available to users and will not result in a new version on Marketplace.

We automatically increment the version for your app as follows:

• The major version is incremented (e.g., from 1.2.3 to 2.0.0) when you specify an API version update (e.g., from 1.0 to 2.0). The new major version matches the API version listed in your descriptor.
• The minor version is incremented (e.g., from 1.2.3 to 1.3.0) when you specify increase/changed scopes, and/or when you update licensing from free to paid. Customers must manually approve updates for minor version updates.
• The micro version is incremented (e.g., from 1.2.3 to 1.2.4) when you make any other descriptor changes not included above that do not require manual approval.

Automatic updates

If the changes do not require manual customer approval, they are automatically deployed to all customer instances within 33 hours:

• We poll the app descriptor URL that you included when you submitted your listing. When we detect a change, we automatically update your app in the Atlassian Marketplace with a new version. Updates are published to the Marketplace within 5 hours of you publishing changes to your descriptor file.
• Each customer instance polls the Atlassian Marketplace periodically (currently every 24 hours) and automatically updates to the latest version of your app.
• If you change your app during the maintenance windows, the upgrade of your app on customer instances could be further delayed by 4 hours.

Upgrading Forge apps

Automatic app polling and versioning

We automatically detect updates to Atlassian Forge apps when any changes are released to the production environment, i.e., deployment to production from Forge CLI. It takes a few minutes for Marketplace to detect when a change is deployed to production. When a change is detected, we automatically update your app in the Atlassian Marketplace with a new version. The way we increment your app’s version number depends on the changes made to your app.

We update your app with a new version so that you can easily release fixes and new features, without having to manually create new version entries on Marketplace. We want to ensure that customers get the latest version of your app with as little delay as possible — Forge apps should seem like web services, not versioned software.

When you release any changes to your Forge app in production, these changes are automatically deployed to customer instances within minutes--unless they require manual customer approval. Here's how it works:

Major and minor version update definitions

New app versions are published to the Marketplace within a few minutes of changes being released to production via Forge CLI.

We automatically increment the version for your app as follows:

• The major version is incremented (e.g., from 1.2.0 to 2.0.0) when you specify increase/changed scopes, and/or when you update licensing from free to paid. Customers automatically receive major version updates via the UPM within 24 hours and must manually approve these updates.
• The minor version is incremented (e.g., from 1.2.0 to 1.3.0) when you make any other changes not included above that do not require manual approval. These changes are instantly available to the customers.

Automatic updates

If the changes do not require manual customer approval, they are automatically deployed to all customer instances within a few minutes.

If the changes require manual approval, each customer instance would poll the Atlassian Marketplace periodically (currently every 24 hours) and show that an update is available to the latest version of your app.

If you change your app during the maintenance windows, the upgrade of your app on customer instances could be further delayed by 4 hours.

Changes that require manual customer approval

Even though your app is automatically updated in the Marketplace, certain scenarios require customers to manually approve your app's update in the UPM. In such cases, we automatically send emails to the product administrator so they can approve and update the app.

These scenarios require manual customer approval:

• Your listing changes from free to paid: Your change triggers a Marketplace approval. After the app version has been approved on Marketplace, it will be available to customers. Existing customers need to approve the change to start paying for your app, otherwise, they will need to uninstall it.
• Your listing involves additional scopes (both Connect and Forge): Marketplace updates happen automatically (no approval necessary), but customers need to approve the changes to continue using your app.

Before the approval, those customers continue to use the older version of your app. If you can plan ahead, it's a good idea to isolate those changes from any other changes in functionality.

What this means for your app

If the new version of your app is backward compatible (if it is able to handle requests from instances that have an older version of the descriptor) the upgrade will be transparent. All customer instances will be upgraded over a period of up to 33 hours.

However, if the new version of your app is not backward compatible, you should make sure that your solution caters to supporting both the old and the new version of the app:

• For up to 33 hours (or two days to be safe) if the changes do not require manual customer approval.
• If the changes require customer approval until administrators for all instances have approved/rejected the changes.

Viewing automatically added versions

You can view apps in the Marketplace the same way you manage other app versions: 

1. Log in to https://marketplace.atlassian.com/ with your vendor account.
2. Click Manage vendor account from the profile menu in the upper right.
3. Click your app's name from the list.
4. Click Versions in the horizontal navigation bar.
5. You'll see updates from Marketplace Hub [Atlassian]: