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.
How to get the app while working in Jira
On the top menu bar select Apps > Find new apps:
You will arrive on the Atlassian Marketplace main page. Search ‘Jenkins integration’:
The first result should be Jenkins Integration for Jira. Click anywhere in the square box:
Click ‘Try it free’:
Click ‘Start free trial’:
A message stating that it is downloading will appear:
The app normally downloads within one minute.
Get app directly from the Atlassian Marketplace
Go to the Atlassian Marketplace and search ‘Jenkins Integration’. Or click here to go directly to Jenkins Integration for Jira:
Click on Jenkins Integration for Jira:
Select the version of Jira you use:
Click ‘Try it free’ button:
Click ‘Start free trial’ under cloud. You need to be logged into an Atlassian account with permission to download apps from the Atlassian Marketplace:
Choose the site you want to add the app to then click ‘Start free trial’:
You will be directed to your Jira instance. Click ‘Start free trial’:
A message stating that it is downloading will appear:
The app normally downloads within one minute.
Installing the Jenkins plugin
You also need to download a plugin on the Jenkins side called Jira Integration for Jenkins. It is required.
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:
- For security purposes, only ports 80 443, 8080 and 8443, and protocols http and https, are supported on Jira Cloud.
- The Jenkins counterpart plug-in is required to be installed before the site can be added on Jira Cloud.
- You should whitelist the IP addresses to make sure your integration works as intended.
-
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