Local add-on development

You will go through three phases during add-on development: developing and testing with a local version of the Atlassian product, testing on a Cloud instance, and finally making the add-on available via the Atlassian Marketplace (as a public or private listing).

This document explains how you would go about developing your add-on with a local copy of the Atlassian product. Installing in the cloud explains how to use private Marketplace listings to test in cloud instances, and Selling on Marketplace explains how to release your add-on to the public.

Step 1. Configure your local development environment

To implement Connect add-ons and test them locally, we provide you with tools to start a local instance of the Atlassian application, in the Atlassian Plugins SDK. There are two ways to configure your local development environment: you can install everything on your machine, or to save you the hassle you can spin up an instance of our pre-configured Vagrant box.

Local installation instructions [+]


Using our pre-configured Vagrant box [+]


More detailed information about using the Vagrant box [+]


Step 2. Start the local Atlassian application

You can start a local instance of JIRA or Confluence Cloud with Atlassian Connect as follows:

If you are using a local installation [+]


If you are using the Vagrant box [+]


Step 3. Start your add-on

Start your add-on application. The options for hosting your add-on are many, but when working on a locally hosted environment, you can use any web framework / server you wish to build your add-on.

For an example of using a HTTP server, see the getting started guide.

Example using atlassian-connect-express in the Vagrant box [+]


Step 4. Register your add-on

Registering your add-on installs it in the Atlassian application. After installation, the add-on appears in the list of user-installed add-ons in the Manage Add-ons page in the administration console and its features are present in the application UI.

You can install an add-on with the UPM as follows. Note, these instructions were written for UPM version 2.14 or later.

  1. Log in to the Atlassian application interface as an admin or a system administrator. If you started the application with Atlassian's SDK, the default username/password combination is admin/admin.
  2. Choose Settings > Add-ons from the menu. The Administration page will display.
  3. Choose the Manage add-ons option.
  4. Scroll to the page's bottom and click the Settings link. The Settings dialog will display.
  5. Make sure the "Private listings" option is checked and click Apply.
  6. Scroll to the top of the page and click the Upload Add-on link.
  7. Enter the URL to the hosted location of your plugin descriptor. In this example, the URL is similar to the following: http://localhost:8000/atlassian-connect.json. (If you are installing to a cloud instance, the URL must be served from the Marketplace, and will look like
  8. Press Upload. The system takes a moment to upload and register your plugin. It displays the Installed and ready to go dialog when installation is complete.
  9. Click Close.
  10. Verify that your plugin appears in the list of User installed add-ons. For example, if you used Hello World for your plugin name, that will appears in the list.

Step 5. Test your add-on

The exact steps for testing will vary based on what your add-on does, of course. However, there are some common minimal steps applicable to any add-on for ensuring that it got installed correctly.

After registering your add-on in the Atlassian application, it should appear in the UPM as a user-installed add-on. Any UI features you have declared with modules should now be visible as well.

Step 6. Change your code and reload

You can now change and reload your add-on as normal for your app or framework. Changes should show up immediately. (Watch out for browser caching!)

You only need to re-register the add-on when you change the descriptor file, such as when modifying or adding module declarations, scopes or changing the plugin-info details. Simply repeat step 3.

You should not need to restart the Atlassian application while developing.

Handy tools

The following tools can be of great help when implementing add-ons!

Tool Description
JSON descriptor validator This validator will check that your descriptor is syntactically correct. Just paste the JSON content of your descriptor in the "descriptor" field, and select the Atlassian product you want to validate against.
JWT decoder An encoded JWT token can be quite opaque. You can use this handy tool to decode JWT tokens and inspect their content. Just paste the full URL of the resource you are trying to access, including the JWT token, in the URL field. E.g. http://localhost:2990/jira/path/to/rest/endpoint?jwt=token