Connect CI and Jenkins controllers

Connect CloudBees CI or Jenkins® controllers to CloudBees Unify to visualize CI jobs and builds, analyze test results and artifacts, and orchestrate software releases within a unified interface. Choose between single controller integration for targeted connections or operations center integration to automatically connect multiple controllers at once.

Each controller or operations center can only be integrated with one CloudBees Unify organization at a time. Before creating a new integration, verify that your controller or operations center is not already integrated with another CloudBees Unify organization.

Before you begin, ensure you have administrator access to CloudBees Unify and your controller or operations center. You must also install the required plugins on your controller or operations center (refer to Install required plugins), create an SCM integration between the Multibranch Pipeline or Organization Folder repository and CloudBees Unify, and create a component for that repository.

Choose your integration approach

CloudBees Unify offers two integration approaches depending on your CI infrastructure and requirements.

Single controller integration: Connect individual CloudBees CI or Jenkins controllers one at a time. Use this approach when:

You are using Jenkins.
You have a small number of controllers.
You want to selectively integrate specific controllers.
You need granular control over each controller connection.

Connect a single controller using:

Approval (recommended)
PEM file
CasC

Operations center integration: Automatically discover and connect all controllers managed by your CloudBees CI operations center. Use this approach when:

You are using CloudBees CI with an operations center.
You have multiple controllers under operations center management.
You want to automatically integrate all controllers at once.
You prefer centralized management of controller connections.

Connect via the operations center using:

Approval (recommended)
PEM file
CasC

System requirements and limitations

The following requirements and limitations apply to CloudBees CI and Jenkins integration with CloudBees Unify. For complete technical specifications, refer to System requirements and Integration limits and constraints.

Only Multibranch Pipeline or Organization Folder project types are supported. Other project types are not supported.
Only GitHub, Bitbucket, or GitLab branch sources are supported for Multibranch Pipelines and Organization Folders. Other SCM providers are not supported at this time.
If a Multibranch Pipeline or Organization Folder contains more than one repository, only the first detected SCM repository is used by CloudBees Unify.
Only CI jobs and builds executed after integrating with CloudBees Unify are displayed.

Install required plugins

Install the CloudBees Unify Integration :: Controllers plugin on each controller before connecting it to CloudBees Unify. For operations center integrations, also install the CloudBees Unify Integration :: OC plugin on the operations center. For version requirements and the full plugin list, refer to continuous-integration:reference/ci-jenkins-integration-reference.adoc#required-plugins.

Install via the CloudBees CI UI

From the controller or operations center dashboard, select in the upper-right corner to navigate to the Manage Jenkins page.
Select Plugins, and then select Available plugins.
Search for the plugin name.
Select the checkbox next to the plugin.
Select Install in the upper-right corner.

Install via CasC

CasC installation is supported on CloudBees CI controllers and operations center only. Jenkins controllers must use the UI method.

Add the following to your plugins.yaml bundle file:

For a controller:

plugins:
  - id: "cloudbees-cbp-unify-integration"▼

For an operations center:

plugins:
  - id: "cloudbees-cbp-unify-integration-oc"▼

Apply the CasC bundle to your controller or operations center.

Integrate a single controller in CloudBees CI or Jenkins

Use the single controller integration to connect an individual CloudBees CI or Jenkins controller to CloudBees Unify.

If your deployment uses a custom CloudBees Unify endpoint, you can configure it directly from the CloudBees CI UI or CasC bundle.

Connect a single controller with approval (recommended)

Authenticate your controller connection through direct approval in CloudBees CI for the most secure integration method.

Select an organization, and then select Configurations Integrations.
Select Create integration. The list of available integrations displays.
Select , and then select Category Continuous integration.
Select CloudBees CI controller or Jenkins® controller from the list of available integration types.

Both CloudBees CI controller and Jenkins® controller appear in multiple categories. Be sure to select from the Continuous integration category for this integration.
Enter the Name and optional Description.
Enter the Controller URL.

The Controller URL cannot be edited after the integration is saved.

Always use HTTPS for controller URLs. HTTP transmits credentials and key material unencrypted, exposing them to interception. Refer to HTTPS requirements for URLs for more information.
Select Approve in Controller to authenticate via the controller.
Select Create & continue. The integration status displays Action pending in Controller.
Select Go to Controller to approve the connection in the controller.
Verify the details displayed in the controller and select Confirm to approve the connection.
Navigate back to CloudBees Unify. The integration status changes to Connected after the connection is successfully established.
Select Save and close.
After you have connected successfully, monitor your CloudBees CI or Jenkins Pipelines through CloudBees Unify.

