If you want to use your Forge app on your own Atlassian site, you can install it directly using the Forge CLI without enabling sharing. See Promote an app to staging or production for instructions.

Apps with distribution status set to Not sharing can only be installed by contributors of the app (developers listed in the developer console). All other users - including licensed users and Jira Service Management portal-only (customer) accounts - cannot install the app.

If your app needs to be installed or accessed by non-contributor users, you must set the distribution status to Sharing within organization or Sharing. Use Sharing within organization only when every installing admin belongs to an organization of the app owner. For customers, partners, or Jira Service Management portal-only users outside the app owner's organization, use Sharing. See Start sharing your app for instructions.

When you're ready to share your Forge app with other users, you'll need to enable sharing for your app in the developer console. This generates a link that you can share with users to install your app on their Atlassian site (they must be the admin of that site to do that).

Use this method to share your apps for internal use, or to test your apps before listing them on the Atlassian Marketplace.

Apps that already have a license in the app manifest or have been submitted for listing on Marketplace can't be shared via installation link; in order to share and test these apps, you'll need to copy the app's code, create a new, unlicensed version of the app, and share this version via installation link.

You can stop sharing your app at any time.

Distribution statuses

Each app has a distribution status that controls who can install it. You set this status on the Distribution page in the developer console.

Distribution status	Who can install the app	When to use it
Not sharing	App contributors only, using the Forge CLI.	While you build and test an app on your own sites.
Sharing within organization	Anyone with the installation link who belongs to any organization the app owner belongs to.	Internal apps that only people in your organization should install.
Sharing	Anyone with the installation link.	Apps you share with customers or partners outside your organization, and apps you're preparing to list on the Atlassian Marketplace.

Using the Forge CLI, deploy your app to the production environment.
In the developer console, choose the app you want to share.
Select Distribution in the left menu, and under 'Distribution controls', select Edit.
Select the Sharing within organization or Sharing option, fill in the app details, and select Save changes. For guidance on which option to choose, see Distribution statuses.
Select which Atlassian apps you want your user to install your app onto.
This affects where users can install your app. For example, if you select both Jira and Confluence, your user can only install it on sites running both Jira and Confluence.

You must tell your user to install it on both Atlassian apps; otherwise, it won't work as expected.
Copy the installation link and send it to your user.

When your user visits the link, an installation screen appears, similar to the one below. It displays information about your app, including the permissions your app is requesting. From here, your user can choose a site and an Atlassian app to install your app onto.

User installation screen

Apps set to Sharing can be installed by any Atlassian user who has the installation link or app ID. If your app is only meant for people you work with, set it to Sharing within organization instead. Installation is then restricted to users who belong to an organization of the app owner.

Keep the following in mind when you share an app within your organization:

Organization membership is determined by the app owner, who is listed on the Contributors page in the developer console. If the app owner belongs to multiple organizations, users in any of those organizations can install the app.
If you transfer app ownership, the organizations whose users can install the app change to match the new owner.
Installing users must be an admin of the site they're installing the app on.
Users who do not belong to an organization of the app owner cannot install the app, even if they have the installation link or app ID.

Restrict installation links

If you want to restrict or change who can install your app, you can generate a new installation link. This disables the previous installation link.

Users with the previous link will no longer be able to install your app. However, if they've already installed your app, they can continue to use it, and update it when you release new versions.

This action can't be undone.

In the developer console, choose the app you want to generate a new link for.
Select Distribution in the left menu.
Next to the installation link, select Generate new link.

If no link appears, check that sharing is enabled for your app.
A modal appears. If you’re happy to continue, select Generate new link.

To restrict sharing to your organization, set the distribution status to Sharing within organization:

In the developer console, choose the app you want to restrict.
Select Distribution in the left menu, and under Distribution controls, select Edit.
Select Sharing within organization, then select Save changes.

For more information, see Share your app within your organization.

If you change an app from Sharing to Sharing within organization, existing installations continue to work for all users on those sites. However, site admins outside your organization can no longer upgrade the app.

Note that automatic updates deployed through bulk upgrades or Rolling releases continue to upgrade existing installations regardless of sharing status. To let external admins manually upgrade via the installation link again, set the app back to Sharing.

If you want to stop sharing your app with users, you must disable sharing in the developer console.

