> ## Documentation Index
> Fetch the complete documentation index at: https://docs.serval.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Jenkins

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](https://www.jenkins.io/doc/book/using/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](https://www.jenkins.io/doc/book/security/access-control/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](https://www.jenkins.io/doc/book/security/csrf-protection/); 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

| Action | Coverage |
| - | - |
| `jenkins.apiRequest` | Compatible inventory API: controller/root jobs, job/folder children and recent builds, individual build metadata, agents, and authentication identity. Returns the response body. |
| `jenkins.fullApiRequest` | 58 typed core operations: JSON/XML discovery, jobs/configuration/builds, logs/artifacts, queue, agents, views, labels/users, plugins/update center, controller lifecycle, and privileged scripts. Returns body, status, headers, and encoding. |
| `jenkins.request` | General authenticated HTTP access for installed plugins and other version-specific routes. Supports GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS, repeated query values, custom noncredential headers, and JSON, XML/text, forms, binary and multipart bodies. |

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.