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 > 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.

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 >Manage  Apps.

  2. Choose Jenkins Integration > Configuration and click on the Add Site button.
    This brings up the Add Site dialog.
  3. Fill in the form

    Private Site

    Private Jenkins sites will need to have Jira Integration for Jenkins - 3.6.0 or newer installed for the integration to work.

    • 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.
      (info) 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 configuration 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.

    Public 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.
    • 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) You should whitelist the IP address to make sure your integration work as intended.

    • Optionally, provide a Display URL incase the Sync URL is not accessible by users and a different URL should be used in the UI features.
    • Select an Authentication Mehtod
      • Select Sync Token Authentication to utilise the JWT based authentication.
        (warning) This option requires Jira Integration for Jenkins - 3.10.0 or newer installed to make it work.
      • Select Basic Authentication to utilise username and token based authentication, and provide them.
        (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.

        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. Locate the jobs you what to enable for synchronization and enable then by toggling the toggle button in front of their names. 

  3. 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 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
  • 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.

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.