Managing JIRA's Plugins

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 1' plugins must be installed manually (see below) and uninstalled manually (see below).
• 'Version 2' Plugins — These plugins are compatible with the 'new' plugin framework used in JIRA version 4.0 and later. 'Version 2' plugins are installed automatically, using the JIRA administration interface (see below). 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

Installing a plugin from the Atlassian Plugin Exchange

To access the Universal Plugin Manager in JIRA:

1. Log in as a user with the JIRA System Administrators global permission.
2. Select 'Administration' > 'Plugins' > 'Plugins'. The Universal Plugin Manager will be displayed, showing the plugins installed on your JIRA site.
   Keyboard shortcut: 'g' + 'g' + start typing 'plugins'

To find and add a plugin from the Atlassian Plugin Exchange:

1. Click the 'Install' tab in the UPM. You will see a list of featured plugins.
2. Search for your plugin as follows:
   • Enter some keywords that describe the plugin in the 'Search the Plugin Exchange' search box and press 'Enter'.
   • Alternatively, browse to the desired plugin in the list. You can choose 'Featured', 'Popular', 'Supported' (by Atlassian) or 'All available' from the 'Plugins to show' dropdown to see a different list of plugins.
3. Click the 'Install' button for the desired plugin to add it to your application. A confirmation message and the plugin details will appear when the plugin is installed successfully.
   Note: You may need to restart your application for your change to take effect. The Universal Plugin Manager will inform you if this is the case.
   Note: Not all plugins can be automatically installed. Some required manual installation. These plugins will have a 'Download' button instead of an 'Install' button. In these cases, you should read and follow the plugin's installation instructions.

Screenshot: Finding a new plugin from the Atlassian Plugin Exchange

Installing your own plugin

To access the Universal Plugin Manager in JIRA:

1. Log in as a user with the JIRA System Administrators global permission.
2. Select 'Administration' > 'Plugins' > 'Plugins'. The Universal Plugin Manager will be displayed, showing the plugins installed on your JIRA site.
   Keyboard shortcut: 'g' + 'g' + start typing 'plugins'

To upload your own plugin:

1. Click the 'Install' tab in the UPM. You will see a list of featured plugins.
2. Click the 'Upload Plugin' link. The 'Upload Plugin' window will appear.
3. Specify the location of your plugin:
   • If the plugin you want to install is on your computer, use the 'Browse' dialogue to choose the plugin JAR file.
   • If you want to install a plugin from a remote location, enter the URL of the plugin JAR file in the 'From this URL' text box.
4. Click the 'Upload' button to upload and enable your plugin. A confirmation message will appear when the plugin is successfully installed.
   Note: You may need to restart your application for your change to take effect. The Universal Plugin Manager will inform you if this is the case.

Screenshot: Uploading a new plugin

Installing a plugin manually

You will need to install plugins manually if:

