Integrate with Jenkins

Jenkins for Jira provides a free, secure, and reliable way to connect your Jenkins server, running behind the firewall, with either Jira Cloud or Jira Service Management Cloud.

This gives your team more visibility and context on every issue in Jira, showing the latest build status or if your work has been successfully deployed to an environment.

You can also use this information to search across issues using the Jira Query Language (JQL), answering questions like “Which issues in the current sprint have been deployed to production?” You can even add these as quick filters on your boards!

Before you begin

To connect Jenkins for Jira and get data flowing to your Jira projects, you’ll need to perform, or delegate, the following tasks:

1. In Jira, install the Jenkins for Jira app

2. In Jira, start a connection to Jenkins

3. In Jenkins, install the Atlassian Jira Cloud plugin (if necessary)

4. In Jenkins, enter the connection credentials provided in Jira to complete your connection

5. In your source code management platform, or in Jenkins, edit your projects' Jenkinsfiles to set up what data is sent from Jenkins to Jira

In many teams, it makes sense to split these tasks up between team members that have the appropriate permissions and experience.

The Jenkins for Jira connection process will guide you through delegating these tasks. However, before you begin you should know who your Jenkins admin is and which of your team members are responsible for editing the Jenkinsfiles that define your Jenkins pipelines.

If you’re not sure who these team members are, reach out to the Jira project team(s) that are using Jenkins to build and deploy their code. They’ll be able to direct you to the right people.

Install Jenkins for Jira on your Jira Cloud site

Install the Jenkins for Jira (Official) app via Atlassian Marketplace:

1. Log in to your Jira site and go to Apps > Explore more apps.

2. Search for the Jenkins for Jira (Official) app and select Get app.

Start a connection to Jenkins in Jira

After installing the Jenkins for Jira app on your Jira site, you’ll need to start a connection to Jenkins.

1. In Jira, go to Apps > Manage your apps.

2. In the left sidebar, under Apps, select Jenkins for Jira.

3. If this is your first connection, you’ll be taken to the connection wizard. If you’ve previously connected a Jenkins server, select Connect another server to go to the wizard.

Follow the on-screen prompts in the connection wizard. This experience will vary depending on whether you are a Jenkins admin or a Jenkins admin is helping you, but in either case after giving your server a name, you’ll be provided with two credential items: a webhook URL and secret token to use in Jenkins.

To complete the connection process, you or your Jenkins admin will need to log in to Jenkins, set up the server, and use these credentials to complete a connection.

Install the Atlassian Jira Cloud plugin on your Jenkins server

Once a Jira site admin has started a connection in Jira, you’ll need to install the Jira Cloud plugin on Jenkins to complete the connection.

1. Log in to your Jenkins server and go to Manage Jenkins > Plugins > Available plugins.

2. Search for Atlassian Jira Software Cloud and install the plugin.

If you can’t find the plugin in the Available plugins screen, it may already be installed on your server. To check:

1. Log in to your Jenkins server and go to Manage Jenkins > Plugins > Installed plugins.

2. Search for Atlassian Jira Software Cloud.

3. If the plugin is already installed, run any available updates.

Complete the connection on your Jenkins server

With the Atlassian Jira Software Cloud plugin installed on your Jenkins server, and a webhook URL and secret token at hand, you can now complete the connection between Jenkins and Jira.

1. In Jenkins, go to Manage Jenkins > Atlassian Jira Software Cloud.

2. Select Add new site.

3. Enter your Jira site name

4. Enter your Webhook URL

5. Enter your Secret using the Jenkins credential manager.

   1. Select Add

   2. From the Kind dropdown, select Secret text

   3. Paste the secret provided in the Jenkins for Jira connection wizard in the Secret field

   4. Give your secret a descriptive name (such as your site name) in the Description field

   5. Select Add

   6. Use the Secret dropdown to select the secret you just entered.

6. Select Test connection to make sure your credentials are valid for your Jira site.

7. Select Save.

8. If you’ve successfully entered your site name and credentials, you’ll be returned to Manage Jenkins > Atlassian Jira Software Cloud.

9. (Optional) Set up build and deployment automations, if appropriate to your team.

10. Select Save

At this point, your Jenkins server is connected to Jira.

If you’re a Jenkins admin helping a Jira site admin to complete the connection process, let them know you’ve completed the connection. If you’re a Jira site admin with Jenkins permissions (ie: you’re completing the entire setup yourself), it’s time to return to Jira

Set up data flow from your Jenkins server to your Jira site by editing Jenkinsfiles

Once your Jenkins server is connected to Jira, Jira will generate a set up guide to help your team choose what data flows from the server to Jira. Your team must follow this guide to receive build and deployment events from Jenkins.

To access the set up guide for a server:

1. In Jira, go to Apps > Manage your apps

2. In the left sidebar, under Apps, select Jenkins for Jira.

3. Navigate to the server you just selected and open the Set up guide tab. This guide will detail what your team needs to do to set up the flow of data between Jenkins and Jira.

4. In most cases, the information in a set up guide is best used by developers in your project teams. Use Share this guide with your team to send them the guide in a read-only version of the Jenkins management page.

5. Once your team has set up what build events your Jenkins server should send to Jira, you’ll start seeing those events populate the Recent events tab in your server.

How Jenkins for Jira works

For a more detailed explanation of how Jenkins for Jira and the Atlassian Jira Software Cloud plugin for Jenkins servers interact, see How Jenkins for Jira works. Jenkins admins may find that topic useful when setting up advanced options such as sending builds or deployment events automatically.