Jenkins ExecModule

Overview

JenkinsModule connects ValkyrAI workflows to the Jenkins Remote Access API through the native map I/O ExecModule ABI. Workflow Studio discovers it as JenkinsModule. The Jenkins origin, username, and API token resolve only from a bound READY IntegrationAccount; workflow input cannot supply credentials or redirect the connector to another host.

The initial production surface focuses on governed CI/CD observation and control:

• connection and infrastructure: verify_connection, list_nodes;
• jobs and builds: list_jobs, get_job, list_builds, get_build, get_build_log;
• approved execution: trigger_build, stop_build;
• queue control: list_queue_items, get_queue_item, cancel_queue_item.

n8n's official Jenkins node is the functional reference for API-token authentication, build triggers, parameter encoding, job paths, and bounded build reads. ValkyrAI adds queue and node evidence, progressive log reads, fixed IntegrationAccount origins, explicit stop/cancel confirmation, response bounds, read-only retries, and credential redaction. Jenkins controller restart, shutdown, quiet-down, arbitrary script, plugin, credential, and raw-request operations are intentionally excluded.

Usage

1. Create a dedicated Jenkins automation user and API token.
2. Grant only the Overall/Read, Job/Read, Job/Build, Job/Cancel, and View/Read permissions required by the selected operations.
3. Store the Jenkins HTTPS origin, including any context path such as /jenkins, in IntegrationAccount.accountId.
4. Store the Jenkins user ID in IntegrationAccount.username and the API token in encrypted apiKey.
5. Set the account status to READY and bind it through ExecModuleConfig.authConfig.integrationAccount.
6. Use list_jobs or get_job to confirm the exact job path before triggering or stopping a build.

Inputs

Name	Type	Requirement	Default	Description and constraints
operation	string	Required	None	One of the twelve documented operations.
jobPath	string	Job/build/log operations	None	Slash-delimited folder and job path; 1–10 segments, each at most 128 characters.
buildNumber	integer	Build/log/stop operations	None	Positive Jenkins build number.
queueId	integer	Queue item/cancel operations	None	Positive Jenkins queue item ID.
parameters	object or JSON string	Optional trigger_build	{}	Up to 100 scalar values; names match [A-Za-z_][A-Za-z0-9_.-]*; 256 KiB total. Plaintext secret-bearing fields are rejected.
offset	integer	Optional tree-list continuation	0	Starting job/build slice offset from 0 through 1,000,000.
limit	integer	Optional lists	100	Maximum returned resources, 1–10,000.
returnAll	boolean	Optional job/build lists	false	Follow bounded tree slices until exhaustion or 10,000 results.
logOffset	integer	Optional get_build_log	0	Jenkins progressive console byte offset.
maxLogBytes	integer	Optional get_build_log	262144	Maximum response bytes, 1,024–1,048,576.
confirmStop	boolean	Required stop_build	false	Must be true to stop a running build.
confirmCancel	boolean	Required cancel_queue_item	false	Must be true to remove a queued build.

Folder paths are converted to Jenkins' repeated /job/<segment> route shape with each segment encoded separately. Build parameters accept strings, numbers, and booleans only. Use Jenkins credentials bindings for sensitive build material; do not put plaintext secrets in workflow payloads.

Outputs

Name	Type	When present	Description
status	string	Always	success or error.
operation	string	Always	Normalized operation name.
attempts	integer	Always	Total provider attempts across tree slices.
httpStatus	integer	Provider responded	Last Jenkins HTTP status.
data	object	Single-resource/mutation success	Bounded Jenkins object or {accepted:true} for an empty successful mutation.
id, name, number, queueId	scalar	Provider returns it	Safe convenience identity fields.
providerStatus	string	Build result is available	Jenkins build result such as SUCCESS or FAILURE; it never replaces module status.
items / count	array / integer	List success	Bounded provider resources and emitted count.
hasMore / nextOffset	boolean / integer	Job/build list success	Tree-slice continuation state.
text / bytes	string / integer	Progressive log success	Redacted console chunk and emitted byte count.
nextLogOffset	integer	Progressive log success	Next start value from X-Text-Size.
jenkinsVersion, sessionId	string	Jenkins supplies headers	Safe runtime evidence from Jenkins response headers.
error	object	Failure	Safe {code, message, httpStatus?, retryable} details.

The module never emits the configured origin, username/API-token pair, Basic header, or raw Location URL. Console and provider error text pass through ValkyrAI's shared workflow sensitive-data policy.

IntegrationAccount Requirements

Setting	Requirement
Provider	Jenkins Remote Access API
Authentication	Jenkins username plus API token using HTTP Basic authentication
accountName	Human-readable Jenkins automation identity
accountId	Required clean HTTPS Jenkins origin, including an optional context path
username	Required Jenkins user ID; whitespace is not allowed
apiKey	Preferred encrypted SecureField containing the Jenkins API token
password	Encrypted fallback for an API token only; account passwords are not recommended
status	Must be READY

API-token-authenticated scripted requests are exempt from Jenkins' CSRF crumb requirement. Do not disable Jenkins CSRF protection. Restrict the automation user to the exact folders/jobs it needs, and rotate tokens through the IntegrationAccount lifecycle rather than workflow inputs.

Configuration

{
  "version": "1.0.0",
  "authConfig": {
    "authStrategy": 1,
    "integrationAccount": "integration-account:jenkins-release-automation"
  },
  "retryPolicy": {
    "maxAttempts": 3,
    "backoffStrategy": "EXPONENTIAL",
    "initialDelayMs": 1000,
    "maxDelayMs": 60000,
    "jitter": false
  },
  "executionConfig": {"timeoutMs": 30000},
  "payloadConfig": {
    "parameters": "{\"operation\":\"list_builds\",\"jobPath\":\"release/api-production\",\"limit\":25}"
  }
}

