List a Forge app

This page covers how to build and test paid apps, and how to submit any app (free or paid) to the Marketplace.

Before you begin

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 detailed by the General Data Protection Regulation (GDPR).

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 Forge as a platform remains free to use.

Building a paid app

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

Enabling licensing for your app

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

1
2
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 (but not UI Kit 2)

License information can be accessed by passing the context into your function or with the useProductContext hook for UI kit functions.

The license.isActive property indicates 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 development, staging, and custom environments.

Here's example code that checks the license state when using UI Kit:

1
2
   import { useProductContext } from "@forge/ui";

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

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

UI Kit 2 and Custom UI front ends

License information can be accessed with the getContext method for UI Kit 2 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 development, staging, and custom environments.

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

1
2
   import { view } from @forge/bridge;
   const context = await view.getContenxt();

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

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

UI Kit 2 and Custom UI back ends

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

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

1
2
   import Resolver from "@forge/resolver";
   const resolver = new Resolver;

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

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. However, context.license is undefined when your app is deployed to development, staging, and custom environments.

We therefore recommend that you implement a function like the following, and use it in your app code wherever you retrieve the license state. This approach allows you to override the license state for testing.

1
2
enum LicenseOverride {
    ACTIVE = 'active',
    INACTIVE = 'inactive'
}

export function isLicenseActive(context) {
    // Check for an environment variable that overrides the license state
    const override = process.env.LICENSE_OVERRIDE;
    if (typeof override !== 'undefined') {
        if (override.toLowerCase() === LicenseOverride.ACTIVE) {
            return true;
        }
        if (override.toLowerCase() === LicenseOverride.INACTIVE) {
            return false;
        }
    }
    // Else return the actual value
    /// option for UI Kit (not UI Kit 2) front end
    return context && context.license && context.license.isActive;
    /// option for UI Kit 2 front end
    return context && context.license && context.license.active;
}

You can then override the license state in both tunnelling and in development, staging and custom environments with an environment variable:

When tunnelling, export FORGE_USER_VAR_LICENSE_OVERRIDE=<active|inactive> before launching the tunnel.
In development, staging, and custom environments run forge variables set -e <environment> LICENSE_OVERRIDE <active|inactive>.

Please make sure you check the value of context in an invocation context, because environment variables and the context object are not accessible during the snapshot context.

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 create a partner profile on the Marketplace and submit your Forge app for approval.

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 products?

The Forge platform lets developers build apps that are compatible with multiple products.

However, the Marketplace doesn't currently support cross-product apps. If your app is compatible with multiple products, you'll need to create two Forge apps using the same code base, and publish two separate listings on the Marketplace. Note, Forge apps listed on the Marketplace aren't able to make API calls across different products and instances/installations.

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.

Known limitations

Forge app events won't appear in the 'Manage apps' audit log.