List a Forge app

How to build and test paid apps, and how to submit any app (free or paid) to the Atlassian cd 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 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 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 1

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

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 1:

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
  // ...

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 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
   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.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 custom environments.

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;
   }

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

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.

This essentially means that you don’t have to mock your app code as if it’s in production to test your Forge apps in different license states.

The allowed license values are:

• active
• inactive
• trial

When testing your Forge app in different license states, run the following command in the Forge CLI:

1
2
forge install --environment development --license <license value>

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.

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.