Managing JIRA's Plugins

On this page:

About Plugins

A plugin is a .jar file (containing code, resources and a configuration file) that can be installed into an Atlassian product to add new functionality or change the behaviour of existing features.

You can use plugins to customise and extend the functionality of JIRA in a variety of ways, including:

• creating new dashboard gadgets (previously known as 'portlets')
• creating new reports
• creating new types of custom fields
• customising workflow
• modifying the availability of 'issue operations' links ('Create Issue', etc)

JIRA ships with a number of preinstalled plugins, and many more are available for download from the Atlassian Plugin Exchange.

You can also create your own plugins — please visit the JIRA Development Hub for information on building 'Version 1' plugins, or visit the Plugin Framework​ for information on building 'Version 2' (OSGi) plugins. These plugins can be installed in your JIRA instance as described below.

Installed JIRA plugins can be enabled or disabled.

Every plugin is made up of one or more plugin modules. A single plugin may do many things, and each module represents a single function of the plugin. Individual modules can be enabled or disabled, although this is not recommended as modules can often depend on each other. To do so safely would require knowledge of the module interdependencies.

About 'Version 1' Plugins and 'Version 2' Plugins

There are two types of Atlassian plugins:

• 'Version 1' Plugins — These plugins are compatible with the 'old' plugin framework that was used in JIRA prior to version 4.0, and also with the 'new' plugin framework used in JIRA version 4.0 and later. 'Version 1' plugins are installed into your JIRA installation directory under atlassian-jira/WEB-INF/lib/.
  
  
• 'Version 2' Plugins — These plugins are compatible with the 'new' plugin framework used in JIRA version 4.0 and later. They are installed into your JIRA home directory under plugins/installed-plugins/. 'Version 2'  plugins are deployed in an internal OSGi container to isolate the plugin from the core code and other plugins, and to allow sophisticated dependency management. 'Version 2' plugins have to be specifically declared as such, using the plugins-version="2" attribute in the plugin's configuration file (atlassian-plugin.xml). 

How do I tell if a Plugin is 'Version 1' or 'Version 2'?

Go to https://plugins.atlassian.com and look at the plugin's details. The 'Plugin System' field will show 'ONE' for Version 1 plugins and 'TWO' for Version 2 plugins.

Installing a JIRA Plugin

1. Shut down JIRA.
2. Copy your plugin jar (e.g. 'EXAMPLE_PLUGIN.jar') into the appropriate plugins directory:
   • If you are installing a 'Version 1' plugin, copy the jar into your JIRA installation directory under atlassian-jira/WEB-INF/lib/.
   • If you are installing a 'Version 2' (OSGi) plugin, copy the jar into your JIRA home directory under plugins/installed-plugins/.
3. Start up JIRA.
4. Go to 'Administration > Plugins'. Your plugin (e.g. 'EXAMPLE_PLUGIN') will be listed and enabled.

Updating a JIRA Plugin

The process for updating a plugin is similar to installing a new one. Simply download or create your updated plugin jar, then follow these steps to install it in your JIRA instance:

1. Shut down JIRA.
2. Remove the old version of the plugin jar and copy your updated plugin jar (e.g. 'EXAMPLE_PLUGIN.jar') into the appropriate plugins directory:
   • If you are installing a 'Version 1' plugin, copy the jar into your JIRA installation directory under atlassian-jira/WEB-INF/lib/.
   • If you are installing a 'Version 2' (OSGi) plugin, copy the jar into your JIRA home directory under plugins/installed-plugins/.
3. Start up JIRA.
4. Go to 'Administration > Plugins'. The updated version of your plugin (e.g. 'EXAMPLE_PLUGIN') will be listed and enabled.

Disabling a JIRA Plugin

1. Log in as a user with the 'JIRA Administrators' global permission.
2. Bring up the administration page by clicking either the 'Administration' link on the top bar or the title of the Administration box on the dashboard.
3. On the panel on the left, under the title 'System', click the link labelled 'Plugins'.
4. This will bring up the 'Current Plugins' page. The page lists all the installed plugins, e.g.:
   
   
   
   
5. Locate the plugin that you want to disable, and click the 'Disable plugin' link.

Also note that JIRA can automatically disable plugins if they cause errors on startup or initialisation. This is usually caused by having an old version of the plugin that is not compatible with your current version of JIRA. If this occurs, it will be indicated on the 'Current Plugins' page (shown above). You will need to stop JIRA, install the newer version of the plugin and restart JIRA.

Enabling a JIRA Plugin

Note: newly installed plugins are enabled by default.

To enable a plugin:

1. Follow the above steps for disabling a plugin, but click 'Enable plugin' instead.

Uninstalling a JIRA Plugin

Follow these steps to uninstall a plugin from your JIRA instance:

1. Shut down JIRA.
2. Remove your plugin jar (e.g. 'EXAMPLE_PLUGIN.jar') from the appropriate plugins directory:
   • If you are removing a 'Version 1' plugin, remove the jar from your JIRA installation directory under atlassian-jira/WEB-INF/lib/.
   • If you are removing a 'Version 2' (OSGi) plugin, remove the jar from your JIRA home directory under plugins/installed-plugins/.
3. Start up JIRA.
4. Go to 'Administration > Plugins'. Your plugin (e.g. 'EXAMPLE_PLUGIN') will no longer be listed.