Jenkins queue actions

This page provides a reference for Jenkins queue actions available in the workflow automation actions catalog. Use these actions to inspect and manage builds waiting in the Jenkins build queue.

Prerequisites

Before using Jenkins queue actions in workflow automation, you need:

A Jenkins server reachable from New Relic Workflow Automation over HTTPS. If your Jenkins instance is behind a firewall or in a private network, allow inbound access from New Relic Workflow Automation.
A Jenkins API token for the account the workflow runs as. Generate one from your Jenkins user profile: Configure > API Token > Add new Token.
A secret in the New Relic Secrets Service containing the Base64-encoded value of username:apiToken. Reference it in the workflow as ${{ :secrets:<keyName> }}.

Get a Jenkins queue item

The action identifier is jenkins.queue.getItem.

Gets queue item details, including the build number once execution starts. Use this action to poll the queue after triggering a build with jenkins.job.trigger to retrieve the build number needed by other job actions.

The executable.number field in the response contains the build number once the build starts executing. It's null while the item is still in the queue.

The following table describes all available input fields for this action.

Input	Type	Description	Example
authToken	String (secret)	Required. Base64-encoded `username:apiToken` for HTTP Basic Authentication.	`${{ :secrets:jenkinsAuthToken }}`
url	String	Required. Jenkins server URL.	`https://jenkins.example.com`
queueId	Int	Required. Queue item ID returned from `jenkins.job.trigger`. Use this to track the build and retrieve the build number once execution starts.	`123`
selectors	List	Optional. JQ selectors to extract specific fields from the HTTP response.	`[{"name": "buildNumber", "expression": ".responseBody \| fromjson.executable.number // null"}]`

The following table describes all output fields returned by this action.

Output	Type	Description
response	Object	Queue item details. `executable.number` contains the build number once the build starts executing — it is `null` while the item is still in the queue. `{ "id": 123, "blocked": false, "buildable": false, "cancelled": false, "why": null, "executable": { "number": 42, "url": "http://jenkins.example.com/job/my-job/42/" }, "task": { "name": "my-job", "url": "http://jenkins.example.com/job/my-job/" }, "inQueueSince": 1625234567000 }`
success	Boolean	`true` on success, `false` on failure.
errorMessage	String	Error message if the request failed. `null` on success.

The following example triggers a build and polls the queue until the build number is available.

Workflow example
name: poll-jenkins-queue description: 'Trigger a build and poll the queue until the build number is available' steps: - name: trigger_build type: action action: jenkins.job.trigger version: 1 inputs: authToken: ${{ :secrets:jenkinsAuthToken }} url: "https://jenkins.example.com" jobName: "my-application-build" selectors: - name: "queueId" expression: ".queueId" next: poll_queue - name: poll_queue type: loop for: in: ${{ [range(0; 10)] }} steps: - name: get_queue_item type: action action: jenkins.queue.getItem version: 1 inputs: authToken: ${{ :secrets:jenkinsAuthToken }} url: "https://jenkins.example.com" queueId: ${{ .steps.trigger_build.outputs.queueId }} selectors: - name: "buildNumber" expression: ".responseBody \| fromjson.executable.number // null" - name: check_if_started type: switch switch: - condition: ${{ .steps.get_queue_item.outputs.buildNumber != null }} next: end next: wait_and_retry - name: wait_and_retry type: wait seconds: 2 next: continue

Workflow example

name: poll-jenkins-queue
description: 'Trigger a build and poll the queue until the build number is available'
steps:
  - name: trigger_build
    type: action
    action: jenkins.job.trigger
    version: 1
    inputs:
      authToken: ${{ :secrets:jenkinsAuthToken }}
      url: "https://jenkins.example.com"
      jobName: "my-application-build"
      selectors:
        - name: "queueId"
          expression: ".queueId"
    next: poll_queue

  - name: poll_queue
    type: loop
    for:
      in: ${{ [range(0; 10)] }}
      steps:
        - name: get_queue_item
          type: action
          action: jenkins.queue.getItem
          version: 1
          inputs:
            authToken: ${{ :secrets:jenkinsAuthToken }}
            url: "https://jenkins.example.com"
            queueId: ${{ .steps.trigger_build.outputs.queueId }}
            selectors:
              - name: "buildNumber"
                expression: ".responseBody | fromjson.executable.number // null"

        - name: check_if_started
          type: switch
          switch:
            - condition: ${{ .steps.get_queue_item.outputs.buildNumber != null }}
              next: end
          next: wait_and_retry

        - name: wait_and_retry
          type: wait
          seconds: 2
          next: continue

Cancel a queued Jenkins build

The action identifier is jenkins.queue.cancel.

Cancels a queued Jenkins build before it starts executing. Requires a queueId obtained from a prior jenkins.job.trigger call.

This action fails if the build has already started executing. To stop an already-running build, use jenkins.job.stop instead.