In the developer console, choose the app you want to stop sharing.
Select Distribution in the left menu, and under 'Distribution controls', select Edit.
Select the Not sharing option, then select Save changes.

Your app is no longer being shared. This has the following effects:

Users with the installation link will no longer be able to install your app.
Users who have already installed your app can generally continue to use it, though in some cases the app might stop working for existing users.

You can start sharing your app again any time.

You might want to deploy a new version of your app that includes updated scopes. Once you've deployed the new version to the production environment using the Forge CLI, users can:

Update their forge apps through the Connected apps page.
Bitbucket forge apps can also be uninstalled or upgraded directly from the Bitbucket workspace settings.

If needed, you can copy the installation link from the developer console and send it to them again.

If your app is set to Sharing within organization, only site admins in the app owner's organization can manually upgrade it using the installation link or through Connected apps. Installations on sites outside that organization remain on their currently installed version unless you upgrade them via bulk upgrades or Rolling releases.

If your app uses Rolling releases, you can view your rollouts from Developer Console after deploying the new version to production. This helps customers receive safe code updates sooner, including bug fixes, security fixes, performance improvements, and features that do not depend on new permissions.

Permission changes remain subject to admin approval. Until admins approve the new permissions, the app continues running with its previously approved permission set. This lets you ship the compatible parts of an update while gracefully skipping permission-dependent features until approval is complete.

To start or monitor a code rollout, open Rollouts in Developer Console. From there, you can start a rollout for an environment, view rollout progress and failure rates, cancel an in-flight rollout, restart a cancelled rollout, and open rollout details. See View app rollouts for more information.

Distributing an app update to existing installations

After deploying a new major version of your app, you might want to upgrade all installations of the app on an eligible older major version to the newer one.

For apps using Rolling releases, use Developer Console to start and monitor code rollouts. Permission changes remain subject to admin approval.

For eligible major version updates that don't require an escalation in privilege, you can use the forge version bulk-upgrade CLI to start, cancel, and track updates in large batches without site admin approval. For more information, see version bulk-upgrade.

If your app uses Rolling releases, use Developer Console to roll out app code and monitor, cancel, or restart rollouts while permission approval remains separate. See View app rollouts for details.

For apps that use Forge Container services, some installations may not upgrade successfully. If this happens, retry to complete the upgrade.

Records from the Forge CLI are time-limited and may not be available indefinitely. It is advisable to document or monitor these records promptly if they are needed for future reference.

Requirements for eligibility

Currently, major version updates may require users and admins to re-consent or review the changes before upgrading. For an update to be eligible for bulk distribution, it should adhere to the following criteria:

The app must remain within the same environment.
The target version must be greater than the source version.
The new major version must not introduce new scopes or egress permissions that represent an escalation of privilege. The following changes are eligible for bulk upgrades:
- Removal of scopes
- Addition of Forge-specific OAuth 2.0 scopes that inherit permissions already granted by a Connect scope the customer has already accepted
- Addition of the sql module
The new major version’s licensing information must remain unchanged.

List your app on the Atlassian Marketplace

If you've finished testing your app, and want to provide or sell it to a large customer base, see Listing Forge apps on the Atlassian Marketplace.

Apps set to Sharing within organization can't be listed on Marketplace. Set the distribution status to Sharing before you submit your app for listing.

Once your app has been submitted for listing on Marketplace, or has a license in the app manifest, it can't be shared via installation link. In order to share and test this app, you'll need to copy the app's code, create a new, unlicensed version of the app, and share this version via installation link.

Forge apps that are compatible with multiple Atlassian apps

The Forge platform lets developers build apps that are compatible with multiple Atlassian apps. Apps with a required Atlassian app can be listed and distributed via the Atlassian Marketplace as paid apps; free listings are not supported. This distribution model does not apply to Global Apps (EAP), which have no required Atlassian app link.

For more information on building Forge apps that are compatible with multiple Atlassian apps, see app compatibility.

When publishing your app on Marketplace, it will detect which Atlassian apps it is compatible with based on the app's manifest. When admins install the app, it will be installed in the required Atlassian app. Admins can also choose to connect it to any additional supported Atlassian apps during installation.

Developing for Atlassian Government Cloud

This content is written with standard cloud development in mind. To learn about developing for Atlassian Government Cloud, go to our Atlassian Government Cloud developer portal.