Installing add-ons

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:

  1. From the application's administration console, click the Manage add-ons link.
  2. Click the Upload add-on link at the top right side of the page. 
    The following dialog appears.

    Upload add-on dialog

  3. 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.
  4. Click Upload.
    A confirmation message appears when the add-on is successfully installed.
  5. 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 <INSTALL_DIR>/atlassian-jira/WEB-INF/lib directory.
  • 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:

  1. Shut down JIRA.
  2. Copy your JAR file (e.g., example_plugin.jar) into the directory:
    • If you are installing a Plugins 1 add-on, copy the JAR file into your JIRA installation directory under atlassian-jira/WEB-INF/lib/.
    • If you are installing a Plugins 2 (OSGi) add-on, copy the JAR file into your JIRA home directory under plugins/installed-plugins/.
  3. Start JIRA.
  4. 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:

  1. Shut down JIRA.
  2. Move the JAR file to <JIRA installation directory>/atlassian-jira/WEB-INF/lib/
  3. Restart JIRA.

Related Topics

Viewing an add-on's details


Last modified on Oct 6, 2015

Was this helpful?

Provide feedback about this article
Powered by Confluence and Scroll Viewport.