The following table describes all available input fields for this action.

Input	Type	Description	Example
authToken	String (secret)	Required. Base64-encoded `username:apiToken` for HTTP Basic Authentication.	`${{ :secrets:jenkinsAuthToken }}`
url	String	Required. Jenkins server URL.	`https://jenkins.example.com`
queueId	Int	Required. Queue item ID to cancel. The item must still be in the queue and not yet executing.	`123`
selectors	List	Optional. JQ selectors to extract specific fields from the HTTP response.	`[{"name": "statusCode", "expression": ".statusCode"}]`

The following table describes all output fields returned by this action.

Output	Type	Description
response	Object	Jenkins returns HTTP 204 (No Content) on successful cancellation. Jenkins returns 404 if the queue item is not found or has already started executing. Example: `{ "statusCode": 204, "body": "" }`
success	Boolean	`true` on success, `false` on failure.
errorMessage	String	Error message if cancellation failed. `null` on success.

The following example triggers a Jenkins build then cancels it before it starts executing.

Workflow example
name: cancel-queued-jenkins-build description: 'Trigger a Jenkins build then cancel it before it starts executing' steps: - name: trigger_build type: action action: jenkins.job.trigger version: 1 inputs: authToken: ${{ :secrets:jenkinsAuthToken }} url: "https://jenkins.example.com" jobName: "my-application-build" selectors: - name: "queueId" expression: ".queueId" next: cancel_build - name: cancel_build type: action action: jenkins.queue.cancel version: 1 inputs: authToken: ${{ :secrets:jenkinsAuthToken }} url: "https://jenkins.example.com" queueId: ${{ .steps.trigger_build.outputs.queueId }} next: end

Workflow example

name: cancel-queued-jenkins-build
description: 'Trigger a Jenkins build then cancel it before it starts executing'
steps:
  - name: trigger_build
    type: action
    action: jenkins.job.trigger
    version: 1
    inputs:
      authToken: ${{ :secrets:jenkinsAuthToken }}
      url: "https://jenkins.example.com"
      jobName: "my-application-build"
      selectors:
        - name: "queueId"
          expression: ".queueId"
    next: cancel_build

  - name: cancel_build
    type: action
    action: jenkins.queue.cancel
    version: 1
    inputs:
      authToken: ${{ :secrets:jenkinsAuthToken }}
      url: "https://jenkins.example.com"
      queueId: ${{ .steps.trigger_build.outputs.queueId }}
    next: end

List all items in the Jenkins build queue

The action identifier is jenkins.queue.list.

Lists all items currently in the Jenkins build queue.

The following table describes all available input fields for this action.

Input	Type	Description	Example
authToken	String (secret)	Required. Base64-encoded `username:apiToken` for HTTP Basic Authentication.	`${{ :secrets:jenkinsAuthToken }}`
url	String	Required. Jenkins server URL.	`https://jenkins.example.com`
selectors	List	Optional. JQ selectors to extract specific fields from the HTTP response.	`[{"name": "queueCount", "expression": ".responseBody \| fromjson.items \| length"}]`

The following table describes all output fields returned by this action.

Output	Type	Description
response	Object	All queue items. Each item includes `id`, `task` (job info), and `executable` (build info once the build starts). `{ "items": [ { "id": 123, "blocked": false, "buildable": true, "cancelled": false, "why": "Waiting for next available executor", "task": { "name": "job1", "url": "http://jenkins.example.com/job/job1/" }, "inQueueSince": 1625234567000 } ] }`
success	Boolean	`true` on success, `false` on failure.
errorMessage	String	Error message if the request failed. `null` on success.

The following example lists all items in the Jenkins build queue and extracts the count.

Workflow example
`name: list-jenkins-queue description: 'List all items currently in the Jenkins build queue' steps: - name: list_queue type: action action: jenkins.queue.list version: 1 inputs: authToken: ${{ :secrets:jenkinsAuthToken }} url: "https://jenkins.example.com" selectors: - name: "queueItems" expression: ".responseBody \| fromjson.items" - name: "queueCount" expression: ".responseBody \| fromjson.items \| length" next: end`

Workflow example

name: list-jenkins-queue
description: 'List all items currently in the Jenkins build queue'
steps:
  - name: list_queue
    type: action
    action: jenkins.queue.list
    version: 1
    inputs:
      authToken: ${{ :secrets:jenkinsAuthToken }}
      url: "https://jenkins.example.com"
      selectors:
        - name: "queueItems"
          expression: ".responseBody | fromjson.items"
        - name: "queueCount"
          expression: ".responseBody | fromjson.items | length"
    next: end

Prerequisites.css-21sua1{background:none;border:none;width:0;padding:0;}

Get a Jenkins queue item

Cancel a queued Jenkins build

List all items in the Jenkins build queue

Prerequisites