Last updated Aug 26, 2021

Rate this page:

Build a Connect on Forge app

This functionality is an alpha release

The features described in this tutorial are available for research and feedback, and are not production-ready. See the known limitations and known issues section for more information.

This tutorial describes how to integrate a Connect app with Forge, and install and use the resultant app on a Jira site. You'll build new modules in your Connect app using the UI kit and use Forge functions to execute your app logic.

With your app deployed to Forge, your Connect app retains the flexibility of remote-hosted compute and UI, while benefiting from Forge-only modules, such as Jira workflow validators and Jira custom fields.

Before you begin

You'll need to set up your Forge development environment and a development site. See Getting started for step-by-step instructions on setting up Forge.

You'll also need a tool to tunnel your local app server to the internet. This tutorial will use ngrok, which can be downloaded for free from ngrok.

Note, it's not necessary to log in with an ngrok account to use the basic tunneling features.

Step 1: Get the sample app

In this step, you'll clone the example code from Bitbucket and explore the file and code structure that enables Connect modules on a Forge app.

  1. Clone the sample app from Bitbucket.
  2. Open the repository in your editor.

The app has the following file structure:

├── connect-app.js
├── manifest.yml
└── src
    └── index.js

The table below shows the purpose for each file in detail.


This is a standalone Atlassian Connect app server, which handles installations, makes authenticated requests, and returns the HTML to display a general page. Installation data is stored as .json files in a data/ directory.

Notably absent is the Connect add-on descriptor. This is because Connect features of the app are described alongside Forge features in the manifest.yml.


The manifest describes your app. The following sections that have changed to support Connect functionality:

  • connectModules contains the parts of the app that map to connect modules.

    Jira-specific modules are prefixed with jira: and Confluence-specific modules are prefixed with confluence:. Modules common to either product can have either prefix.

    This app has a general page and handlers for installation and uninstallation events. enabled and disabled events are currently not fired by the Forge platform.

  • remotes contains the Connect base URL. This section is limited to a single entry, but the value of the key doesn't matter.

  • permissions contains the app's scopes.

    Connect scopes appear in the Forge manifest as lower-cased, with underscores converted to dashes, and with a suffix of either :connect-jira or :connect-confluence. It makes no difference which of the two is used, as long as the suffix contains connect in it. For example, the Connect READ scope becomes read:connect-jira or read:connect-confluence, and PROJECT_ADMIN becomes project-admin:connect-jira or project-admin:connect-confluence.


This contains the source of the workflow validator function.

Step 2: Start your Connect app server

Unlike a Forge app, Connect apps are served from a remote HTTP server. For development purposes, you'll start up a local HTTP server embedded in the example app.

  1. Navigate to the top-level directory of the sample app.
  2. Start the app server by running:

    node connect-app.js

    Note, on Linux you can directly execute the app ./connect-app.js.

  3. Open a separate terminal window and start your internet-facing tunnel by running:

    ngrok http --bind-tls=true 49998

  4. Copy the HTTPS URL from the ngrok output into the baseUrl in the manifest.yml. The URL contains a random ID followed by the ngrok domain. For example, https://<random ID>

Step 3: Deploy and test your Forge app

With a running local HTTP server, you'll deploy a Forge app that calls back over the internet via the ngrok tunnel connecting to your local Connect app.

In this section, you'll define app.connect properties in the manifest file. app.connect.key is environment specific. In production environments, we recommend setting it to your Connect app key. In development and staging environments, set an appropriate variation of your key.

In future, your production app.connect.key must match the marketplace key when publishing a Connect on Forge app to the Atlassian Marketplace. This functionality is not yet supported.

  1. Open another terminal window, and navigate to the top-level directory of the sample app.

  2. Register the sample app by running:

    forge register

    a. Enter a name for your app. For example, My Connect app on Forge.

  3. Add a connect: field nested under the app: field, with its own key and remote fields, like so:

        key: hello-world
        remote: connect

    key should correspond to the desired connect key of the app in production, and remote should correspond to the key of the remotes entry that holds the connect app baseUrl.

  4. Deploy the app by running:

    node deploy.js

    A custom deploy script is used in order to update the app.connect.key for the environment being deployed to.

  5. Install your app by running:

    forge install
  6. Select Jira using the arrow keys and press the enter key.

  7. Enter the URL for your development site. For example,

