Here are the initial steps you need to follow in order to get Jenkins Integration for Jira up and running.
Step 1: Installing the Jira app
The Jira app is published on the Atlassian Marketplace.
Installing the add-on directly for the Atlassian Marketplace
If you are connected to the Atlassian Marketplace website from your Jira’s administration console, you can install apps by clicking the Install button from the Find new apps administration page.
- 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.
Installing the add-on by file upload
The app for Jira “Jenkins Integration for Jira” is available for download form the release notes. Alternatively, you can download the app from the Atlassian Marketplace listing. Once downloaded.
- From the top navigation bar in Jira, choose Gear Icon > Manage apps.
- Click the Upload app link at the top right side of the page.
- Select jira-jenkins-plugin-[version].obr file to upload using the file chooser.
- Click Upload.
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 > Manage Sites 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
Public 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.
-
- 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.
-
- 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 or higher 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
Private Site
Select this option if the Jira app can’t access the Jenkins site directly.Private Jenkins sites will need to have Jira Integration for Jenkins - 3.6.0 or newer installed for the integration to work.- 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.
- 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.
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.On large Jenkins instances, or if you know upfront that you are only interested in a subset of jobs from Jenkins, the is it best to disable Auto enable new Jobs. This will cause the integration to only synchronize job details when the site is added, but will not synchronize any builds. Only after a job is enabled for synchronization will its builds be synchronized.
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 Manage Sites 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.
Linking Builds to Issues
Jenkins builds are linked to Jira issues if a key of an existing Jira issue can be found in the job and build data that was synchronized.
The following elements are inspected to extract Jira issue keys:
- Job display name
- Job description
- Job url
- Build display name
- Build description
- Build trigger cause
- Change-set commit messages
- Git branch names
Any potential issue key located will be verified to exist, and a link between the build is issue is only created if the issue exists in Jira.
Next: Configuration