Jira

Version: 3.1.1Minimum Jenkins requirement: 2.176.4ID: jira
Installs: 71484
Last released:
Maintainers
Olivier Lamy
Radek Antoniuk

Documentation GitHub release Jenkins CI Travis CI

Jenkins Plugin Installs Coverage Contributors

About the plugin

This plugin integrates with Jenkins the Atlassian Jira Software (both Cloud and Server versions). For bug reports, see bugs or all open issues. For documentation, see official plugin site.

Reporting Bugs

Before reporting a new bug, check currently open issues in JIRA.

When creating a new issue, provide as much information as possible including:

  • steps to reproduce the issue and possible workarounds if known (Description field)

  • Jenkins and plugin versions (Environment field)

    You can obtain the list using using Jenkins Script console at http://<jenkins-ip:8080>/script:

println("Jenkins:" + Jenkins.instance.getVersion())

Jenkins.instance.pluginManager.plugins.each{
  plugin ->
    println ("${plugin.getDisplayName()} (${plugin.getShortName()}): ${plugin.getVersion()}")
}

Configuring the plugin

Usage with Jira Cloud

With Atlassian Jira Cloud, it's not possible to create a user without an email, so you need to create API token that will be used as a service user by Jenkins to execute API calls to Jira Cloud - follow Atlassian API tokens documentation

Then create a global Jenkins credential:

  • put Atlassian ID email as username
  • API token as password.

You can check if your API token works correctly by getting a correct JSON issue response with this command (where TEST-1 is an example issue in your project):

$ curl -X GET -u <email>:<API token> -H "Content-Type: application/json"  https://<YourCloudInstanceName>.atlassian.net/rest/api/latest/issue/TEST-1

Also make sure that CAPTCHA is not triggered for your user as this will prevent the API token to work - see CAPTCHA section in Atlassian REST API documentation.

Using Jira REST API

This plugin has an optional feature to update Jira issues with a back pointer to Jenkins build pages. This allows the submitter and watchers to quickly find out which build they need to pick up to get the fix.

Jira Issue links in build Changelog

When you configure your Jira site in Jenkins, the plugin will automatically hyperlink all matching issue names to Jira.

If you have additionally provided username/password to Jira, the hyperlinks will also contain tooltips with the issue summary.

Updating Jira issues with back pointers

If you also want to use this feature, you need to supply a valid user id/password. If you need the comment only to be visible to a certain Jira group, e.g. Software Development, enter the groupname. 

Now you also need to configure jobs. I figured you might not always have write access to the Jira (say you have a Jenkins build for one of the Apache commons project that you depend on), so that's why this is optional.

And the following screen shows how Jira issue is updated:

By taking advantages of Jenkins' fingerprint feature, when your other projects that depend on this project pick up a build with a fix, those build numbers can also be recorded in Jira.

This is quite handy when a bug is fixed in one of the libraries, yet the submitter wants a fix in a different project. This happens often in my work, where a bug is reported against JAX-WS but the fix is in JAXB. 

For curious mind, see this thread for how this works behind the scene.

Referencing Jira Release version 

To reference Jira Release versions in your build, you can pull these releases directly from Jira by adding the Jira Release Version Parameter. 

This can be useful for generating release notes, trigerring parameterized build, etc.

Generating Release Notes

You can also generate release notes to be used during your build. These notes can be retrieved from an environment variable. See the Maven Project Plugin for the environment variables found within the POM.

After your build has run, you can also have the plugin mark a release as resolved. This typically will be a release you specified in your Build Parameters.

The plugin can also move certain issues matching a JQL query to a new release version.

Sample usage of generated Release Notes:

Jira Authentication & Permissions required

Note: As a rule of thumb, you should be always using a service account (instead of a personal account) to integrate Jenkins with Jira.