Once the successful installation message appears, your app is installed and ready to use on the specified site. You should see a Connect installation logged in the output of the app server started at step 2.

You can now see the app in action on your development site by transitioning an issue or clicking on the Apps drop-down in the Jira top nav, then clicking Connect on Forge: My Jira projects.

Optional steps

With your functioning basic app, you can continue to explore what's possible with Connect modules in a Forge app. Below are some ideas to get you started.

Add more modules

You can experiment with adding other Forge and Connect modules to your app.

You may have an existing Connect app you wish to experiment with porting to Forge. If so, we recommend you set up a separate instance of the app with its own data store to avoid conflicts. Because the ported version will have a different, randomly generated key, this version will not clash with the original version on the development site. See the known limitations and known issues section below.

Connect modules have the same format in Forge. You'll need to specify the jira or confluence prefix, but should otherwise be able to copy and paste the Connect module syntax directly into the manifest.yml since YAML is a superset of JSON.

Intermediate: Experiment with calling from Connect to Forge

You can use web triggers to use a Forge feature from your Connect app. Note, web trigger URLs must be generated per installation.

Advanced: Experiment with calling from Forge to Connect

It may be possible to make a JWT authenticated call from a Forge function to your app server. However, this hasn't been tested and and we foresee the following issues:

  • Possible lack of a crypto polyfill in the Forge app runtime.

  • No way to access the clientKey in which the function is being invoked.

Known limitations and known issues

We're working on broadening the support for Forge apps with Connect modules. In its current early state, it has some limits and issues you should be aware of.

Although these issues are known to us, we're excited to hear your feedback about how you would prefer these features to work or which are the most troublesome for you.

Alpha release

Connect features in Forge are still a work in progress. At the moment, it’s not yet possible to list a Forge/Connect app on the Atlassian Marketplace.

Issues granting access to restricted resources

Despite having the required scopes, your app may not be able to access restricted resources, such as team-managed projects with custom permissions, or operations, such as deleting projects. This is due to reliability issues with Connect app permission provisioning.

Uninstall/reinstall required to reflect module changes

When updating the modules, scopes, and baseURL of your app, simply redeploying your app will not reflect these changes where the app is currently installed. You must uninstall and reinstall the app via the Forge CLI for these changes to reflect.

Issues with context variables in module urls

If certain modules (such as jira:webItems or confluence:webItems) contain context parameters (such as {project.key}) in their url, they will fail to deploy due to a validation error. This is due to differences in how Forge and Connect validate urls within such modules against the module schema.

Communication issues between Forge and Connect

An app has no communication path between the Forge and Connect parts of an app.

app.connect.key can be changed in the development and staging environments at any time, and in production up until the app is listed on the Atlassian Marketplace.

app.connect.key is used by a number of Atlassian Connect features as an identifier, and these are affected by the change. For example, the app loses access to:

  • Any app properties it has written such as the /rest/atlassian-connect/1/addons/{addonKey}/properties resource.
  • Certain existing configured modules identified by the key, such as workflow post functions.
  • Bookmarked urls that include the app key, such as links to general pages, space tools tabs, or reports.

Managing different environments

app.connect.key can and should be set differently in different environments, but the field in the manifest is not environment specific, meaning it will need to be changed to the appropriate key before deploying to a different environment. See deploy.js in the sample app for one way to automate this.


Forge does not support Connect apps with internationalized content.

Data residency

Forge does not support Connect apps using the new data residency API.

Dynamic modules

Forge does not support dynamic modules.


Forge does not support user impersonation for Connect Apps. The oauthClientId supplied in the installation hook payload is not compatible.

Giving feedback

We're excited to hear your feedback. Please join us in the Forge developer community.

Rate this page: