This plugin sends a HTTP/HTTPS request to a user specified URL. The request is made via job execution in Jenkins and depending on the HTTP response the job can be marked as failed (configurable). For example, responses such as 404 and 500 can make the job fail. When a job fails it will log the response to help identify the problem.
According to the setting of HTTP mode the request will be performed either using HTTP GET or POST. If there is no such setting then it will use the default from global settings. Default there is POST.
The following features are available in both Pipeline and traditional project types:
-
Programmable HTTP method: GET, POST, PUT, PATCH, DELETE, or HEAD
-
Programmable range of expected response codes (a response code outside the range fails the build)
-
Supports Basic Authentication (see global configuration)
-
Supports Form Authentication (see global configuration)
-
You can specify a string that must be present in the response (if the string is not present, the build fails)
-
You can set a connection timeout limit (build fails if timeout is exceeded)
-
You can set an "Accept" header directly
-
You can set a "Content-Type" header directly
-
You can set any custom header
|
ℹ️
|
Feature Availability
The following features are only present in the non-pipeline version of the plugin. For the Pipeline version, these features are available programmatically. |
-
You can send the build parameters as URL query strings
-
You can store the response to a file, built-in to the plugin
In a Pipeline job, you have total control over how the url is formed. Suppose you have a build parameter called “param1”, you can pass it to the HTTP request programmatically like so:
httpRequest "http://httpbin.org/response-headers?param1=${param1}"If you wish to save the response to a file, you need to grab a workspace. You can do this with a
node Pipeline step. For example:
def response = httpRequest "http://httpbin.org/response-headers?param1=${param1}"
node() {
writeFile file: 'response.txt', text: response.content
}You can access the response status code, content and headers programmatically:
def response = httpRequest "http://httpbin.org/response-headers?param1=${param1}"
println("Status: ${response.status}")
println("Response: ${response.content}")
println("Headers: ${response.headers}")You may also send content in the body of the request, such as for a PATCH request:
// create payload
def patchOrg = """
{"description": "$description"}
"""
def response = httpRequest acceptType: 'APPLICATION_JSON', contentType: 'APPLICATION_JSON',
httpMode: 'PATCH', requestBody: patchOrg,
url: "https://api.github.com/orgs/${orgName}"You may also send content in the body of the request, such as for a POST request:
httpRequest acceptType: 'APPLICATION_JSON', contentType: 'APPLICATION_JSON',
httpMode: 'POST', quiet: true,
requestBody: '''{
"display-name" : "my_Username",
"email" : "user@example.test",
"password" : {
"value" : "my_password"
},
}''',
url: 'https://api.github.com/orgs/${orgName}'You can also set custom headers:
def response = httpRequest customHeaders: [[name: 'foo', value: 'bar']]You can also set custom headers with mask set true:
def response = httpRequest customHeaders: [[maskValue: true, name: 'foo', value: 'bar']],
url: 'https://api.github.com/orgs/${orgName}'You can send multipart/form-data forms:
def response = httpRequest httpMode: 'POST', formData: [
[contentType: 'application/json', name: 'model', body: '{"foo": "bar"}'],
[contentType: 'text/plain', name: 'file', fileName: 'readme.txt',
uploadFile: 'data/lipsum.txt']]You can send a request with form-data:
def response = httpRequest acceptType: 'APPLICATION_JSON', contentType: 'APPLICATION_FORM_DATA',
formData: [[body: '''{
"name" : "example",
"type" : "bot"
}''',
contentType: 'text/plain', fileName: 'sample', name: 'data',
uploadFile: './files/readme.txt']],
httpMode: 'POST', quiet: true, responseHandle: 'NONE', timeout: null,
url: 'https://api.github.com/orgs/${orgName}',
validResponseCodes: '200,404', validResponseContent: 'token'You can send multipart file and multipart entity name:
def response = httpRequest acceptType: 'APPLICATION_JSON', contentType: 'APPLICATION_OCTETSTREAM',
httpMode: 'POST', multipartName: 'file', quiet: true,
responseHandle: 'NONE', timeout: null, uploadFile: './files/readme.txt',
url: 'https://api.github.com/orgs/${orgName}'You can send a request with SSL error ignored
def response = httpRequest ignoreSslErrors: true, responseHandle: 'NONE',
url: 'https://api.github.com/orgs/${orgName}'You can send a request with http proxy
def response = httpRequest httpProxy: 'http://proxy.local', responseHandle: 'NONE',
url: 'https://api.github.com/orgs/${orgName}'You can send a request with http proxy authenticate
def response = httpRequest httpProxy-authenticate: Basic, 'http://proxy.local',
responseHandle: 'NONE', url: 'https://api.github.com/orgs/${orgName}'You can send a request with accepted response codes
def response = httpRequest responseHandle: 'NONE', validResponseCodes: '200,404',
url: 'https://api.github.com/orgs/${orgName}'You can send a request with accepted response content
def response = httpRequest responseHandle: 'STRING',
url: 'https://api.github.com/orgs/${orgName}',
validResponseCodes: '200,404', validResponseContent: 'token'You can send a request with connection timeout
def response = httpRequest timeout: 30, url: 'https://api.github.com/orgs/${orgName}'You can send a request where output is written to file
def response = httpRequest outputFile: 'readme.txt', url:'https://api.github.com/orgs/${orgName}'You can send a request where response is printed on the console
def response = httpRequest consoleLogResponseBody: true,
url:'https://api.github.com/orgs/${orgName}'You can send a request without logging output — with logs turned off
def response = httpRequest quiet: true, url:'https://api.github.com/orgs/${orgName}'You can handle response
def response = httpRequest responseHandle: 'LEAVE_OPEN',
url: "https://api.github.com/orgs/${orgName}"
response.close() // must call response.close() after a LEAVE_OPENYou can use a Jenkins credential to authenticate the request
def response = httpRequest authenticate: 'my-jenkins-credential-id',
url: 'https://api.github.com/user/jenkinsci'For details on the Pipeline features, use the Pipeline snippet generator in the Pipeline job configuration.
|
|
Known Limitations
If Jenkins is restarted before the HTTP response comes back, the build will fail. |
The plugin can be built and tested locally using a Maven Docker container:
docker run -it --rm -v "$(pwd)":/usr/src/mymaven -w /usr/src/mymaven maven:3.3-jdk-8 mvn test
Parameters are escaped, which means if you try to pass another value inside a value, it will not happen.
In the example below, the key “name” will be passed with a value of “jenkins&os=linux”. Note that “os” is not a parameter - it is part of the value). At the HTTP server-side no parameter named “os” will exist.
|
🔥
|
Regarding Logging & Sensitive Information
Every execution will log all parameters. Be careful to not pass private information such as passwords or personal information. |
Report issues and enhancements in the Jenkins issue tracker.
Use the http-request-plugin component in the JENKINS project.
Refer to our contribution guidelines.
Licensed under the MIT License.