• you are installing a 'Version 1' plugin; or
• your JIRA server does not have access to the internet (in which case the Universal Plugin Manager will be unable to access http://plugins.atlassian.com).

Once you have downloaded or created your plugin jar file, follow these steps to install it in your JIRA instance:

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/.
     To find out whether a plugin is Version 1 or Version 2, check the Plugin Exchange. Note that plugins have different versions, and older builds of plugins may be Version 1.
3. Start up JIRA.
4. Go to 'Administration' > 'Plugins' > 'Plugins'. Your plugin (e.g. 'EXAMPLE_PLUGIN') will be listed and enabled.

If you copy the JIRA jar file of a 'Version 1' plugin into the installation directory for 'Version 2' plugins (or vice versa), JIRA provides a warning, indicating that the plugin has been installed into the wrong directory. However, there may be a very small number of 'Version 1' plugins (such as the JIRA RPC Plugin) which, when accidentally installed into the 'Version 2' plugins directory (<JIRA home directory>/plugins/installed-plugins/), will not generate this warning. Nevertheless, the plugin will not function correctly and the JIRA administration 'Plugins' page typically indicates that this plugin has zero modules. To rectify this problem, reinstall the plugin jar to the correct directory by: Shutting down JIRA, Moving the plugin jar file to <JIRA installation directory>/atlassian-jira/WEB-INF/lib/ Restarting JIRA.

Viewing Installed Plugins

To access the Universal Plugin Manager in JIRA:

1. Log in as a user with the JIRA Administrators global permission.
2. Select 'Administration' > 'Plugins' > 'Plugins'. The Universal Plugin Manager will be displayed, showing the plugins installed on your JIRA site.
   Keyboard shortcut: 'g' + 'g' + start typing 'plugins'

Screenshot: Finding installed JIRA plugins, using the Universal Plugin Manager
Some tabs will not be visible if you do not have the JIRA System Administrators global permission

Updating a JIRA Plugin

To access the Universal Plugin Manager in JIRA:

1. Log in as a user with the JIRA System Administrators global permission.
2. Select 'Administration' > 'Plugins' > 'Plugins'. The Universal Plugin Manager will be displayed, showing the plugins installed on your JIRA site.
   Keyboard shortcut: 'g' + 'g' + start typing 'plugins'

To upgrade a plugin:

1. Click the 'Upgrade' tab. The plugin upgrades page will appear.
   • If there is a later version of a plugin that you have already installed, this page will show the latest compatible version of the plugin.
   • You can click the plugin name to expand the row and see more information about the plugin.
   • You can filter your list by entering keywords in the 'Filter plugins' text box.
2. Click the 'Upgrade Now' button next to the relevant plugin to update it to the plugin version shown.

To upgrade all available plugins:

1. Click the 'Upgrade' tab. The plugin upgrades page will appear.
   • If there is a later version of a plugin that you have already installed, this page will show the latest compatible version of the plugin.
   • You can click the plugin name to expand the row and see more information about the plugin.
   • You can filter your list by entering keywords in the 'Filter plugins' text box.
2. Click the 'Upgrade All' button to update every plugin to the plugin versions shown.
   Note: Some plugins cannot be installed via the Universal Plugin Manager. You must install these plugins manually. These plugins will not be upgraded automatically.

Disabling a JIRA Plugin

To access the Universal Plugin Manager in JIRA:

1. Log in as a user with the JIRA Administrators global permission.
2. Select 'Administration' > 'Plugins' > 'Plugins'. The Universal Plugin Manager will be displayed, showing the plugins installed on your JIRA site.
   Keyboard shortcut: 'g' + 'g' + start typing 'plugins'

To disable a plugin:

1. Click the 'Manage Existing' tab. You will see a list of the plugins installed in your application. Enabled plugins will have this icon:
2. Locate the plugin that you want to disable and click the title to expand the plugin details section.
3. Click the 'Disable' button.
4. Once a plugin has been disabled, you may need to restart your application for your change to take effect. If so, you will see a message for the plugin, 'Disabled, requires restart'.
   Once the plugin is fully disabled, you will see an 'Enable' link for the plugin.

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 access the Universal Plugin Manager in JIRA:

1. Log in as a user with the JIRA Administrators global permission.
2. Select 'Administration' > 'Plugins' > 'Plugins'. The Universal Plugin Manager will be displayed, showing the plugins installed on your JIRA site.
   Keyboard shortcut: 'g' + 'g' + start typing 'plugins'

To enable a plugin:

1. Click the 'Manage Existing' tab. You will see a list of the plugins installed in your application. Disabled plugins will have this icon:
2. Locate the plugin that you want to enable and click the title to expand the plugin details section.
3. Click the 'Enable' button.
4. Once a plugin has been enabled, you may need to restart your application for your change to take effect. If so, you will see a message for the plugin, 'Enabled, requires restart'.
   Once the plugin is fully disabled, you will see a 'Disable' link for the plugin.

Disabling/Enabling all User Installed Plugins (Safe Mode)

Running JIRA in Safe Mode disables all user installed plugins at once. All plugins that were disabled when you entered Safe Mode will be re-enabled when you exit Safe Mode.

To access the Universal Plugin Manager in JIRA:

1. Log in as a user with the JIRA Administrators global permission.
2. Select 'Administration' > 'Plugins' > 'Plugins'. The Universal Plugin Manager will be displayed, showing the plugins installed on your JIRA site.
   Keyboard shortcut: 'g' + 'g' + start typing 'plugins'

To enable Safe Mode:

1. Click the 'Manage Existing' tab. You will see a list of the plugins installed in your application.
2. Click the 'Enable Safe Mode' button.
3. Click the 'Continue' button in the confirmation window. All user installed plugins will be disabled and your application will now be running in 'Safe Mode'.
4. You can now make changes to your installed plugins as desired. For example, you may want to enable/disable specific plugins or plugin modules.
5. Exit safe mode by clicking one of the links in the Safe Mode banner:
   • Click 'Exit Safe Mode and restore the previous configuration' to restore your plugin configuration to its state before you entered Safe Mode.
   • Click 'Exit Safe Mode and keep the current configuration' to keep all changes made to your plugin configuration during Safe Mode.

Uninstalling a JIRA Plugin

Note: If you only want to temporarily remove a plugin, you may wish to disable it instead of uninstalling it.

To access the Universal Plugin Manager in JIRA:

1. Log in as a user with the JIRA System Administrators global permission.
2. Select 'Administration' > 'Plugins' > 'Plugins'. The Universal Plugin Manager will be displayed, showing the plugins installed on your JIRA site.
   Keyboard shortcut: 'g' + 'g' + start typing 'plugins'

To uninstall a plugin:

1. Click the 'Manage Existing' tab. You will see a list of the plugins installed in your application.
2. Click the name of the plugin that you wish to uninstall. The plugin details will appear.
3. Click the 'Uninstall' button. The information summary will display an 'Uninstalling' message and the plugin will be uninstalled from your application.

Uninstalling a 'Version 1' plugin manually

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.

Configuring a JIRA Plugin

A number of plugins have advanced configuration options, e.g. a plugin may contain multiple 'modules' that you can enable/disable. If you have one of these plugins installed on your application instance, you can view and update these configuration options via the Universal Plugin Manager (UPM).

To access the Universal Plugin Manager in JIRA:

1. Log in as a user with the JIRA Administrators global permission.
2. Select 'Administration' > 'Plugins' > 'Plugins'. The Universal Plugin Manager will be displayed, showing the plugins installed on your JIRA site.
   Keyboard shortcut: 'g' + 'g' + start typing 'plugins'

To configure a plugin:

1. Click the 'Manage Existing' tab.
2. Locate the plugin that you want to configure and click its title. The plugin details section will expand.
3. Click the 'Configure' link for that plugin.
   • The link will be disabled if the plugin is disabled.
   • If there is no 'Configure' link, then there are no advanced configuration options available for that plugin.
4. The advanced configuration options for the plugin will appear. Update the configuration settings as desired and save your changes.
   Note: The advanced configuration screens are provided by the plugin. If you encounter any problems after you click the 'Configure' link, the plugin is responsible for the issue, not the Universal Plugin Manager.