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

# Jenkins

> Connect a self-managed Jenkins controller to Oleria to discover its users, roles, permissions, and administrators, and manage role membership.

Connect Jenkins to Oleria to see who can do what on a Jenkins controller: which users hold Overall/Administer, which roles and permissions each user and group has, and who signs in. Oleria reads this from the Jenkins remote access API and from the authorization plugin the controller uses.

This integration is for self-managed Jenkins controllers. One Oleria connection maps one controller. Connect additional controllers as separate instances.

## What Oleria discovers

Once connected, Oleria continuously discovers and maps the following from the controller:

* **Users** - accounts in Jenkins' own user database, users who have signed in through the controller's security realm (for example LDAP or SAML), and any user named in a role or permission. Records Jenkins creates only for commit authors are skipped.
* **Roles** - with the **Role-based Authorization Strategy** plugin: global, project, and agent roles, including each role's permissions and, for project and agent roles, its name pattern.
* **Permissions** - with **Matrix-based security** or **Project-based Matrix Authorization**: each global permission granted on the controller (for example Overall/Administer) appears as a role, with the users and groups that hold it.
* **Groups** - groups named in a role or permission, and the built-in **authenticated** group (every signed-in user).
* **Role and permission membership** - which users and groups hold each role or permission.
* **Administrators** - users who hold Overall/Administer, directly, through the **authenticated** group, or through **anonymous** (Jenkins applies permissions granted to Anonymous to every user).

Jobs, folders, views, build agents, credentials, builds, and per-job permissions are not synced.

<Note>
  What Oleria can read depends on the controller's authorization strategy. Oleria detects it at every sync:

  | Authorization strategy | What Oleria gets |
  | :- | :- |
  | Role-based Authorization Strategy | Users, roles, membership, and the remediation actions below. |
  | Matrix-based security or Project-based Matrix Authorization | Users and global permissions, read-only. Requires the **Configuration as Code** plugin, which is the only way Jenkins exposes the global permission matrix. Without it, Oleria syncs users only. |
  | Logged-in users can do anything | Users, all shown as administrators. |
  | Anyone can do anything, or security disabled | Users, all shown as administrators. Oleria connects with a warning, because every request is anonymous. |
  | Any other strategy | Users only. |
</Note>

## Prerequisites

* A Jenkins controller reachable over **HTTPS from the internet** at a public address. Controllers that are only reachable on a private network or VPN, or whose address resolves to a private IP, can't be connected.
* A Jenkins user with **Overall/Administer**. Oleria refuses to connect with a user that isn't an administrator, because Jenkins only shows user details and the authorization configuration to administrators. (If security is disabled on the controller, the user isn't checked.)
* On Jenkins 2.452 and later, the **People View** plugin, which provides the user list. Without it, Oleria connects but syncs only users who are named in a role or permission.

<Note>
  Use a dedicated Jenkins user for this integration rather than a person's account. Oleria never removes the connection's own user from a role that grants Overall/Administer.
</Note>

## Create an API token in Jenkins

<Steps>
  <Step title="Sign in as the integration user">
    Sign in to Jenkins as the administrator user that Oleria will use.
  </Step>

  <Step title="Generate the token">
    Select your user name in the top-right corner, then select **Security** (**Configure** on older Jenkins versions). Under **API Token**, select **Add new Token**, give it a name such as "Oleria", and select **Generate**. Copy the token: Jenkins shows it only once.
  </Step>
</Steps>

<Note>
  Use an API token, not the user's password. Jenkins requires a token for API clients that change role membership.
</Note>

## Connect Jenkins to Oleria

<Steps>
  <Step title="Open the integration">
    Go to your Oleria workspace, select **Integrations** -> select **Jenkins**.
  </Step>

  <Step title="Complete the connection form">
    | Field | Notes |
    | :- | :- |
    | Jenkins URL | Required. The HTTPS address of the controller, including any context path, for example `https://ci.example.com` or `https://ci.example.com/jenkins`. Use the controller's final address: Oleria doesn't follow redirects, because each request carries the API token. You can't change the URL after the integration is saved. |
    | Username | Required. The Jenkins user ID of the administrator the API token belongs to. |
    | API token | Required. The token you generated. When you edit the integration later, leave it blank to keep the stored token. |
  </Step>

  <Step title="Authenticate">
    Select **Authenticate** to validate and save the integration. Oleria signs in with the token, checks that the user is an administrator, and detects the authorization strategy before saving.
  </Step>
</Steps>

## Verify the integration

Confirm the Jenkins instance appears on the **Connected** tab of your Oleria **Integrations** page. After the first sync completes, review the discovered users, roles, and administrators in your Oleria workspace.

## Remediation actions

On controllers that use the Role-based Authorization Strategy plugin, Oleria can take the following actions:

| Action | What it does | Revert |
| :- | :- | :- |
| Add user to role | Assigns the role to the user. If the user already holds the role, nothing changes. | Supported - removes the assignment Oleria added. |
| Remove user from role | Removes the user's own assignment of the role. If the user has no assignment of their own and nothing else grants the role, nothing changes. | Supported - assigns the role back. |

Oleria confirms each change by reading the role back. If Jenkins doesn't answer clearly, the action reports that the outcome is unknown so you can check the role in Jenkins.

<Note>
  Oleria refuses to remove a user from a role when:

  * the user is the integration's own Jenkins user and the role grants Overall/Administer
  * the removal would leave no user with Overall/Administer through a role
  * the user holds the role only through a group, such as **authenticated**, **anonymous**, or a group from your security realm. Remove the user from the group, or remove the role from the group, in Jenkins or in your directory.
  * the role is also granted to **authenticated** or **anonymous**, so removing the user's own assignment wouldn't revoke it. Remove the role from that group in Jenkins first.

  If the role is also granted to groups from your security realm, Oleria removes the user's own assignment and warns that the user may still hold the role through one of those groups.

  Roles can't be changed on controllers that use matrix-based security.
</Note>

## Known limitations

* **Users who never signed in may be missing.** With an external security realm such as LDAP, SAML, or OIDC, Jenkins only knows users who have signed in or are named in a role. Connect your identity provider to Oleria to see everyone.
* **Group membership isn't synced.** Oleria shows which groups hold a role, but Jenkins doesn't expose who is in a security-realm group. Users who hold Overall/Administer only through such a group aren't flagged as administrators.
* **Users can't be disabled.** Jenkins has no way to disable a user, and deleting a user can't be undone, so Oleria offers neither.
* **No activity or last sign-in.** Jenkins doesn't expose an audit log or users' last sign-in time through its API.
* **MFA isn't shown.** Multi-factor authentication is handled by the security realm, not by Jenkins.
* **Per-job permissions aren't synced.** Project roles show their name pattern, but Oleria doesn't list which jobs each pattern matches.

## Contact us

For questions about this integration, contact us at [support@oleria.com](mailto:support@oleria.com).


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