When you approve the connection, CloudBees Unify creates a public and private key pair and installs the private key into the controller, which creates a Jenkins credential. This allows the controller to send data to CloudBees Unify.

Connect a single controller with PEM file

Configure your controller connection using a PEM file when direct approval is not available or when you need to automate the setup process.

Select an organization, and then select Configurations Integrations.
Select Create integration.
Select , and then select Category Continuous integration.
Select CloudBees CI controller or Jenkins® controller from the list of available integration types.

Both CloudBees CI controller and Jenkins® controller appear in multiple categories. Be sure to select from the Continuous integration category for this integration.
Enter the Name and optional Description.
Enter the Controller URL.

The Controller URL cannot be edited after the integration is saved.

Always use HTTPS for controller URLs. HTTP transmits credentials and key material unencrypted, exposing them to interception. Refer to HTTPS requirements for URLs for more information.
Select Set up with PEM File, and then select Create & continue.
Select Download to download the generated PEM file containing the private key.

Save the PEM file in a secure location. You cannot regenerate or download this file again.

Select the Controller link to navigate to your controller to add the private key.

To manually navigate to the CloudBees Unify configuration page, from the controller dashboard select in the upper-right corner, and then select CloudBees Unify. .. Next to the Private key field, select +Add, and then select Global. .. In the Add Credentials dialog, select Secret text, and then select Next. .. Paste your private key into the Secret field, and then select Create. .. Select Add. .. Select the new Secret text credential from the Private key dropdown. .. On the CloudBees Unify configuration page, select Save.

In CloudBees Unify, check the integration status; it may take a few minutes to transition from Action pending in Controller to Connected.
After you have connected successfully, monitor your CloudBees CI or Jenkins Pipelines through CloudBees Unify.

Connect a single controller with CasC

CasC configuration is supported on CloudBees CI controllers only. Jenkins controllers must use the approval or PEM file method.

Configure your controller connection using Configuration as Code.

Select an organization, and then select Configurations Integrations.
Select Create integration.
Select , and then select Category Continuous integration.
Select CloudBees CI controller or Jenkins® controller from the list of available integration types.

Both CloudBees CI controller and Jenkins® controller appear in multiple categories. Be sure to select from the Continuous integration category for this integration.
Enter the Name and optional Description.
Enter the Controller URL.

The Controller URL cannot be edited after the integration is saved.

Always use HTTPS for controller URLs. HTTP transmits credentials and key material unencrypted, exposing them to interception. Refer to HTTPS requirements for URLs for more information.
Select Set up with PEM File, and then select Create & continue.
Select Download to download the generated PEM file containing the private key.

Save the PEM file in a secure location. You cannot regenerate or download this file again.

Add the following to jenkins.yaml in your controller CasC bundle, replacing secret-value with the private key from the PEM file:

credentials:
  system:
    domainCredentials:
      - credentials:
          - string:
              scope: GLOBAL
              id: "unify-cred-id"
              secret: "secret-value"
cbpConnectionConfiguration:
  cbpUrl: "https://api.cloudbees.io/"
  type:
    direct:
      credentialsId: "unify-cred-id"▼

The id value must match the credentialsId field. Replace cbpUrl if your deployment uses a custom endpoint.

Apply the CasC bundle to your controller.
In CloudBees Unify, check the integration status; it may take a few minutes to transition from Action pending in Controller to Connected.
Select Save and close.
After you have connected successfully, monitor your CloudBees CI Pipelines through CloudBees Unify.

Connect multiple controllers via the operations center

CloudBees Beta

This feature is available as a beta release and is subject to change without notice. CloudBees recommends stringent testing in a development environment and a complete review of the documentation and architecture before using it in production.

Integrate multiple controllers simultaneously by connecting your CloudBees CI operations center, which automatically discovers and connects all controllers.

Before creating the operations center integration, install the required plugins in both your operations center and all controllers. For installation instructions, refer to continuous-integration:reference/ci-jenkins-integration-reference.adoc#oc-plugin-requirements.

Connect the operations center with approval (recommended)

To create an operations center integration with approval:

Select an organization, and then select Configurations Integrations.
Select Create integration.
Select , and then select Category Continuous integration.
Select CloudBees CI Operations Center from the list.

CloudBees CI Operations Center appears in multiple categories. Ensure you select from the Continuous integration category.
Enter the Name and optional Description.
Enter the Operations Center URL.

The operations center URL cannot be edited after the integration is saved.

