HTTP

source	condition	target
✔	✔	✗

source

condition

target

✔

✗

Description

The http resource performs an HTTP request and uses the response.

source

Returns the response body, or one response header when returnresponseheader is set.

condition

Asserts on the response (its status code, its headers, or simply that the request succeeded).

target

Not supported. A target fails with:

Target not supported for the plugin http

Updatecli does not treat an HTTP endpoint as something it can write to. To act on a remote system, use the "Shell" resource with curl and a changedif rule.

When to use it

Most resources that manipulate files already accept an http:// or https:// path for a source or a condition, and reach for it directly. Use the http resource when you need control the others do not give you: a custom verb, request headers, a request body, assertions on the response status, or a value that lives in a response header rather than in the body.

Parameters

Name	Type	Description
request	object	[S][C] Customizes the HTTP request to emit.
body	string	[S][C] Specifies a custom HTTP request body. Required with POST, PUT, PATCH.
headers	object	[S][C] Specifies custom HTTP request headers. Defaults to an empty map.
nofollowredirects	boolean	[S][C] Specifies whether or not to follow redirects. Default to false (e.g. follow HTTP redirections) unless spec.returnresponseheader is set to true (source only).
verb	string	[S][C] Specifies a custom HTTP request verb. Defaults to “GET”.
responseasserts	object	[C] Specifies a set of custom assertions on the HTTP response for the condition.
headers	object	[C] Specifies a set of assertions on the HTTP response headers.
statuscode	integer	[C] Specifies a custom assertion on the HTTP response status code.
returnresponseheader	string	[S] Specifies the header to return as source value (instead of the body).
url	string	[S][C] Specifies the URL of the HTTP request for this resource.

url: The URL to request.
returnresponseheader: Source only. Returns the named response header instead of the body (how you read a Location header without following the redirect).
request: Customises the request that is sent.
responseasserts: Condition only. Assertions on the response.

request

Field Behaviour

Field	Behaviour
`verb`	The HTTP method. Defaults to `GET`.
`body`	The request body. Required with `POST`, `PUT` and `PATCH`.
`headers`	Request headers, as a map. Empty by default.
`nofollowredirects`	Stops at the first response instead of following redirects.

verb

The HTTP method. Defaults to GET.

body

The request body. Required with POST, PUT and PATCH.

headers

Request headers, as a map. Empty by default.

nofollowredirects

Stops at the first response instead of following redirects.

responseasserts

Field Behaviour

Field	Behaviour
`statuscode`	The exact status code expected.
`headers`	Response headers that must match, as a map.

statuscode

The exact status code expected.

headers

Response headers that must match, as a map.

How a condition decides

With statuscode set, the check is an exact comparison (anything else is a failure).

Without it, the outcome depends on the class of the response, and the distinction between failing and erroring matters:

Status	Outcome
1xx, 2xx, 3xx	The condition passes.
4xx	The condition fails - the pipeline stops, but this is not an error. A 404 is a legitimate "not published yet".
5xx	The condition errors. A broken server is not evidence about your assertion.

Status

Outcome

1xx, 2xx, 3xx

The condition passes.

4xx

The condition fails - the pipeline stops, but this is not an error. A 404 is a legitimate "not published yet".

5xx

The condition errors. A broken server is not evidence about your assertion.

That is why checking whether an artifact exists needs no statuscode: a 404 already reports a clean failure.

Reading a redirect target

nofollowredirects combined with returnresponseheader reads where a "latest" URL points without downloading anything, the usual way to turn a GitHub /releases/latest URL into a version:

sources:
  latest:
    kind: http
    spec:
      url: https://github.com/updatecli/updatecli/releases/latest
      returnresponseheader: Location
      request:
        nofollowredirects: true

The 302 response is used as-is, and the source value is the redirect target:

https://github.com/updatecli/updatecli/releases/tag/v0.119.0

Add a transformers block with find or trimprefix to reduce it to the version. For GitHub specifically, githubrelease is the better tool (this pattern is for hosts with no API).

Examples

# updatecli.yaml
name: End to end test of the 'http' resource kind
pipelineid: "e2e/http"

