In this recipe, we will see how to deploy a plugin into JIRA. We will see both the automated deployment using the Atlassian Plugin SDK and manual deployment.
Make sure you have the development environment set up as we discussed earlier. Also, the skeleton plugin should now have the plugin logic implemented in it.
Installing a JIRA plugin using the Atlassian Plugin SDK is a cakewalk. Here is how it is done:
Open a command window and go to your plugin's root folder, that is, the folder where your
pom.xml
resides.Type
atlas-run
and press Enter. It is possible to pass more options as arguments to this command for which the details can be found at https://developer.atlassian.com/docs/developer-tools/working-with-the-sdk/command-reference/atlas-run.You will see a lot of things happening as Maven downloads all the dependent libraries in to your local repo. As usual, it is going to take lot of time when you run it for the first time.
If you are on Windows, and if you see a security alert popping up, click Unblock to allow incoming network connections.
When the installation is completed, you will see messages similar to the following:
Open
http://localhost:2990/jira
in your browser.Log in using the username
admin
and passwordadmin
.Test your plugin! You can always go to Administration | Add-ons | Manage add-ons menu to confirm that the plugin is deployed properly.
If you already have a local JIRA installed or if you want to manually install your plugin due to some reason, all you need to do is to package the plugin JAR and install it via UPM (Universal Plugin Manager) as described at https://confluence.atlassian.com/display/UPM/Installing+add-ons#Installingadd-ons-Installingbyfileupload. Or, you can copy it across to JIRA_Home/plugins/installed-plugins
directory and restart JIRA.
You can package the plugin using the following command:
atlas-mvn clean package
Use atlas-mvn clean install
if you also want to install the package plugin into your local repo.
There is only one single command that does the whole thing: atlas-run
. When you execute this command, it does the following:
Builds your plugin
.jar
file. It also builds the.obr
file, which is the OSGi Bundle Repository file; that is essentially a.jar
file containing our plugin and all dependent plugins, if we have any. More details on .obr files can be read at https://developer.atlassian.com/docs/faq/advanced-plugin-development-faq/bundling-extra-dependencies-in-an-obr.Downloads the latest/specified version of JIRA to your local machine if it is the first time you are running the command.
Creates a virtual JIRA installation under your plugin
/target
folder.Copies the
.jar
file in to the/target/jira/home/plugins/installed-plugins
directory.Starts JIRA in the Tomcat container.
Now, if you look at your target
folder, you will see a lot of new folders that were created for the virtual JIRA installation! The main two folders are the container
folder that has the Tomcat container set up and the jira
folder that has the JIRA WAR along with the JIRA home setup.
You will find the database (HSQLDB), indexes, backups, and attachments under /target/jira/home
, and you will see your jira-webapp
at /target/container/tomcat8x/cargo-jira-home/webapps/jira
.
If you have any JSPs that need to be put under the webapp, you will have to copy it to the appropriate folder under the aforementioned path.
It is also possible to use a specific version of JIRA or to reuse the data that we have used for testing.
As mentioned earlier, atlas-run
deploys the latest version of JIRA. But what if you want to deploy the plugin into an earlier version of JIRA and test it?
There are two ways to do it:
Mention the JIRA version as an argument to
atlas-run
; make sure you runatlas-clean
if you already have the latest version deployed:a. Run
atlas-clean
(if required)b. Run
atlas-run -v 5.0
oratlas-run -version 5.0
if you are developing for JIRA version 5.0. Replace the version number with a version of your choice.Permanently change the JIRA version in your plugin
pom.xml
:a. Go to your
pom.xml
b. Modify the
jira.version
property value to the desired version.c. Modify the
jira.data.version
to a matching version.This is how it will look for JIRA 5.0:
<properties> <jira.version>5.0</jira.version> <jira.data.version>5.0</jira.data.version> </properties>
Suppose you added some data on to virtual JIRA; how do you retain it when you clean start-up JIRA next time?
This is where a new SDK command comes to our rescue.
After atlas-run
is finished, that is, after you pressed Ctrl + C, execute the following command:
atlas-create-home-zip
This will generate a file named generated-test-resources.zip
under the target/jira
folder. Copy this file to the /src/test/resources
folder or any other known location. Now modify the pom.xml
to add the following entry under configurations in the maven-jira-plugin
:
<productDataPath>${basedir}/src/test/resources/generated-test-resources.zip</productDataPath>
Modify the path accordingly. This will reuse the data the next time you run atlas-run
after an atlas-clean
.
Missing JAR file exception? Make sure the local-repository
attribute in the settings.xml
points to the embedded Maven repository that comes with the SDK. If the problem still persists, manually download the missing .jar
files and use atlas-mvn install
to install them in to the local repository.
Watch out for the proxy settings or antivirus settings that can potentially block the download in some cases!
BeanCreationException? Make sure your plugin is version 2. Check atlassian-plugin.xml
to see if the plugins-version="2"
entry is there or not. If not, add the entry, as shown here:
<atlassian-plugin key="${atlassian.plugin.key}" name="${project.name}"
plugins-version="2">
Run atlas-clean
followed by atlas-run
.