Always use HTTPS for operations center URLs. HTTP transmits credentials and key material unencrypted, exposing them to interception. Refer to HTTPS requirements for URLs for more information.
Select Approve in Operations Center to authenticate via the operations center.
Select Create & continue. The integration status displays Action pending in OC.
Select Go to Operations Center to approve the connection in the operations center.
Verify the details displayed in the operations center and select Confirm to approve the connection.
Navigate back to CloudBees Unify. The integration status transitions from Action pending in OC to Connected within a few minutes.
Select Save and close.
After you have connected successfully, monitor your CloudBees CI Pipelines through CloudBees Unify.

When you approve the connection, CloudBees Unify creates a public and private key pair and installs the private key into the operations center, which creates a Jenkins credential. This allows the operations center and controllers to send data to CloudBees Unify.

For monitoring individual controllers and troubleshooting, refer to Monitor CI and Jenkins builds.

Connect the operations center with PEM file

To create an operations center integration with a PEM file:

Select an organization, and then select Configurations Integrations.
Select Create integration.
Select , and then select Category Continuous integration.
Select CloudBees CI Operations Center from the list.
Enter the Name and optional Description.
Enter the Operations Center URL.

The Operations Center URL cannot be edited after the integration is saved.

Always use HTTPS for operations center URLs. HTTP transmits credentials and key material unencrypted, exposing them to interception. Refer to HTTPS requirements for URLs for more information.
Select Set up with PEM File, and then select Create & continue.
Select Download to download the generated PEM file.

Save the PEM file securely. You cannot regenerate this file.

Select Go to Operations Center to add the private key to your operations center.

To manually navigate to the CloudBees Unify configuration page, from the operations center dashboard select in the upper-right corner, and then select CloudBees Unify. .. Next to the Private key field, select +Add, and then select Global. .. In the Add Credentials dialog, select Secret text, and then select Next. .. Paste your private key into the Secret field, and then select Create. .. Select Add. .. Select the new Secret text credential from the Private key dropdown. .. On the CloudBees Unify configuration page, select Save.

Go back to CloudBees Unify, and then select Next.
Select Copy to copy the registration key (ID) displayed in CloudBees Unify.

Select Go to Operations Center to add the registration ID to your operations center.

In CloudBees Unify, check the integration status; it may take a few minutes to transition from Action pending in OC to Connected.
Select Save and close.
After the integration is connected successfully, you can monitor controller status.

For monitoring individual controllers and troubleshooting, refer to Monitor CI and Jenkins builds.

Connect the operations center with CasC

Select an organization, and then select Configurations Integrations.
Select Create integration.
Select , and then select Category Continuous integration.
Select CloudBees CI Operations Center from the list.
Enter the Name and optional Description.
Enter the Operations Center URL.

The Operations Center URL cannot be edited after the integration is saved.

Always use HTTPS for operations center URLs. HTTP transmits credentials and key material unencrypted, exposing them to interception. Refer to HTTPS requirements for URLs for more information.
Select Set up with PEM File, and then select Create & continue.
Select Download to download the generated PEM file.

Save the PEM file securely. You cannot regenerate this file.
Go back to CloudBees Unify, and then select Next.
Copy the registration key (ID) displayed in CloudBees Unify.

Add the following to jenkins.yaml in your operations center CasC bundle, replacing secret-value with the private key from the PEM file and clusterId with the registration key copied from CloudBees Unify:

credentials:
  system:
    domainCredentials:
      - credentials:
          - string:
              scope: GLOBAL
              id: "unify-cred-id"
              secret: "secret-value"
cbpConnectionConfiguration:
  cbpUrl: "https://api.cloudbees.io/"
  type:
    direct:
      credentialsId: "unify-cred-id"
      clusterId: "12345678-90ab-cdef-1234-567890abcdef"▼

The id value must match the credentialsId field. Replace cbpUrl if your deployment uses a custom endpoint.

Apply the CasC bundle to your operations center.
In CloudBees Unify, check the integration status; it may take a few minutes to transition from Action pending in OC to Connected.
Select Save and close.
After you have connected successfully, monitor your CloudBees CI Pipelines through CloudBees Unify.

Opt specific controllers out of operations center integration

By default, operations center integration automatically discovers and connects all controllers. You can opt individual controllers out of the integration.

If you opt out a controller after the integration is already established, manually sync the operations center to reflect the change in CloudBees Unify.

Opt out via the CloudBees CI UI

From the operations center dashboard, select the controller you want to opt out.
Select Configure in the left pane.
Scroll down to CloudBees Unify configuration.
Select Opt out of auto configuration.
Select Save.

