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.

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.

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

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.

  1. From the top navigation bar in Jira, choose Gear Icon > Manage apps.
  2. Click the Upload app link at the top right side of the page.
  3. Select jira-jenkins-plugin-[version].obr file to upload using the file chooser.
  4. 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.

  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 Jira app and Jenkins plug-in, 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 and click Create to create your first Jenkins Site

    Private Site

    1. Selected the Type of the site.
    2. Provide a Name.
    3. 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.
    4. Select Private accessibility option if your Jenkins site is behind a firewall or otherwise not accessible for job and build synchronization.
    5. Provide the Display URL for UI features.
    6. Save the site and open the Configuration options of the Jenkins site by clicking on the Configuration action of the site.
    7. Follow the instructions in the dialog box to complete the registration of the site.

    Public Site

    1. Selected the Type of the site.
    2. Provide a Name.
    3. Optionally, check the Auto enable new Jobs checkbox if you want to enable all Jobs on the site by default, including future new jobs.
    4. Select Public accessibility.
    5. Provide the Sync URL that should be used for synchronization and other background actions.
    6. 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.
    7. 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.
      • 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

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 app provides. From there you can inspect the build results related to an issue and take action if needed.