Continuous integration (CI) configuration

Integrate CloudBees CI or Jenkins® with CloudBees Unify to visualize CI jobs and builds, analyze test results and artifacts, and orchestrate software releases. You can integrate single controllers or a CloudBees CI operations center to automatically connect multiple controllers at once.

To learn more about working with CloudBees CI or Jenkins in CloudBees Unify, including technical requirements and limitations, refer to Integrate a single controller with CloudBees Unify or Integrate multiple controllers with the CloudBees CI operations center.

Before proceeding with the integration, you must install the required plugins. For instructions, refer to:

Choose your integration type

Select the integration type that matches your CI environment:

Integrate a single controller in CloudBees CI or Jenkins: Connect a single CloudBees CI or Jenkins controller.
Integrate multiple controllers with the CloudBees CI operations center: Connect all controllers managed by your CloudBees CI 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. To create a single controller integration, choose one of the following connection methods:

Approve in Controller (recommended): Approve the connection directly in the controller.
Set up with a PEM File: Download the private key and add it to the controller manually.

Approve in Controller

Both CloudBees CI and Jenkins can be integrated with the Approve in Controller method, which is the recommended approach. CloudBees Unify requests approval from the controller, and you approve the integration directly in the controller.

Create the integration

To create a single controller integration with approval in the controller:

Select an organization, and then select Configurations Integrations.
Select Create integration. The list of available integrations displays.
Select .
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.

Figure 1. Create a single controller integration
Select Create & continue. The integration status displays Action pending in Controller.

Figure 2. Approve connection 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.

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.

After you have connected successfully, monitor your CloudBees CI or Jenkins Pipelines through CloudBees Unify.

Set up with a PEM File

Both CloudBees CI and Jenkins can be integrated with the Set up with PEM File method. This method uses certificate-based authentication. You download a PEM file and configure the controller with the private key.

To create a single controller integration with a PEM file:

Select an organization, and then select Configurations Integrations.
Select Create integration. The list of available integrations displays.
Select .
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 this file securely. It contains your private key and cannot be retrieved later.
Select Controller to navigate to your controller in CloudBees CI or Jenkins.
Add the private key to your controller.
1. From the controller dashboard, select in the upper-right corner to navigate to the Manage Jenkins page.
2. Select System, and then scroll down to CloudBees Platform connection.
3. Next to the Private key field, select +Add, and then select Jenkins.
  
  Figure 3. Add a private key to the controller, with Add highlighted
4. From the Kind dropdown, select Secret text.
5. Paste your private key into the Secret field.
6. Select Add.
7. Select the new credential from the Private key dropdown.
8. In System, 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.

Integrate multiple controllers with the CloudBees CI operations center

CloudBees limited preview

This documentation describes features and functionality available only to customers in the CloudBees Limited Preview Program for early access and feedback. It is provided for informational purposes only and is subject to change without notice. While this feature is in limited preview, your experience may vary. 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 by connecting your CloudBees CI operations center, which automatically discovers and connects all controllers it manages.

Before creating the operations center integration, install the required plugins in your operations center and controllers. Refer to Install the required plugins to the OC and controllers for instructions.

To create an operations center integration, choose one of the following connection methods:

Approve in Operations Center (recommended): Approve the connection directly in the operations center.
Set up with a PEM File: Download the private key and add the credential to the operations center manually.

Approve in Operations Center

The Approve in Operations Center method is the recommended approach. CloudBees Unify requests approval from the operations center, and you approve the integration directly in the operations center.

To create an operations center integration with approval in the operations center:

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

CloudBees CI Operations Center appears in multiple categories. Be sure to select from the Continuous integration category for this integration.
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.

Figure 4. Create an operations center integration
Select Create & continue. The integration status displays Action pending in OC.

Figure 5. Approve connection in Operations center
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.
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 view and monitor controller status.

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.

After you have connected successfully, monitor your CloudBees CI Pipelines through CloudBees Unify.

For status definitions, refer to Understand the integration status. For monitoring individual controllers and troubleshooting, refer to View and monitor controller status.

Set up with a PEM File

The Set up with PEM File method uses certificate-based authentication. You download a PEM file and configure the operations center with the private key and registration ID.

To create an operations center integration with a PEM file:

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

CloudBees CI Operations Center appears in multiple categories. Be sure to select from the Continuous integration category for this integration.
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 containing the private key.

Save this file securely. It contains your private key and cannot be retrieved later.
Select Go to Operations Center to navigate to your operations center.
Add the private key to your operations center.
1. From the operations center dashboard, select in the upper-right corner to navigate to the Manage Jenkins page.
2. Select System, and then scroll down to CloudBees Platform connection.
3. Next to the Private key field, select +Add, and then select Jenkins.
  
  Figure 6. Add a private key to the operations center, with Add highlighted
4. From the Kind dropdown, select Secret text.
5. Paste your private key into the Secret field.
6. Select Add.
7. Select the new credential from the Private key dropdown.
8. In System, select Save.
Go back to CloudBees Unify, and then select Next.
Copy the registration key (ID) displayed in CloudBees Unify.
Select Go to Operations Center to navigate to your operations center.
Add the registration ID to your operations center.
1. From the operations center dashboard, select in the upper-right corner to navigate to the Manage Jenkins page.
2. Select System, and then scroll down to CloudBees Platform connection.
3. Paste the registration ID into the Registration Id field.
4. In System, select Save.
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 view and monitor controller status.

For status definitions, refer to Understand the integration status. For monitoring individual controllers and troubleshooting, refer to View and monitor controller status.

Understand the 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. The controller synchronization occurs in the background, and can be tracked independently in the View controllers screen.

Reset a connection

Use the reset feature to update a connection or if your connection fails. When you initiate a reset, you are prompted to confirm the action. After you confirm, the connection 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.

Troubleshoot connection issues

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

Table 2. Common connection issues and solutions
Issue	Probable cause	Solution
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 (for a single controller) or Action pending in OC (for multiple controllers connected via the operations center).	The integration has been created, but the `accessKey` has not been updated.	After redirecting to the controller or operations center, you must confirm access before closing the window.
A controller or operations center is already integrated to a CloudBees Unify organization. The same controller or operations center was integrated to a different CloudBees Unify organization, but it is not working correctly.	Each controller or operations center can only be integrated to one CloudBees Unify organization at a time. When you create a new integration in a different CloudBees Unify organization, it overrides the previous integration configuration.	Before creating a new integration, delete or reset the existing integration.

HTTPS requirements for URLs

To secure communication between CloudBees Unify and your operations center and controllers, always use HTTPS for your operations center or controller URL. HTTP transmits data in plain text, allowing anyone monitoring network traffic to intercept sensitive information, including authentication credentials, API keys, and private key material. This is particularly critical when integrating controllers, as the configuration process involves transferring:

Private keys (when using the PEM file setup).
Authentication tokens.
Organization and endpoint identifiers.
Job and build data.

HTTPS uses Transport Layer Security (TLS) to provide three essential security protections:

Confidentiality: Encrypts all data in transit, preventing eavesdropping on sensitive information.
Integrity: Protects against tampering or modification of requests and responses during transmission.
Authentication: Verifies you’re connecting to the legitimate controller, not an imposter or man-in-the-middle attacker.

HTTP connections should only be used in the following limited scenarios:

Local testing environments completely isolated from external networks.
Development environments where no production credentials or sensitive data are present.
Proof-of-concept demonstrations on localhost.

Production, staging, and any internet-accessible controller integrations must always use HTTPS to protect your organization’s security credentials and operational data.

For more information on TLS best practices and secure transport configuration, refer to the OWASP Transport Layer Security Cheat Sheet.