Opt out via CasC

Add the opt-out property to the operations center bundle’s items.yaml:

items:
  - kind: managedController
    name: my-controller
    properties:
      - cbpOptOut:
          optOut: true▼

Set optOut: true to exclude a controller from integration, or false to include it.

(Optional) Manually sync your controller configuration data with CloudBees Unify

Manually sync your existing controller configuration data to CloudBees Unify. An automatic sync occurs every 24 hours, independent of any manual sync.

To manually sync your controller data:

From the controller or operations center dashboard, select in the upper-right corner to navigate to the Manage Jenkins page.
Select CloudBees Unify to navigate to the CloudBees Unify configuration page.
On the CloudBees Unify Connection tab, under CloudBees Unify Data Synchronization, select Start sync or Resync Now.

The Sync controller configuration data status updates to:
- Sync in progress: The synchronization is currently in progress.
- Synced: The sync completed successfully. Once synced, a confirmation message and the sync timestamp are displayed.

(Optional) Monitor job configuration reconciliation

For single controller integrations, job configuration reconciliation maps every Multibranch Pipeline job on the controller to a CloudBees Unify workflow, and every job’s repository to a CloudBees Unify component.

To view job configuration reconciliation results:

From the controller dashboard, select in the upper-right corner to navigate to the Manage Jenkins page.
Select CloudBees Unify.
Select the Last Job Reconciliation tab.
- If the controller integration is not configured, you must first complete the controller integration setup in CloudBees Unify.
- If no reconciliation has been performed yet, select Start sync on the CloudBees Unify Connection tab to trigger reconciliation.
- When reconciliation has been performed, the reconciliation details (timestamp, triggered by, request ID, total jobs sent, and response status) and the jobs sent to CloudBees Unify with their associated SCM repositories are displayed.

(Optional) Monitor controller registration reconciliation

For operations center integrations, the operations center automatically attempts to preregister all connected controllers with CloudBees Unify. If a controller fails to preregister, the reason for the failure is displayed.

To verify controller preregistration status in the operations center:

From the operations center dashboard, select in the upper-right corner to navigate to the Manage Jenkins page.
Select CloudBees Unify to navigate to the CloudBees Unify configuration page.
Select the Controller Registration Reconciliation tab.
- Preregistered: The controller has been successfully preregistered with CloudBees Unify.
- Not Preregistered: The controller has not been preregistered, or it has been opted out from the integration.
- Failed: The preregistration failed. The Error cause displays the reason for the failure.

Verify and manage connections

After creating your integration, verify the connection and monitor synchronization status.

Check integration status

Integration status indicates the connection state between CloudBees Unify and your controllers or operations center.

Table 1. Integration status definitions
Status	Applies to	Definition
Action pending in controller	Single controller	Integration initiated in CloudBees Unify, but approval or authentication is pending on the controller side.
Action pending in OC	Operations center	Integration initiated in CloudBees Unify, but approval or authentication is pending on the operations center side.
Waiting for connection	Controllers (via operations center integration)	Controllers are pre-registered via the operations center integration and in the process of connecting to CloudBees Unify.
Connected	Single controller	Controller successfully connected with CloudBees Unify and can send data.
Connected	Operations center	Operations center successfully connected with CloudBees Unify. Controller synchronization occurs in the background and can be tracked in the View controllers screen.

To verify your integration is working correctly:

Navigate to Configurations Integrations.
Locate your CI integration in the list.
Verify the status shows Connected.

Initial synchronization may take several minutes depending on the number of pipelines and build history.

View connected controllers

For operations center integrations, view the status of individual controllers:

Navigate to Configurations Integrations.
Select your operations center integration.
Select the Controllers tab to view all discovered controllers.
Review the connection status and last sync time for each controller.

Update integration settings

To modify an existing integration:

Navigate to Configurations Integrations.
Select the integration you want to update.
Select Edit to modify the name or description.

You cannot change the controller or operations center URL after creation. To use a different URL, delete the integration and create a new one.

Remove an integration

To disconnect a controller or operations center:

Navigate to Configurations Integrations.
Select the integration you want to remove.
Select Delete.
Confirm the deletion when prompted.

Deleting an integration removes all synchronized data from CloudBees Unify, including build history and test results. This action cannot be undone.

HTTPS requirements for URLs

Always use HTTPS for controller and operations center URLs. For protocol requirements and security protections, refer to continuous-integration:reference/ci-jenkins-integration-reference.adoc#https-requirements.

