Here are the initial steps you need to follow in order to get Jenkins Integration for Jira up and running.
Install the Jira app from the Atlassian Marketplace
You need to download the app Jenkins Integration for Jira from the Atlassian Marketplace.
Go to Jenkins Integration for Jira on the Atlassian Marketplace.
OR
On top right corner of menu bar select your headshot/icon → scroll down to Atlassian Marketplace → click on Atlassian Marketplace.
You will arrive on the Atlassian Marketplace main page. Search ‘Jenkins integration’ and click enter/return:
The first result should be Jenkins Integration for Jira. Click the button ‘Free trial’:
Click ‘Accept & Install’ to start installation:
The app normally downloads within one minute but could be longer depending on your Jira configuration:
Now you need to get the trial license. Click ‘Get license’:
Note: The app will not work until you have the license activated in your Jira instance.
Getting and applying a license
After clicking on ‘Get license’ you will be redirected to my.atlassian.com. Ensure you are logged in. Agree to the terms of use and then click ‘Generate License’.
You will arrive at a page with the license key. If you have configured your Jira to connect with the Atlassian Marketplace click ‘Apply License’:
You should have the app installed. Go to Step 3: Installing the Jenkins Plugin. If not keep reading.
If you have not configured your Jira to connect with the Atlassian Marketplace you will see this:
You must manually apply the license. Jenkins Integration for Jira will not work until this is done.
How to manually apply the license
Click ‘Close’ on modal dialog window (the popup that says Oh no!). You will see the installed apps on the Manage Apps page.
Go to my.altassian.com in a new browser window (make sure you are logged in).
Scroll down on the page to see licences. Check ‘Trials’ box if not checked.
Expand ‘Jenkins Integration for Jira: Trial’. Copy the license from the ’license key’ field:
Go back to the Atlassian Marketplace → Manage Apps. Click on Jenkins Integration for Jira Server and Data Center to expand it.
Paste the license key into the field ‘License key’.
Click ‘Update’ to save the license key.
Installing the Jenkins plugin
You also need to download a plugin on the Jenkins side called Jira Integration for Jenkins.
Get the latest version of Jira Integration for Jenkins, from the Release Notes.
Go to your Jenkins homepage
Manage Jenkins > Manage Plugins
Under Manage Plugin
Click on the Advanced tab.
Under Upload Plugin
Upload the file you just downloaded. It has the file extension .hpi:
If prompted, restart your Jenkins instance
Connecting Jira and Jenkins
Now you are ready to configure your first Jenkins site (an instance of Jenkins) and enable jobs to synchronize. This is important to do right away as it establishes the data connection between Jira and Jenkins. If you do not do this you will not get any Jenkins data in Jira.
From the top navigation in Jira, choose Gear Icon > Manage Apps
Choose Jenkins Integration > Configuration and then click Connect your first site
This brings up the Add Site dialog. Create a name of the site you are adding:
Under Options check Enabled for Synchronization
Optional: Under Options check Auto enable new Jobs
If you want to enable all Jobs on the site by default, including future new jobs. If you don’t select it you will have to manually select jobs.
Optional: Under Options check CSRF
Only if your site has CSRF enabled. Checked is the default in Jenkins.
Under Accessibility select either Public or Private
If select Public:
Note the following if select Public:
- In case you use SSL, make sure that Jira and Jenkins have each other SSL certificate in their trust store so that they can connect. See also Connecting to SSL Services.
-
Under Sync URL enter the root URL of Jenkins that the app uses to connect.
-
Optional: provide a Display URL in case the Sync URL is not accessible by users and a different URL should be used in the UI features
-
Select an Authentication Method
If select Sync Token Authentication then the app will generate access tokens automatically.
If select Basic Authentication you must enter a username and token (the token can be an API token or a password) If you use an external source (like LDAP, AD or Crowd) for authentication, then provide the API Token as password for the user. Where to find the API Token...
The API Token is a password replacing token that users can use to authenticate with against Jenkins. This is mostly useful for users that have there accounts managed outside Jenkins. To get a token for an account, follow these steps:
- Login on Jenkins using the username and password of the synchronization account
- Click on the Account Name in the top-right corner of the page after login
- Then click on the Configure link in the left menu
- The API Token can now be displayed by clicking on the Show API Token… button
- Click Create to save the configuration.
If selected Auto enable new jobs you are done. If you DID NOT select Auto enable new jobs then you need to manually enable the jobs you want to sync automatically.
If select Private:
Select this option if the Jira app can’t access the Jenkins site directly.
-
Add a Display URL (required).
-
Click Create to save the configuration. This opens the Manage Sites page.
- Then you need to manually register your Jira site in Jenkins. Click on Configuration. This opens the configuration dialogue box:
- Follow the link in the warning box Register with site. Fill in the site registration form in Jenkins.
Optional step: select the jobs to enable for synchronization
If you have NOT selected Auto enable new Jobs, you will need to select the jobs that should enabled for synchronization.
-
From the Manage Site page in Jira click on the Site Name.
-
Locate the jobs you want to enable for synchronization and enable them by toggling the toggle button in front of their names.
-
Either manually trigger the synchronization of individual jobs you just enabled, or click the Refresh Jobs button to trigger a full site synchronization.
Recommended Reading
We strongly recommend you read about how data synchronization works and how builds are linked to issues.
Next: Configuration