# Sources of type http returns either the body or a header
sources:
  # Returns the content of the 'maven-metadata.xml' file content as source (multi-line, direct HTTP/200)
  getJenkinsWarArtifactMetadatas:
    kind: http
    spec:
      url: https://repo.jenkins-ci.org/releases/org/jenkins-ci/main/jenkins-war/maven-metadata.xml
  # Returns the content of the 'checksums.txt' file content as source (multi-line, following redirections HTTP/3xx)
  getUpdatecli0.65.1Checksums:
    kind: http
    spec:
      url: https://github.com/updatecli/updatecli/releases/download/v0.65.1/checksums.txt # HTTP/302 (GitHub redirection to raw.githubusercontent.com)
  ## Empty Source due to HTTP/3xx not followed (e.g. empty body)
  getUpdatecli0.65.1ChecksumsNoFollow:
    kind: http
    spec:
      url: https://github.com/updatecli/updatecli/releases/download/v0.65.1/checksums.txt # HTTP/302 (GitHub redirection to raw.githubusercontent.com)
      request:
        nofollowredirects: true # Default is false
  # Returns the content of the Header 'Location' (e.g. the target of the HTTP redirect)
  getRedirectLocationForUpdatecliLinuxAmd64Archive:
    kind: http
    spec:
      url: https://github.com/updatecli/updatecli/releases/download/v0.65.1/updatecli_Linux_arm64.tar.gz
      returnresponseheader: Location
  # Returns the content of the 'maven-metadata.xml' file from the private URL (custom headers for the request)
  getWithCustomRequest:
    kind: http
    spec:
      url: https://repo.jenkins-ci.org/releases/org/jenkins-ci/main/jenkins-war/maven-metadata.xml
      request:
        headers:
          Authorization: 'Bearer Token'
          Accept: 'application/xml'
        verb: GET 
  ## Source fails with an error: the URL returns HTTP/404 (same for server-side errors such as HTTP/5xx)
  # failOnHttpError:
  #   kind: http
  #   spec:
  #     url: https://google.com/do-not-exist


conditions:
  # Returns 'true' if the specified URL returns HTTP/1xx, HTTP/2xx or HTTP/3xx
  checkForURL:
    kind: http
    sourceid: getJenkinsWarArtifactMetadatas
    spec:
      url: https://repo.jenkins-ci.org/releases/org/jenkins-ci/main/jenkins-war/maven-metadata.xml
  ## Conditions returns 'false' as the URL returns HTTP/404
  ## If there is an HTTP/500 (server side error) then the conditions fails with an ERROR (different than returning false which "skips" the pipeline)
  # checkForNonExistingUrl:
  #   kind: http
  #   sourceid: getJenkinsWarArtifactMetadatas
  #   spec:
  #     url: https://google.com/do-not-exist
  # Returns 'true' if the specified URL returns HTTP/1xx, HTTP/2xx or HTTP/3xx to the custom request (custom verb and headers)
  checkWithCustomRequest:
    kind: http
    sourceid: getJenkinsWarArtifactMetadatas
    spec:
      url: https://repo.jenkins-ci.org/releases/org/jenkins-ci/main/jenkins-war/maven-metadata.xml
      request:
        headers:
          Authorization: 'Bearer Token'
          Accept: 'application/xml'
        verb: HEAD
  # Returns 'true' if the response code is HTTP/302 and has header "Content-Type" set to "application/xhtml"
  getUpdatecli0.65.1Checksums:
    kind: http
    sourceid: getJenkinsWarArtifactMetadatas
    spec:
      url: https://github.com/updatecli/updatecli/releases/download/v0.65.1/checksums.txt # HTTP/302 (GitHub redirection to raw.githubusercontent.com)
      responseasserts:
        statuscode: 302 
        headers:
          Content-Type: "text/html; charset=utf-8"

# json.yaml
name: Basic Json Example

sources:
  http:
    name: Get value from json
    kind: json
    spec:
      file: https://www.updatecli.io/schema/latest/config.json
      key: $id 
  semverVersion:
    kind: json
    name: Get latest version
    spec:
      file: https://www.updatecli.io/changelogs/updatecli/_index.json
      query: ".Changelogs.[*].Tag"
      versionfilter:
        kind: semver
        pattern: "v0.92.0"

conditions:
  http:
    name: Test value from json
    kind: json
    disablesourceinput: true
    spec:
      file: https://www.updatecli.io/schema/latest/config.json
      key: $schema
      value: http://json-schema.org/draft-04/schema
 
  http-query:
    kind: json
    name: Get latest version
    disablesourceinput: true
    spec:
      file: https://www.updatecli.io/changelogs/updatecli/_index.json
      key: ".Changelogs.(Tag=v0.92.0).PublishedAt"
      value: "2025-01-12 08:14:30 +0000 UTC"

Docs

Title here

HTTP

Description

When to use it

Parameters

request

responseasserts

How a condition decides

Reading a redirect target

Examples

Links

HTTP

Description#

When to use it#

Parameters#

request#

responseasserts#

How a condition decides#

Reading a redirect target#

Examples#

Links#

Description

When to use it

Parameters

request

responseasserts

How a condition decides

Reading a redirect target

Examples

Links