Creating your Plugin Descriptor

On this page:

Every plugin requires an atlassian-plugin.xml file. This is a single file also known as the plugin descriptor. The plugin descriptor is an XML file that describes a plugin and the modules contained within it for the host application. In a plugin project, the file is resides in the resources directory. In a plugin submission, the descriptor is located at the root of the plugin's jar file.

The following is a basic descriptor file:

The following sections describe the basic elements in the descriptor XML file.

atlassian-plugin element

The root element for your plugin descriptor. For example, the plugin descriptor file should have this structure:




A String identifying the plugin module. This attribute is required and must be unique within the plugin. You should use the reverse domain name notation to ensure your key is unique. In other contexts, you may need to uniquely identify a module. You should use the complete module key.

By default, the SDK generation commands sets the key for you by referencing and concatenating the groupId and artifactId from the pom.xml.


This is a human-readable name, used for display in menus within the application. By default, the SDK generation commands sets the key for you by referencing the add-on name from the pom.xml. You should not use the words 'plugin' or 'add-on' in this value.


This is enabled by default. To disable the entire plugin, specify disabled.


To create an OSGi plugin, use plugins-version="2".
(info) The attribute pluginsVersion was deprecated in version 2.1 of the plugin framework.


The localization key for the human-readable name of the plugin module.


The class that implements this plugin module. The class you need to provide depends on the module type. For example, Confluence theme, layout and colour-scheme modules can use classes already provided in Confluence. So you can write a theme-plugin without any Java code. But for macro and listener modules you need to write your own implementing class and include it in your plugin.


Indicates whether this plugin module is a system plugin module (value='true') or not (value='false'). Only available for non-OSGi plugins.

plugin-info Element

Contains plugin information displayed by the application for administrators, plugin parameters, and OSGi bundle instructions. Its parent element is <atlassian-plugin>, and it supports several nested elements.

Nested element



A human-readable description of your plugin.


The version of your plugin. This number is displayed in the application's plugin manager.


The Java version required for this plugin module. This is an optional value. It is not used consistently among the host applications.


Supply the versions of the application that will support your plugin. Deprecated.


Supply information about the developer of the plugin.


Supply parameter values if required by your plugin.


Declare plugin dependencies and shorten your export package lists by specifying OSGi bundle instructions directly in the plugin XML (OSGi plugins only).

These nested elements are described in more detail below.

description element

Describes your plugin. Its parent element is <plugin-info>.

version element

The current version of your plugin. Its parent element is <plugin-info>. The UPM sometimes compares the plugin version value within an application to determine the newer version, particularly when performing automated upgrades. Versions are compared by splitting the version number into components and comparing them numerically first and alphabetically second.

Following are some sample version numbers in ascending order: 0.99, 1.0, 1.0.1-alpha, 1.0.1-beta, 1.0.1-beta2, 1.0.1,, 1.1, 1.2, 1.10, 2.0.

application-version element

Deprecated since Atlassian Plugin Framework 2.2

Describe which versions of the host application are compatible with this plugin. Enforcement of this property varies between applications: some applications strictly enforce compatibility, while others ignore the value.

Its parent element is <plugin-info>.

Attribute name



Lowest application version that your plugin is compatible with.


Highest application version that your plugin is compatible with.

vendor element

The plugin vendor. Provides a link in the plugin administration screens. Its parent element is <plugin-info>.

Attribute name



Supply your name or the name of the company you work for.


Supply a web site address.

param element

Arbitrary parameters for a plugin. Its parent element is <plugin-info>. These can be nested in many other elements. Attribute name gives the parameter name. The element's body is its value.




The name of the parameter.


The value of the parameter.

A common example of a param element the URL for your plugin's configuration screen. Below is an example.

bundle-instructions element

This element allows you to declare plugin dependencies and shorten your export package lists by specifying OSGi bundle instructions directly in the plugin XML. The element's parent element is <plugin-info>.

As seen in the above example, the bundle-instructions element allows child elements, including:

  • <Export-Package>
  • <Import-Package>
    Alternatively, you can declare these instruction sets inside your pom.xml file.
Speeding up Plugin Loading

How to Speed Up Plugin Startup contains information on using bundle instructions for speeding plugin start up.

The Atlassian Plugin Framework uses the bnd tool to generate OSGi bundles. This tool is available as the Bundle Plugin for Maven. For details of the bnd directives, please refer to the bnd documentation.

Plugin module elements

In the rest of the descriptor XML file, contains any modules that make up your plugin. You can add these modules through the atlas-* commands or manually. The following illustrates the addition of a web-item module:

For more information about the modules a plugin can contain, refer to the list of module types for your plugin's host application.


Information sourced from Plugin Framework documentation

Was this page helpful?

Have a question about this article?

See questions about this article

Powered by Confluence and Scroll Viewport