The integration-account value is symbolic. Persisted workflows use the generated relationship and never plaintext Jenkins credentials.

Operations

Operation	Jenkins behavior	Side effect
verify_connection	Reads bounded controller mode, executor, security, and quiet-down state.	Read-only; safe retries.
list_jobs	Lists top-level jobs using bounded Jenkins tree slices.	Read-only; safe retries.
get_job	Reads one folder-aware job plus health, last-build, and parameter definitions.	Read-only; safe retries.
list_builds	Lists bounded build summaries for one job.	Read-only; safe retries.
get_build	Reads one build, causes, culprits, and bounded change evidence.	Read-only; safe retries.
get_build_log	Reads one bounded progressive console chunk.	Read-only; safe retries.
trigger_build	Calls build or buildWithParameters; returns a queue ID when Jenkins supplies one.	Enqueues a build; single attempt.
stop_build	Requests stop for one build after confirmStop=true.	Interrupts work; single attempt.
list_queue_items	Lists bounded queue state.	Read-only; safe retries.
get_queue_item	Reads one queue item and causes.	Read-only; safe retries.
cancel_queue_item	Removes one queued item after confirmCancel=true.	Cancels queued work; single attempt.
list_nodes	Lists bounded executor/node availability.	Read-only; safe retries.

Errors and Failure Modes

Code	Typical cause	Retryable	Resolution
VALIDATION_ERROR	Invalid account origin, job path, identifier, parameter map, limit, or missing confirmation.	No	Correct the named value; no unsafe request was sent.
UNSUPPORTED_OPERATION	Unknown operation.	No	Select a documented operation.
INTEGRATION_ACCOUNT_REQUIRED	No bound account.	No	Bind a Jenkins IntegrationAccount.
INTEGRATION_ACCOUNT_NOT_READY	Account status is not READY.	No	Repair or reconnect the account.
JENKINS_HTTP_400	Malformed tree or build parameter.	No	Correct bounded input.
JENKINS_HTTP_401 / 403	Invalid token or insufficient Jenkins permission.	No	Rotate credentials or grant least privilege.
JENKINS_HTTP_404	Job, build, queue item, or endpoint is absent or hidden.	No	Re-run discovery with the same account.
JENKINS_HTTP_429 / 5xx	Rate limiting, restart, proxy, or transient controller failure.	Yes for reads	Honor backoff; inspect Jenkins state before repeating a mutation.
NETWORK_ERROR	Timeout, DNS, TLS, or connectivity failure.	Yes for reads	Verify the configured origin and network path. Reconcile queue/build state before retrying a write.
RESPONSE_TOO_LARGE	JSON exceeded 5 MiB or a log chunk exceeded maxLogBytes.	No	Narrow the list or advance the progressive log offset with a smaller chunk.
INVALID_PROVIDER_RESPONSE	Expected job/build/queue/node structure or identity is missing.	No	Confirm Jenkins and plugin compatibility before continuing.

Example

Trigger an approved release build after a ValkyrAI workflow has validated its artifact and change window:

{
  "operation": "trigger_build",
  "jobPath": "release/api-production",
  "parameters": {
    "VERSION": "2.4.1",
    "DEPLOY": true,
    "CHANGE_TICKET": "CHG-1842"
  }
}

Expected result:

{
  "status": "success",
  "operation": "trigger_build",
  "attempts": 1,
  "httpStatus": 201,
  "queueId": 812,
  "data": {
    "accepted": true,
    "queueId": 812
  }
}

Use get_queue_item with queueId: 812, then get_build and get_build_log after Jenkins assigns a build number.

Notes

• Pagination: list_jobs and list_builds use Jenkins tree slicing in pages of at most 100 plus one lookahead item. limit/offset continuation is bounded at 10,000 results. Queue and node arrays are capped locally.
• Rate limits and retries: GET operations retry HTTP 408, 429, 500, 502, 503, and 504 according to RetryPolicy and Retry-After. Build triggers, stops, and queue cancellation never retry automatically.
• API limits: JSON responses are capped at 5 MiB, build parameter maps at 256 KiB and 100 scalar values, paths at ten bounded segments, and console chunks at 1 MiB.
• Idempotency: a build trigger is not idempotent. Capture the returned queue ID and reconcile queue/build state before repeating any trigger after an ambiguous timeout. Stop and cancel are also single-attempt.
• Destructive behavior: stop_build interrupts a running build and cancel_queue_item removes queued work. Each requires a separate explicit confirmation. Controller restart, shutdown, quiet-down, job creation/copy/deletion, and arbitrary configuration mutation are not exposed.
• API behavior: Jenkins instances and plugins can customize authorization, queueing, tree fields, context paths, build retention, and redirect responses. Reverse proxies must preserve API-token authentication and Jenkins headers.
• Security: the origin is bound to IntegrationAccount.accountId; it is not workflow input. Production requires HTTPS. API tokens avoid CSRF crumbs while Jenkins CSRF protection remains enabled. Log output is classified confidential and redacted, but Jenkins-side credentials masking remains essential.
• External verification: authentication, request construction, folder encoding, tree bounds, progressive logs, retries, mutation single-attempt behavior, destructive guards, redaction, response identity, and metadata discovery have deterministic local tests. A live Jenkins instance and authorized token are not available in repository tests.
• Deferred operations: job create/copy/delete/config XML, views, credentials, plugins, scripts, artifacts, test reports, SCM polling, quiet-down, restart/shutdown, webhook triggers, OAuth, and arbitrary raw requests.
• Functional references: n8n Jenkins node source, Jenkins Remote Access API, Jenkins scripted-client authentication, and Jenkins CSRF protection.