Getting Started

Here are the initial steps you need to follow in order to get Jenkins Integration for Jira up and running.

Install the Jira app from the Atlassian Marketplace

You need to download the app Jenkins Integration for Jira from the Atlassian Marketplace.

Go to Jenkins Integration for Jira on the Atlassian Marketplace.

OR

On top right corner of menu bar select your headshot/icon → scroll down to Atlassian Marketplace → click on Atlassian Marketplace.

Getting Started

You will arrive on the Atlassian Marketplace main page. Search ‘Jenkins integration’ and click enter/return:

Getting Started

The first result should be Jenkins Integration for Jira. Click the button ‘Free trial’:

Getting Started

Click ‘Accept & Install’ to start installation:

Getting Started

The app normally downloads within one minute but could be longer depending on your Jira configuration:

Getting Started

Now you need to get the trial license. Click ‘Get license’:

Getting Started

Note: The app will not work until you have the license activated in your Jira instance.

Getting and applying a license

After clicking on ‘Get license’ you will be redirected to my.atlassian.com. Ensure you are logged in. Agree to the terms of use and then click ‘Generate License’.

Getting Started

You will arrive at a page with the license key. If you have configured your Jira to connect with the Atlassian Marketplace click ‘Apply License’:

Getting Started

You should have the app installed. Go to Step 3: Installing the Jenkins Plugin. If not keep reading.

If you have not configured your Jira to connect with the Atlassian Marketplace you will see this:

Getting Started

You must manually apply the license. Jenkins Integration for Jira will not work until this is done.

How to manually apply the license

Click ‘Close’ on modal dialog window (the popup that says Oh no!). You will see the installed apps on the Manage Apps page.

Go to my.altassian.com in a new browser window (make sure you are logged in).

Scroll down on the page to see licences. Check ‘Trials’ box if not checked.

Getting Started

Expand ‘Jenkins Integration for Jira: Trial’. Copy the license from the ’license key’ field:

Getting Started

Go back to the Atlassian Marketplace → Manage Apps. Click on Jenkins Integration for Jira Server and Data Center to expand it.

Getting Started

Paste the license key into the field ‘License key’.

Getting Started

Click ‘Update’ to save the license key.

Getting Started

Installing the Jenkins plugin

You also need to download a plugin on the Jenkins side called Jira Integration for Jenkins.

Get the latest version of Jira Integration for Jenkins, from the Release Notes.

Go to your Jenkins homepage

Manage Jenkins > Manage Plugins

Under Manage Plugin

Click on the Advanced tab.

Under Upload Plugin

Upload the file you just downloaded. It has the file extension .hpi:

Getting Started

If prompted, restart your Jenkins instance

Connecting Jira and Jenkins

Now you are ready to configure your first Jenkins site (an instance of Jenkins) and enable jobs to synchronize. This is important to do right away as it establishes the data connection between Jira and Jenkins. If you do not do this you will not get any Jenkins data in Jira.

From the top navigation in Jira, choose Gear Icon > Manage Apps

Getting Started

Choose Jenkins Integration > Configuration and then click Connect your first site

This brings up the Add Site dialog. Create a name of the site you are adding:

Getting Started

Under Options check Enabled for Synchronization

Optional: Under Options check Auto enable new Jobs

If you want to enable all Jobs on the site by default, including future new jobs. If you don’t select it you will have to manually select jobs.

Optional: Under Options check CSRF

Only if your site has CSRF enabled. Checked is the default in Jenkins.

Under Accessibility select either Public or Private

If select Public:

  1. Under Sync URL enter the root URL of Jenkins that the app uses to connect.

  2. Optional: 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

  3. Select an Authentication Method

If select Sync Token Authentication then the app will generate access tokens automatically.

If select Basic Authentication you must enter a username and token (the token can be an API token or a password) If you use an 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:

  • 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

  1. Click Create to save the configuration.

If selected Auto enable new jobs you are done. If you DID NOT select Auto enable new jobs then you need to manually enable the jobs you want to sync automatically.

If select Private:

Select this option if the Jira app can’t access the Jenkins site directly.

  1. Add a Display URL (required).

  2. Click Create to save the configuration. This opens the Manage Sites page.

Getting Started
  1. Then you need to manually register your Jira site in Jenkins. Click on Configuration. This opens the configuration dialogue box:
Getting Started
  1. Follow the link in the warning box Register with site. Fill in the site registration form in Jenkins.

Optional step: select the jobs to enable for synchronization

If you have NOT selected Auto enable new Jobs, you will need to select the jobs that should enabled for synchronization.

  1. From the Manage Site page in Jira click on the Site Name.

  2. Locate the jobs you want to enable for synchronization and enable them 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.

We strongly recommend you read about how data synchronization works and how builds are linked to issues.


Next: Configuration
Docs - Jenkins Integration for Jira

Didn’t find what you were looking for?