--- title: Jenkins queue actions source: https://docs.newrelic.com/docs/workflow-automation/setup-and-configure/actions-catalog/jenkins/jenkins-queue --- 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: }}`. ## 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`](https://docs.newrelic.com/docs/workflow-automation/setup-and-configure/actions-catalog/jenkins/jenkins-job#trigger-a-jenkins-job) 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. ### Inputs 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"}]` | ### Outputs 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. ```json { "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. | ### Example The following example triggers a build and polls the queue until the build number is available. | Workflow example | | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ```yaml 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`](https://docs.newrelic.com/docs/workflow-automation/setup-and-configure/actions-catalog/jenkins/jenkins-job#stop-a-running-jenkins-build) instead. ### Inputs 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"}]` | ### Outputs 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. | ### Example The following example triggers a Jenkins build then cancels it before it starts executing. | Workflow example | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | ```yaml 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. ### Inputs 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"}]` | ### Outputs 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). ```json { "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. | ### Example The following example lists all items in the Jenkins build queue and extracts the count. | Workflow example | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ```yaml 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 ``` |