List a Forge app

How to build and test paid Marketplace apps, and how to submit any Marketplace app (free or paid) to the Atlassian Marketplace.

Before you begin

Read the following details before submitting your Marketplace 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.

Building a paid Marketplace app

If you're planning to list a paid Marketplace app, you need to configure your Marketplace app so that a commercial license is provisioned when the Marketplace app is installed. Additionally, you should check the license status of your Marketplace app when your functions are invoked, and implement reduced functionality if your Marketplace app is unlicensed.

Enabling licensing for your Marketplace app

Licenses for Forge Marketplace apps are controlled by a configuration option in your Marketplace app manifest.yml file. To enable licensing for your Marketplace app, add the app.licensing.enabled attribute to the manifest.yml file and set its value to true.

1
2
3
4
5
6
app:
  id: ari:cloud:ecosystem::app/12345678-90ab-cdef-1234-2840465f3b84
  name: Forge Demo App
  licensing:
    enabled: true

After enabling licensing for your app, you should deploy a new version of your app to production by running the forge deploy -e production command.

Once deployed, you won't be able to install the app from the production environment until your Marketplace listing is approved.

Checking the license status

For licensed apps, additional context data is passed into the function invocation that allows the app to determine the current license state.

The way you check the license state differs depending on which UI toolkit you are using, and whether you are checking the state from the front-end or back-end.

UI Kit and Custom UI front ends

License information can be accessed with the getContext method for UI Kit or Custom UI front end functions.

The license.active property contains the app's license state; true if the installation has a valid license, and false otherwise.

Note: The license object is only present for paid apps in the production environment. license is undefined for free apps, apps not listed on the Atlassian Marketplace, and apps in custom environments.

Here's example code that checks the license state when using UI Kit or in a Custom UI front end function:

1
2
3
4
5
6
7
8
9
10
11
   import { view } from @forge/bridge;
   const context = await view.getContext();

  if (context.license.active !== true) {
    console.log("App is not licensed");
    return;
  }

  // App is licensed ... continue with app functionality
  // ...

To know how to test whether your app is behaving as expected across license states, see Testing your app with different license states.

UI Kit and Custom UI back ends

License information can be accessed from your resolver function's context parameter, when the function is invoked.

The license.active property indicates the app's license state; true if the installation has a valid license, and false in all other cases, including for free apps.

Note: The license object is only present for apps in the production environment. license is undefined for free apps, apps not listed on the Atlassian Marketplace, and apps in custom environments.

Here's example code that checks the license state in a Custom UI back end resolver function:

1
2
3
4
5
6
7
   import Resolver from "@forge/resolver";
   const resolver = new Resolver;

   resolver.define("checkLicense", ({ context }) => {
      return context.license && context.license.active;
   }

To know how to test whether your app is behaving as expected across license states, see Testing your app with different license states.

Triggers

For product event triggers and scheduled triggers, you can use filter.appIsLicensed to automatically skip invocations when the app is unlicensed. This means you don't need to add a code-level license check in your trigger handler — the platform handles it for you.

1
2
3
4
5
6
7
8
9
modules:
  trigger:
    - key: my-trigger
      function: handler
      events:
        - avi:jira:commented:issue
      filter:
        appIsLicensed: true

See the filter reference for triggers and scheduled triggers for more details.

Add licensing to an existing app

If you add licensing to a Forge app that was previously free, Forge considers existing installations unlicensed until the site admin subscribes to the app in the Admin Hub.

Best practices for transitioning users

To ensure a smooth experience for your users, we recommend the following:

• Create a deprecation policy: Define and communicate a clear deprecation policy. Outline how long existing features will remain free and when a license will be required.
• Maintain free functionality: Keep existing features available without a license for a set period. This provides a grace period for users before they are required to pay for functionality they previously used for free.
• Introduce new features behind a license check: You can add new functionality that requires a license immediately, while maintaining the free functions of the app for a transition period.

Testing your app with different license states

You will most likely need to test that your app behaves as expected when it is both licensed and unlicensed.

The--license option in the forge install command allows you to specify and test different license states for your Forge app in non-production environments, providing greater flexibility and control during the development and testing phases. The allowed license values are:

• active
• inactive
• trial

To test a license state, run the following command in the Forge CLI. Replace active with another allowed value when needed.

1
2
forge install --environment development --license active

If you want to simulate a different app behavior, you can define your own environment variable and update your app code to read it.

1
2
3
forge variables set --environment development LICENSE_OVERRIDE inactive
forge deploy --environment development

For example, a backend function helper can check an app-defined override before falling back to the license state supplied by Forge:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
export function isLicenseActive(context) {
  const override = process.env.LICENSE_OVERRIDE?.toLowerCase();

  if (override === "active") {
    return true;
  }

  if (override === "inactive") {
    return false;
  }

  return context?.license?.active === true;
}

If the variable is unset or has another value, the helper uses the platform-provided license state.

How do I list an app on the Atlassian Marketplace?

Firstly, you'll need to make sure you've enabled sharing for your app in the developer console.

Then follow the steps to publish the developer space.

Once your Forge app is submitted, we aim to provide a decision within one week. Actual times may vary, depending on the volume of apps that have been submitted.

How do I make sure my app gets approved?

Check out our approval guidelines.

Note that when submitting your app, we'll ask for additional details about your app's functionality. Be ready to provide the following information:

• The API scope permissions that your app requires, and why each scope is necessary for your app to function.

• The remote hostnames or IP addresses that your Forge app sends requests to (if any), what data is sent to these hosts, and why.

What if my app supports multiple Atlassian apps?

The Forge platform lets developers build apps that are compatible with multiple Atlassian apps. While previously these apps were not able to be distributed via the Atlassian Marketplace, soon you will be able to list and distribute apps that are compatible with multiple Atlassian apps.

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.

Can I still share my app via the developer console?

Apart from listing an app on the Marketplace, Forge apps can also be distributed via the developer console. This method involves sharing an installation link, to install apps for internal usage or for testing. This is usually for cases where the app isn't intended to be discoverable by a wide range of customers.

Once you've listed an app on the Marketplace, you won't be able to distribute the app via the developer console. 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.