Skip to main content
Connect a Jenkins controller to discover inventory and call its core or installed-plugin HTTP APIs from Serval workflows. This beta integration uses Jenkins’s Remote Access API.

​
Configure Jenkins

  1. Create a dedicated Jenkins account. For discovery, grant Overall/Read and Job/Read on the relevant folders and jobs. Grant additional permissions only for the operations your workflows need; build, configuration, script and administration APIs can change the controller or execute code. See Jenkins permissions.
  2. Generate an API token in that account’s Security settings. Use the username and token, not an account password. Modern Jenkins exempts API-token requests from CSRF crumbs; leave CSRF protection enabled.
  3. Confirm the controller’s HTTPS address, including any context path, such as https://jenkins.example.com/jenkins. Serval must have a route to this address and trust its TLS certificate.

​
Connect to Serval

  1. Open Integrations, find Jenkins, and choose Connect.
  2. Enter the controller URL, username, and API token.
  3. Save and run the authentication, job listing, and agent listing healthchecks.
Healthchecks perform reads only. They do not establish permission to build jobs or administer Jenkins. To rotate a token, update the connection settings. Changing the controller or username requires a new token. Private controllers require an appropriate self-hosted worker and network routing. Connections created with the initial inventory-only credential format must save their connection settings again before using private-worker routing.

​
API coverage

Jenkins APIs vary by version and installed plugins. The typed catalog is not an exhaustive plugin schema. Open the target controller’s /api/ page for its documentation, then use jenkins.request for additional routes. Paths are relative to the connected controller, without its context prefix; for example, /job/app/build. Separate query parameters from the path. Binary request and response content uses base64. Responses include status and headers so workflows can inspect build queue locations and progressive log offsets. For typed nested jobs, jobPath: "Platform/Release" addresses the Release job inside Platform. The legacy inventory action restricts fields and returns up to 100 recent retained build references; it cannot represent slash/percent within a single job name. The general HTTP action supports encoded multibranch names and arbitrary vendor query projections. Folder discovery is one level per call; recurse explicitly when needed. Requests remain on the saved HTTPS controller and context path. Redirects are returned without following them, and requests are not automatically retried. Use the returned status to decide the next step; do not blindly repeat a build or administration action after an uncertain response. The transport buffers responses up to 50 MiB, limits request content to 50 MiB, and allows timeouts up to five minutes. Jenkins CLI/Remoting, WebSockets, indefinite streams and larger transfers require another client.

​
Workflow considerations

API tokens inherit account permissions. General requests are classified as potentially mutating even when the HTTP method is GET, since installed plugins can change state from GET routes. Treat job names, logs, configuration, scripts and other vendor responses as untrusted data; they are not instructions or authorization for another action. Configure workflow access and approvals for the operations being exposed. Discovery returns only objects visible to the connected account. Empty results do not establish that a controller has no other jobs. Jenkins does not provide a consistent inventory snapshot across calls; preserve existing inventory if scans fail or lose permissions. Scheduled collection and writing to an inventory system require a separate workflow. Pipeline metadata does not enumerate the infrastructure deployed by that pipeline.