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.
Instead of opening an issue of type Patch, consider submitting a pull request on GitHub. You're probably not going to file a Task. Neither will be explained here.
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 master and slaves 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, the changelog is here. Select "Upcoming changes" to view changes that have been implemented but not yet released. If you believe the problem to be in a plugin, go to the plugin's wiki page to see its change log. The plugin's wiki page 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 whether newer versions of Jenkins or the plugin in question have been released. 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.
That you're searching for existing issues doesn't just make it easier for us to deal with any issue reports, but it will also show which issues are considered important by the community by the number of voters and watchers (and therefore increase 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
- For Project select:
- Jenkins for general issues with Jenkins,
- Security Issues if you want to report a security issue privately, or
- Infrastructure if you're reporting a bug with the Jenkins web site, wiki, or any other services run by the Jenkins project.
- 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 slave nodes'),
- All relevant JRE/JDK vendors and versions (e.g. Oracle JRE, OpenJDK, ...) and the parameters set.
- Jenkins and plugin versions,
- 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 slave nodes (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 slave 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.