Issue Reporting

How-To Report an Issue

The Jenkins JIRA is not a support site. If you need assistance or have general questions, visit us in chat, email one of the mailing lists, or post on the community forum.

Before creating an issue

First, determine what kind of issue it is. There are three main types whose use is explained on this page:

  • Bug: Something does not work as intended.

  • New Feature: You want Jenkins to have new functionality.

  • Improvement: Existing functionality should be changed.

Other types (Patch, Task) are not widely used in JIRA. Neither will be explained here. If you want to propose a patch, create an issue of one of the 3 types above and then create a pull request in GitHub.

Before reporting a bug

  • First, search for the error message or general problem description. This can help you find solutions if it’s actually e.g. a configuration problem, or point you to earlier reports in case you’re not the first one experiencing this problem. You can use the search in the issue tracker, or use web search. Stack Overflow may also be a good place to search. Any results will often point you to earlier issue reports if it’s really a bug. You can then watch them and vote for them in JIRA. Voting helps us determine the impact of bugs and prioritize them. If you have doubts that the problem you’re experiencing is the exact same one as you found, prefer to file a new issue (and mention the one(s) you found in the description).

  • Make sure that the problem actually is with Jenkins. If your build seems to fail for no reason, try to build your project outside Jenkins, but in the same general environment (e.g. same machine, same user account, …​). If Jenkins interacts with other systems, make sure that they’re working. If the connections between Jenkins controller and agents fail, make sure the network is reliable.

  • Check the changelogs to see whether the issue has been fixed in newer versions of the affected component. For Jenkins itself, review the long term support changelog, the LTS upgrade guide, and the weekly changelog. If you believe the problem to be in a plugin, review the changelog for the specific plugin on the plugins site. The plugin documentation can also be reached directly by clicking the plugin name in Manage Jenkins » Manage Plugins » Installed. If you’re still unable to resolve the problem and cannot find existing issue reports or related fixes in newer versions of Jenkins or the plugins, file a bug in JIRA.

Before requesting an improvement or feature

  • Check newer versions of Jenkins or the plugin for this feature. They may have the feature already!

  • Search JIRA for existing requests for this feature. You can then watch them and vote for them. Voting helps us determine the demand for requests and prioritize them, so it’s in your interest to actually find these rather than reporting a duplicate.

If you cannot find anything, file an improvement or new feature request in JIRA.

Searching for existing issues makes it easier for us to deal with issue reports and shows which issues are considered important by the community by the number of voters and watchers. It increases the likelihood of related changes. It’s not that obvious when an issue has been reported separately several times with only a few watchers each.

Creating the issue

You need to register an account if you haven’t already. Then, just select Create Issue on the JIRA home page.

  • For Project select:

    • Jenkins for general issues with Jenkins,

    • Security Issues if you want to report a security issue privately

  • For Infrastructure, if you’re reporting a bug with a Jenkins service run by the Jenkins project, open an issue in the dedicated helpdesk on Github.

  • Enter a short but meaningful description of your problem as Summary.

  • For Priority, see here for descriptions of the levels. This is not how urgently you want it fixed. Try to be realistic: Most bugs should be Minor or Major priority. If you found a workaround, reduce the priority, even if it’s a severe problem otherwise.

  • As Component, select core if it’s a problem with Jenkins itself and not any of the plugins. Otherwise, select the name of the plugin; all of them should have a related component. You can also select multiple components e.g. if the problem is in the interaction of the components, or when you’re not sure.

  • Leave the Assignee field to automatic.

What information to provide for Environment and Description

Much of the advice on How To Ask Questions The Smart Way also helps you write great issue reports.

Environment is mostly relevant for bug reports: What is the configuration experiencing the issue? Depending on the type of problem, the following are often relevant:

  • Operating System (including version, and whether it’s 32/64 bit) of all systems involved (your client’s, the Jenkins server’s, all agent nodes'),

  • All relevant JRE/JDK vendors and versions (e.g. Oracle JRE, OpenJDK, …​) and the parameters set.

  • Jenkins and plugin versions, use the below snippet in Jenkins > Manage Jenkins > Script Console:

println("Jenkins: " + Jenkins.instance.getVersion())
println("OS: " + System.getProperty('') + " - " +System.getProperty('os.version'))
println "---"

    .sort { it.getShortName() }
    .each {
        plugin -> println("${plugin.getShortName()}:${plugin.getVersion()}")
  • Whether you’re running Jenkins directly or in a container like Tomcat (which one, in which version?)

  • Whether Jenkins is accessed through a reverse proxy (if so, how is it configured?)

  • How you installed Jenkins (Windows installer, deb/rpm, …​), and how you’re launching any involved agents (via SSH, web browser, command line, …​)

  • Your web browser (+ version). Make sure the issue occurs on supported web browsers.

If this is too much information for the Environment field, just put some of it into the description.

Every Jenkins installation has the /systemInfo URL with information about Jenkins. If you’re not sure what information to provide, copying everything on that page is a good place to start. Another option would be to install the Support Core Plugin, which allows downloading zip files from Jenkins that contain information relevant for investigating bug reports.

The Description should be comprehensive to allow others to understand the problem or improvement request immediately. A few suggestions on what to include (again, mostly applicable to bug reports):

  • Did the issue occur after an upgrade of Jenkins or any plugins? If so, what was/were the previous version(s), what is/are the current version(s)? Does downgrading resolve the issue? For plugins, the previous versions can often be seen in Plugin Manager (where it offers to downgrade to the previous version).

  • Include log output and stack traces of error messages from the UI or any client programs.

  • Provide a complete step-by-step description of how to reproduce the problem. We cannot see your screen, so be comprehensive. Consider switching the Jenkins UI to English by changing your web browser’s configuration to get the labels right.

  • If possible, provide information on the circumstances the issue occurs with (or doesn’t), e.g. "only when starting the agent via SSH", "only when using Tomcat as container", etc. – this may be some work, but it’ll make reproducing and fixing the issue much easier!

  • Does the issue occur with a new Jenkins installation not reusing any old configuration or data? Try to reproduce the problem with a pristine Jenkins installation with as little customization as possible.

  • If the problem occurs in interaction with other systems (e.g. SCM), include their version and other relevant configuration.

  • If the Jenkins UI no longer responds, get a thread dump using e.g. (on Linux) kill -3 <Jenkins PID> or jstack -l <Jenkins PID>.

After creating the issue

Once you’ve created an issue, make sure to respond to requests for additional information in a timely manner, otherwise your issue may be resolved as Incomplete.

If you reported a regression in Jenkins (i.e. a bug that appeared after updating Jenkins itself), consider leaving community feedback on the changelog to let others know about it.

Keep the issue updated. This includes, for example:

  • If you find additional information that may be relevant to the issue, add it to the issue description or write a comment.

  • If it turns out that the bug you reported was actually something else, resolve it. (If you only found a workaround, don’t resolve it yet.)

  • If newer Jenkins versions no longer are affected by the issue, or implemented the feature you requested, make sure to mark your issue as Fixed. This can happen e.g. if there were other reports on the issue, or developers noticed it on their own.