The Universal Plugin Manager (UPM) makes it easy to install add-ons. With just a few clicks, you can browse the Atlassian Marketplace and install add-ons in your application, all without leaving the administration interface of your Atlassian product.
Alternatively, you can install add-ons by file upload. The file upload procedure installs an add-on as a JAR or an OBR (OSGi Bundle Repository) file. The archive file should contain the plugin code and resource files. File upload enables you to install custom add-ons or any add-on not available on Atlassian Marketplace. You can also use it to install add-ons for applications operating behind a firewall and disconnected from the Internet.
On this page:
A note about add-on safety: Add-ons are very powerful; they can change the behavior of almost any part of the Atlassian application. It is very important that you trust an add-on before you install it. Always be aware of where (and who) an add-on comes from.
Add-on framework versions
Add-ons come in three types: Plugins 1, 2, and Atlassian Connect. The most prominent add-on type is Plugins 2. This version number refers to the version of the underlying Atlassian SDK framework used to build the add-on. This identifier is distinct from the add-on's individual versioning scheme, which identifies updates to the add-on software.
Add-ons built with the Plugin 2 SDK use the internal OSGi framework built into Atlassian applications. In some cases, Plugins 1 add-ons may not be installable in the host application. Instead, you must install them manually. If you attempt to install a Plugins 1 add-on using file upload when not supported, an error message similar to the following appears:
The add-on name-version.jar is a type 1 add-on. Type 1 add-ons cannot be dynamically installed. For more information on installing type 1 add-ons see the UPM documentation.
Learn more about installing Plugins 1 type add-ons in JIRA and Bamboo.
Installing add-ons directly from Atlassian Marketplace
If you are connected to the Atlassian Marketplace website from your Atlassian application's administration console, you can install add-ons by clicking the Install button from the Find new add-ons administration page. This single-click installation method is the quickest way to install add-ons, although it's not the only way. You can also install by file upload, as described in the next section.
For more information on installing add-ons from the Find new add-ons page, see Finding new add-ons.
Installing by file upload
You can install most add-ons using the single-click installation method, as described in Finding new add-ons. Alternatively, you can install an add-on by uploading it to your Atlassian application. You must use this method to install add-ons that are not available on the Marketplace, such as a custom add-on you created, or if installing an older version of an add-on.
Add-ons are normally distributed as JAR or OBR (OSGi Bundle Repository) files. These are the only types of add-on distribution files that are accepted by the file upload mechanism.
Note that some add-ons are distributed as ZIP files or other types of files other than JARs. These are typically add-ons that run separately from the host application container, such as the JIRA Client. In Atlassian Marketplace, these entries have a Download button that you click to get the add-on.
If you attempt to install a file that isn't a JAR or OBR file in the 'Manage Add-ons' page, the following error appears:
Could not find a handler capable of installing the add-on at filename. Check that the file is a valid add-on.
You should refer to the installation instructions provided with the add-on in this case.
Before installing by file upload, make sure that the add-on distribution file that you want to upload is accessible to your computer either at a file system location or at a network location by URL.
To upload an add-on:
- From the application's administration console, click the Manage add-ons link.
- Click the Upload add-on link at the top right side of the page.
The following dialog appears.
- Enter the location of the JAR or OBR file to upload using the file chooser or by specifying a network location by entering a URL.
- Click Upload.
A confirmation message appears when the add-on is successfully installed.
- If prompted, restart your application to have your change take effect.
You can now manage the add-on from the user-installed add-on list on the Manage add-ons page.
Installing Plugins 1 type add-ons in JIRA and Bamboo
A few considerations apply to installing or uninstalling add-ons created with the SDK version 1 framework. These types of add-ons are identified in their Marketplace listing as 'Plugins 1' add-ons.
- You cannot install Plugins 1 add-ons into JIRA or Bamboo using the Universal Plugin Manager. You must download the add-on distribution and follow its specific installation instructions. Such add-ons have a Download button rather than an Install button in their listing. In most cases you will need to move or download the file to the
- Similarly, Plugins 1 JIRA and Bamboo add-ons do not have an Uninstall button. You must remove the add-on from the file system manually.
- In Confluence, you can install and uninstall Plugins 1 add-ons using the Universal Plugin Manager. You should see an Install or an Uninstall button with the add-on entry.
Once you have downloaded or created your add-on JAR file, follow these steps to install it to JIRA:
- Shut down JIRA.
- Copy your JAR file (e.g., example_plugin.jar) into the directory:
- Start JIRA.
- Confirm the installation by going to Administration > Manage Add-ons. Your add-on (e.g., example_plugin) should appear in the list as enabled.
If you attempt to install a Plugins 1 add-on by copying its JAR file into the installation directory meant for Plugins 2 add-on (or vice versa), JIRA provides a warning indicating that the add-on has been installed into the wrong directory.
However, there may be a very small number of Plugins 1 add-ons (such as the JIRA RPC Plugin) which, if accidentally installed into the Plugins 2 directory (
<JIRA home directory>/plugins/installed-plugins/), do not generate this warning. Nevertheless, the add-on does not function correctly and the 'Manage Add-ons' page typically indicates that this add-on has zero modules.
To resolve this problem, reinstall the JAR file into the correct directory as follows:
- Shut down JIRA.
- Move the JAR file to
<JIRA installation directory>/atlassian-jira/WEB-INF/lib/
- Restart JIRA.