Integrations

An integration in a CloudBees platform organization provides a standard interface connecting two or more systems. You can use integrations to facilitate communication and data exchange between different applications, resources, or services.

The following types of integrations are available:

Continuous integration (CI) tool types
- CloudBees CI controller
- Jenkins®
- operations center
Project management type
- Jira
Source code management (SCM) types
- Bitbucket access token
- GitHub App

To complete integration setup or testing, the CloudBees platform may redirect you to your external provider.

Access an integration

Access the integrations that are key to connecting your repositories, CI tools, and project issues. To access an integration:

Select Configurations Integrations.
(Optional) Search for a specific integration, by entering all or part of an integration name into Search.
(Optional) Select an option in Sort by to sort the integration list by either ASCENDING or DESCENDING alphanumerical sort order.

The integrations are displayed according to your search or sort criteria.

Create a CI tools integration

Connect the platform to your CloudBees CI and Jenkins instances. Once you have created this integration, data is available in the CI insights for Jenkins dashboard.

To create a CI tool integration:

Select Configurations Integrations.
Select CREATE INTEGRATION.
Select CI tools, and then select one of the options.
Enter a Name and an (optional) Description.
Configure in Jenkins, as follows:
- For CloudBees CI controller and operations center:
  1. Go to Manage Jenkins Plugins Available Plugins.
  2. Search for CloudBees Platform Insights Plugin and then install it.
  3. Go to Manage Jenkins System, and search for CloudBees Platform Insights.
  4. Enter the authentication code from the CloudBees platform.
  5. Save the Jenkins configuration.
- For Jenkins:
  1. Go to Manage Jenkins Plugins Available Plugins.
  2. Search for CloudBees Installation Plugin and then install it.
  3. Search for CloudBees Platform Insights Plugin and then install it.
    
    Figure 1. CloudBees integration plugins in Jenkins.
  4. Go to Manage Jenkins System, and search for CloudBees Platform Insights.
  5. Enter the authentication code from the CloudBees platform.
    
    Figure 2. Platform authentication code for a Jenkins integration.
    
    Figure 3. Pasted authentication code in Jenkins system configuration.
  6. Save the Jenkins configuration.
Select SUBMIT to save the integration in the platform.

For CloudBees CI controllers and the operations center, the CloudBees Platform Insights Plugin requires CloudBees CI 2.440.3.7 or later.
For Jenkins, CloudBees Platform Insights Plugin requires Jenkins 2.414.3 or later.

The CI tools integration is connected and listed in Integrations.

Create a project management integration

Create a project management integration to connect your Atlassian Jira tasks to the platform.

Create an Atlassian personal access token to set up the connection to your Jira account.

To create a Jira integration:

Select Configurations Integrations.
Select CREATE INTEGRATION.
Select Project management.
Select Jira.
Enter a Name and an (optional) Description.
Enter the URL.
Enter the Username.
Enter the Personal access token.
Select SUBMIT.

The Jira integration is connected and listed in Integrations.

Figure 4. Setting up a Jira connection.

Create an SCM integration

Create an SCM integration to connect your repository. Connect to Bitbucket with an access token, or to GitHub by installing a GitHub App.

To create an SCM integration:

Select Configurations Integrations.
Select CREATE INTEGRATION.
Select Source code management.

Select one of the following options.

For Bitbucket access token:
1. Enter a Name, an (optional) Description, and your Token.
  
  Figure 5. An example Bitbucket access token with the appropriate permissions.
  The CloudBees platform only requires the following scopes from Bitbucket:
  
  Repositories: Read and write
  
  Pull requests: Read and write
  
  Webhooks: Read and write
2. (Optional) Select TEST INTEGRATION.
3. Select SUBMIT.
  
  Figure 6. Successfully connected Bitbucket integration, with TEST INTEGRATION highlighted.

For GitHub App:

(Optional) Enter a Description.
Select INSTALL GITHUB APP. This action redirects you to GitHub.

Select a GitHub account or GitHub organization to connect.

You only can set up a single platform integration with a given GitHub account or organization. GitHub accounts and organizations are displayed in GitHub as follows:

With a white background (no Configure): Available to connect to the platform.
With a light gray background and Configure: At least one repository is already connected to the platform.

The integration name is automatically generated based on the GitHub organization name.

Figure 7. GitHub App installation with available GitHub organization highlighted

Install and authorize All repositories, or Only select repositories, and select from the options.
Select Install & Authorize.

The integration is connected and listed in Integrations.

Update an integration

To connect a repository that is in a GitHub account or organization that is already connected, configure the connected repositories in GitHub.

From your CloudBees integration list, make updates to any integrations.

To update an integration:

Select Configurations Integrations.
Select the next to the integration you want to update.
Select Edit integration.
Make any desired changes.
(Optional) Select TEST INTEGRATION.
Select SAVE.

The selected integration is updated accordingly.

Delete an integration

Delete any of your integrations. A deleted integration is completely removed from the CloudBees platform, and deletion is irreversible.

To delete an integration:

Select Configurations Integrations.
Select the next to the integration you want to delete.
Select Delete integration.
Select DELETE.

The selected integration is deleted and removed from the integration list.