Issue Reporting

This site is the new docs site currently being tested. For the actual docs in use please go to https://www.jenkins.io/doc.

How-To Report an Issue

Jenkins JIRA is an issue tracker, 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, identify the location of the issue. Are you reporting an issue in Jenkins itself or one of its plugins? We document all the issues in Jenkins on JIRA. Plugins may use JIRA or Github for issue tracking, see Creating the Issue for details. If you are reporting an issue with the jenkins.io site, please create an issue in our GitHub issue tracker.

After that, 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.

  • Improvement: Either a current functionality should be improved or new functionality should be added.

  • Vulnerabilities: Security related issues in Jenkins

Other types (Patch, Task) are not used in JIRA. Neither will be explained here. If you want to propose a patch, create an issue using one of the 3 types above, and then create a pull request on GitHub as explained here. Report issues with infrastructure services hosted by the Jenkins project (jenkins.io, accounts.jenkins.io, etc.) at the dedicated help desk.

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 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, or subscribe to notifications in Github Issues. 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, and prefer to file a new issue, be sure to mention the one(s) you found in the description. 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 » 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 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.

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 or Github Issues for existing requests for this feature. You can then watch 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 creating a duplicate.

If you cannot find anything, file an improvement or new feature request in the issue tracker for the specific plugin. Open the page for the plugin and select the "Report an issue" link in the Links section on the right side of the plugin page.

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

If you are reporting an issue in Jenkins, then you’ll have to report it on JIRA. However if the issue you’re reporting is in one of Jenkins' plugins, you’ll have to follow these steps:

  • Open the Plugin Site.

  • Search for the Plugin and open its page.

  • Click the Report an issue link in the Links section on the right side of the plugin page.

Reporting an issue on JIRA

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.

  • Leave the Assignee field to automatic.

Reporting an issue on GitHub

You need to have a Github account. Register an account if you haven’t already.

  • If you are redirected to the Github issue tracker from the Plugin Site, you will see something like this:

    Github Issue Page

  • Select Get started next to the type of issue you’d like to open.

    Get Started Button

  • After that, fill in the details of the issue according to the Github issue template provided for each type of issue.

  • Don’t forget to subscribe to the issue so you’ll get notifications regarding any updates on the issue.

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('os.name')} - ${System.getProperty('os.version')}")
println("Java: ${System.getProperty('java.version')} - ${System.getProperty('java.vm.vendor')} (${System.getProperty('java.vm.name')})")
println "---"

Jenkins.instance.pluginManager.plugins
    .collect()
    .sort { it.getShortName() }
    .each {
        plugin -> println("${plugin.getShortName()}:${plugin.getVersion()}")
    }
return

  • 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.