Installing an add-on
Installing an add-on using the Universal Plugin Manager
You can install an add-on with the UPM as follows. Note, these instructions were written for UPM version 2.14 or later.
- 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
- Choose > Add-ons from the menu. The Administration page will display.
- Choose the Manage add-ons option.
- Scroll to the page's bottom and click the Settings link. The Settings dialog will display.
- Make sure the Private listings option is checked and click Apply.
- Scroll to the top of the page and click the Upload Add-on link.
- Enter the URL to the hosted location of your plugin descriptor. In this example, the URL is similar to the following:
- 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.
- Click Close.
- 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 name will appear in the list.
Installing an add-on using the REST API
You can also install an add-on using the UPM's REST API. You'll find this method useful if you want to install add-ons programmatically, say from a script, or simply want to quickly install an add-on from the command line. Broadly speaking, installing an add-on (or performing any operation against the REST API of the UPM) is a two-step process:
First get a UPM token. Next, issue the request to the REST API, including the token you received.
The following steps walk you through these steps in detail:
Send a GET request to the following resource:
In your request:
PORTwith the actual host name and port of the target Atlassian application. If applicable (i.e., if using a development instance), include the
CONTEXTwith the application context (
- Include the username and password for a system administrator user in the target Atlassian application as HTTP Basic Authentication credentials.
- Set the Accept header for the request to: "
Capture the header named
upm-token in the response. This is the UPM token you need for the next request.
Now install your add-on by issuing a
POST request to the following resource:
In your request:
- Again use the actual host name and port and path for your target Atlassian application.
- The token value should be the value of the
upm-tokenheader you just received.
- In the request, set the Accept header to: "
- Set the
Content-Typefor the data to: "
In the body of the
POST, include the following JSON data:
plugin-xml-urlwith the hosted location of your descriptor file, and the plugin name with the name by which you want the add-on to be registered in the application.
This registers the add-on declared by the
atlassian-plugin.xml file at the URL.
You should not rely on the response returned from the
POST request to confirm that the plugin has been installed. Instead, the best way to confirm that the plugin has been installed is to add a webhook to your add-on descriptor that listens for the add-on installation event. The webhook declaration in the
atlassian-plugin.xml file would look something like this:
When registering from the command line using cURL, keep in mind that cURL does not perform session maintenance across calls (unlike other clients, such as Apache HttpClient). Thus, you need to either:
Send the authentication credentials in both requests, or have curl save any cookies from the first request and send them in the second.
To set curl to save any cookies from the first request to use in the second:
- To save cookies, use the
curl -c cookiesfile.txt ...
- And then include the cookies in the second request:
curl -b cookiesfile.txt ...