Quick Start Guide
This guide will help you startup the integration between your Jira Software and Jenkins instances.
Step 1: Installing the Jira app
The Jira app is published on the Atlassian Marketplace.
- From the top navigation bar in Jira, choose Gear Icon > Manage apps.
- Entering “jenkins” or “jenkins integration” in the Search the Marketplace box. The “Jenkins Integration for Jira” app will be listed in the search results, likely the first result.
- Install the add-on by clicking on Install.
A confirmation message appears when the app is successfully installed.
Step 2: Installing the Jenkins plug-in
The plug-in for Jenkins “Jira Integration for Jenkins” download is available from the release notes. Once downloaded.
- Navigate to the Manage Jenkins > Manage Plugins page in the web UI.
- Click on the Advanced tab.
- Choose the jenkins-jira-plugin-[version].hpi file under the Upload Plugin section.
- Upload the plugin file.
- If prompted, restart your application to have your change take effect.
Step 3: Add your First Jenkins Site
After you installed the Jira app and Jenkins plug-in, you are ready to configure your first Jenkins Site and enable the jobs to synchronize.
- From the top navigation in Jira, choose Gear Icon > Manage Apps.
- Choose Jenkins Integration > Configuration and click on the Add Site button. This brings up the Add Site dialog.
- Fill in the form and click Create to create your first Jenkins Site
Private SiteSelect this option if the Jira app can’t access the Jenkins site directly.
Jenkins will now notify Jira whenever there is a change that needs to be processed by Jira, so it may take some time for all the jobs to become available in Jira.
- Selected the Type of the site.
- Provide a Name.
- Optionally, check the Auto enable new Jobs checkbox if you want to enable all Jobs on the site by default, including future new
- It is advised that you enable this, since jobs will only become available in Jira after Jenkins notifies Jira of it, and this can time some time depending the build workload on Jenkins.
- Select Private accessibility option if your Jenkins site is behind a firewall or otherwise not accessible for job and build synchronization.
- Provide the Display URL for UI features.
- Save the site and open the Configuration options of the Jenkins site by clicking on the Configuration action of the site.
- Follow the instructions in the dialog box to complete the registration of the site.
- Selected the Type of the site.
- Provide a Name.
- Optionally, check the Auto enable new Jobs checkbox if you want to enable all Jobs on the site by default, including future new jobs.
- Select Public accessibility.
- For security purposes, only ports 80 443, 8080 and 8443, http and https respectively, 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 address 188.8.131.52 to make sure your integration works as intended.
- Provide the Sync URL that should be used for synchronization and other background actions.
- Optionally, 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
- Select Sync Token Authentication to utilise JWT based authentication.
- This option requires version 3.10.0 of the Jenkins counterpart plugin to be installed!
- Select Basic Authentication to utilise username and token based authentication and provide them.
- If you use and 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
If you have enabled the Auto enable new Jobs option in step 3 then your are all set to enjoin the build insight, but if you kept this disabled, then you first need to select the jobs that you want to be synchronized.
- From the Configuration page click on the Site Name.
- Locate the jobs you what to enable for synchronization and enable then 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.
Step 4: Enjoin the Insight
Once build data has been synchronized, any located links between builds and issues will become visible through the different CI Build Panels that the app provides. From there you can inspect the build results related to an issue and take action if needed.