Quick Start Guide

This guide will help you startup the integration between your Jira Software and Jenkins instances.

Step 1: Installing the Jira add-on

The Jira add-on 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 add-ons or Find new apps administration page.

  1. From the top navigation bar in Jira, choose Gear Icon > Add-ons or Manage apps.
  2. Entering "jenkins" or "jenkins integration" in the Search the Marketplace box. The "Jenkins Integration for Jira" will be listed in the search results, likely the first result.
  3. Install the add-on by clicking on Install.
    A confirmation message appears when the app is successfully installed.
  4. If prompted, restart your application to have your change take effect.

Installing the add-on by file upload

The add-on for Jira "Jenkins Integration for Jira" is available for download form the release notes. Alternatively, you can download the add-on from the Atlassian Marketplace listing. Once downloaded.

  1. From the top navigation bar in Jira, choose Gear Icon > Add-ons or Manage apps.
  2. Click the Upload add-on or Upload app link at the top right side of the page.  
  3. Select  file to upload using the file chooser.

  4. Click Upload
    A confirmation message appears when the app is successfully installed.
  5. If prompted, restart your application to have your change take effect.

Step 2: Installing the Jenkins add-on 

The add-on for Jenkins "Jira Integration for Jenkins" is available for download form the release notes. Once downloaded.

  1. Navigate to the Manage Jenkins > Manage Plugins page in the web UI.

  2. Click on the Advanced tab.

  3. Choose the jenkins-jira-plugin-[version].hpi file under the Upload Plugin section.

  4. Upload the plugin file.

  5. If prompted, restart your application to have your change take effect.

Step 3: Add your First Jenkins Site

After you installed the add-ons, you are ready to configure your first Jenkins Site and enable the jobs to synchronize.

  1. From the top navigation in Jira, choose Gear Icon > Applications.
  2. Choose Jenkins Integration > Configuration and click on the Add Site button.
    This brings up the Add Site dialog.
  3. Fill in the form

    1. Selected the Type of the site.
    2. Provide a Name.
    3. Provide the Sync URL that should be used for synchronization and other background actions.

      (warning) For security purposes, only ports 80 443, 8080 and 8443, http and https respectively, are supported on Jira Cloud.
      (warning) The Jenkins counterpart add-on is required to be installed before the site can be added on Jira Cloud.
      (warning) If you're Jenkins site is behind a firewall or if you use whitelisting, then contact support for assistance.

    4. Optionally, provide a Display URL incase the RPC URL is not accessible by users and a different URL should be used in the UI features of the plugin.
    5. Optionally, check the Auto enable new Jobs checkbox if you want to enable all Jobs on the site by default, including future new jobs.
    6. Optionally, provide basic authentication details in the form of an Username and Token.
      (warning) If you use and external source (like LDAP, AD or Crowd) for authentication, Then it could be that you need to 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:

      1.  Login on Jenkins using the username and password of the synchronization account
      2. Click on the Account Name in the top-right corner of the page after login
      3. Then click on the Configure link in the left menu
      4. The API Token can now be displayed by clicking on the Show API Token... button

    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.

  4. Click Create to create your first Jenkins Site

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.

  1. From the Configuration page click on the Site Name.
  2. Click on Manage Jobs to open the Manage Jobs dialog. Locate the job(s) you what to enable for synchronization and enable then by checking the box in front of there name. Click Submit to enable the selected jobs.

  3. Open the Manage Jobs dialog again by clicking on Manage Jobs and click on Refresh Jobs 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 add-on 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 an issue key of an existing Jira issue can be found in the job and build data that was synchronzied.

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

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.

It is important to note that the issue keys in the commit message must follow the rules set by Atlassian on the format of Project Keys and therefor Issue Keys. Details on the format rules can be found in there documentation Changing the project key format.