Reset a connection

Use the reset feature to update a connection or if your connection fails.

In CloudBees Unify, navigate to Configurations Integrations.
Locate the controller or operations center integration record.
Select for the controller or operations center record, and then select Edit integration.
Select Reset connection.
When prompted, select Reset connection again to confirm.
Select Reset & continue.

A Connection reset successfully message is displayed, and the integration status transitions as follows:
- Single controller integration: Action pending in Controller
- Operations center integration: Action pending in OC
  
  If you close your browser before confirming, the integration status remains unchanged.
After confirming, select Go to Controller or Go to Operations Center to re-authenticate the connection in the controller or operations center.
Verify the details displayed in the controller or operations center and select Confirm to approve the connection.
Navigate back to CloudBees Unify.

The integration status changes to Connected after the connection is successfully re-established.
Select Save and close.

Troubleshoot integration problems

If you encounter problems connecting your CloudBees CI or Jenkins to CloudBees Unify, use this guidance to identify the cause and resolve the issue.

Error: This name already exists in your organization hierarchy

The integration name matches an existing integration name in your current organization. Update the integration name to be unique.

Error: This controller URL already exists in your organization hierarchy

The controller URL matches an existing integrated controller. You must enter a controller URL that is unique before you can save the integration.

The integration cannot be updated or deleted

The integration is inherited by your current organization. Navigate to the organization where the integration was created to update or delete it.

The integration status remains Action pending in controller

The integration has been created, but the access key has not been updated. After redirecting to the controller, you must confirm access before closing the window.

The integration status remains Action pending in OC

The integration has been created, but the access key has not been updated. After redirecting to the operations center, you must confirm access before closing the window.

An operations center is already integrated with a different CloudBees Unify organization

Each operations center can only be integrated with one CloudBees Unify organization at a time. Only the most recent integration receives data. Verify no existing integration exists before creating a new one, or delete the existing integration first.

A controller remains in Waiting for connection status for an extended period

The controller may be hibernating, offline, or missing the required plugin. Verify the following:

The controller is up and running and not hibernated.
The CloudBees Unify Integration :: Controllers plugin plugin is installed on the controller.

If the plugin is not installed, install it and allow up to one hour for connection, or restart the controller to speed up detection.

Last data received shows No data sent even though the controller status is Connected

The Last data received field displays the latest timestamp of when CloudBees Unify received job data from the controller. If the controller has no Multibranch Pipeline jobs configured, this field shows No data sent even when connected.

Opted out controllers still appear in the View controllers table, or their status has not updated

If you opted out controllers after the operations center integration was already established, manually sync the changes to CloudBees Unify. Refer to (Optional) Manually sync your controller configuration data with CloudBees Unify.

A controller went offline, was shut down, or was hibernated after the operations center integration was established, but the status still shows Connected

Manually sync the changes to CloudBees Unify from your operations center. Refer to (Optional) Manually sync your controller configuration data with CloudBees Unify.

Missing builds or pipelines

Verify the CloudBees Unify Integration :: Controllers plugin plugin is installed on the controller. Check controller logs for synchronization errors. Ensure network connectivity between the controller and CloudBees Unify.

Test results not appearing

Confirm the JUnit plugin plugin is installed and active. Verify test result files are in JUnit XML format. Check that the junit step path pattern matches your test files.

Security scans not published

Verify the scan report format is SARIF or JSON. Check that the scanner parameter is specified for non-SARIF formats. Confirm the scan report file exists at the specified path.

Artifacts not registered

Verify all required parameters are provided to registerBuildArtifactMetadata. Check that the artifact URL is accessible. Confirm the build has appropriate permissions.

Connect CI and Jenkins controllers

Choose your integration approach

System requirements and limitations

Install required plugins

Install via the CloudBees CI UI

Install via CasC

Integrate a single controller in CloudBees CI or Jenkins

Connect a single controller with approval (recommended)

Connect a single controller with PEM file

Connect a single controller with CasC

Connect multiple controllers via the operations center

Connect the operations center with approval (recommended)

Connect the operations center with PEM file

Connect the operations center with CasC

Opt specific controllers out of operations center integration

Opt out via the CloudBees CI UI

Opt out via CasC

(Optional) Manually sync your controller configuration data with CloudBees Unify

(Optional) Monitor job configuration reconciliation

(Optional) Monitor controller registration reconciliation

Verify and manage connections

Check integration status

View connected controllers

Update integration settings

Remove an integration

HTTPS requirements for URLs

Reset a connection

Troubleshoot integration problems

Related pages