Web Methods

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

Changes in Jenkins 2.138.4 and Jenkins 2.154

Web methods need to provide some indication that they are intended for Stapler routing:

  • Any applicable annotation recognized by Stapler, e.g., @RequirePOST.

  • Any inferable parameter type, e.g., StaplerRequest.

  • Any applicable parameter annotation, recognized by Stapler, e.g., @AncestorInPath.

  • Any declared exception type implementing HttpResponse, e.g., HttpResponseException.

  • A return type implementing HttpResponse.

If none of these indicators are present, the method will no longer be invoked by Stapler as a web method starting in Jenkins 2.138.4 and Jenkins 2.154. Some examples:

public void doRun()
public String doRun(String foo) throws Exception

When the SECURITY-595 fix prevents access to a URL, a warning message is written to the Jenkins log that looks similar to the following:

WARNING: New Stapler routing rules result in the URL "/example" no longer being allowed. If you consider it safe to use, add the following to the whitelist: "method hudson.model.Hudson doExample". Learn more: https://www.jenkins.io/redirect/stapler-routing

Administrators can follow the instructions to make the method or field work on their specific instance, but ideally the component is changed to prevent the problem in the first place:

  • Add any of the indicators listed in the previous section that would make your method routable.

  • Annotate the web method @StaplerDispatchable. You may need to add a dependency to the io.jenkins.stapler:io.jenkins.stapler library to make this annotation available.