Make sure that the Jira user used by Jenkins has enough permissions to execute its actions. You can do that via Jira Permission Helper tool.

  • For creating Jira issues, the user has to be able to Create Issues in the specified project
  • If you additionally enter assignee or component field values, make sure that:
    • both of the fields are assigned to the corresponding Jira Screen
    • the Jira user is Assignable in the project
    • the Jenkins Jira user can Assign issues

System properties

Property Name Functionality Change
-Dhudson.plugins.jira.JiraMailAddressResolver.disabled=true Use to disable resolving user email from Jira usernames. Currently there is no option for this in UI.

Related Resources

Common issues

Jenkins<>Jira SSL connectivity problems

If you encounter stacktraces like this:

Caused by: javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target

make sure the JRE/JDK that Jenkins master is running (or the Jenkins slaves are running) contain the valid CA chain certificates that Jira is running with. You can test it using this SSLPoke.java class:

$ wget -O SSLPoke.java https://gist.githubusercontent.com/warden/e4ef13ea60f24d458405613be4ddbc51/raw/7f258a30be4ddea7b67239b40ae305f6a2e98e0a/SSLPoke.java

$ /usr/java/jdk1.8.0_131/bin/javac SSLPoke.java

$ /usr/java/jdk1.8.0_131/jre/bin/java SSLPoke jira.domain.com 443
Successfully connected

References:

Contributing to the Plugin

New feature proposals and bug fix proposals should be submitted as Pull Requests.

Before submitting your change please note that:

  • tests should be added for any changed code - the coverage is automatically checked after submitting the Pull Request
  • the code formatting should follow the defined standard - see Code Style
  • you use findbugs to see if you haven't introduced any new warnings
  • when adding new features please make sure that they support Jenkins Pipeline Plugin - see COMPATIBILITY.md for more information

Testing your changes

There have been many developers involved in the development of this plugin and there are many downstream users who depend on it. Tests help us assure that we're delivering a reliable plugin and that we've communicated our intent to other developers in a way that they can detect when they run tests.

Each change should be covered by appropriate unit tests. In case it is not testable via a unit test, it should be tested against a real Jira instance - possibly both Jira Server and Jira Cloud.

There is a Jira Cloud test instance that we are using for testing the plugin releases - let us know in the Pull Request in case you need access for testing.

Code Style

We try to improve the code quality by conforming to Google Java styleguide, that is defined in google_checks.xml. If you are using an IDE, like IntelliJ IDEA, please:

or

  • install the Checkstyle plugin
  • go to Preferences > Editor > Code Style > Java, select Scheme to Project
  • click the Cog icon and import Checkstyle configuration from google_checks.xml

Currently the formatting is not automatically checked during the build. However, in the effort to improve the quality of the code, maintainers might ask for proper formatting during the review process, so it is better to have it in place sooner than later.

Docker

Start dockerized Jenkins (for testing)

The command below will start a local Jenkins using the version specificied as first argument (or lts):

$ ./examples/start_docker.sh 2.249.2
Build the plugin in Docker environment

The command below allows to build the plugin using maven docker image. This is useful to test building against different Maven/JDK versions. See also SDKMan for a different approach.

$ docker run -it --rm -v "$PWD":/usr/src/mymaven -v "$HOME/.m2:/root/.m2" -w /usr/src/mymaven maven:3.3-jdk-8 mvn clean package

Atlassian sources import

To resolve some binary compatibility issues JENKINS-48357, the sources from the artifact com.atlassian.httpclient:atlassian-httpclient-plugin:0.23 has been imported in the project to have control over http(s) protocol transport layer. The downloaded sources didn't have any license headers but based on the pom sources are Apache License (see pom in src/main/resources/atlassian-httpclient-plugin-0.23.0.pom)

Maintainers Section

Releasing the plugin

  • we use the Release Drafter extension to perform releases, make sure that the PRs are properly labelled
  • there is a Jira Cloud test instance that the changes can be tested against, official maintainers are admins that can grant access for testing to PR submitters on a need-to-have basis
ArchivesGet past versions
Links
Labels