SCM integrations

Create an SCM integration to connect the CloudBees platform to Bitbucket or GitHub repositories in the cloud. With this integration in place, the platform can query the SCM for repositories and branches, configure webhooks to trigger workflows, and inject tokens that can be used to pull the source code when the workflow runs. This integration also allows us to perform security scans on your source code repositories.

Users who must manage code repositories behind their own firewall can integrate Bitbucket Data Center repositories with the platform. Connect to Bitbucket services with access tokens, or to GitHub by installing a GitHub App.

Table 1. SCM integration types available in the platform
SCM provider	Hosting	Integration type
Bitbucket	Cloud	Access token
Bitbucket Data Center	Self-hosted	Access token
GitHub	Cloud	GitHub App

Once you have a connected your source code to the platform, you can create a new component and set up a workflow.

For more information, refer to the following documentation:

GitHub

If you have a GitHub repository in the cloud, you can connect it to the platform.

GitHub App installation

The CloudBees platform requires that the integration to GitHub be made through the GitHub App registered by CloudBees.

To integrate your GitHub repository:

Select an organization, and then select Configurations Integrations.
Select Create integration.
Select Source code management.
Select GitHub App.
Enter an integration Name (no spaces are allowed).
(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:

Configure present: At least one repository is already connected to the platform.
Configure is not present: Available to connect to the platform.

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

New features in the CloudBees platform may sometimes require updates to permissions in the GitHub App registered by CloudBees.

Figure 1. Example GitHub App installation.

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

Your GitHub account is connected to the platform and listed in Configurations Integrations.

GitHub App permission change requests

On occasion, new features in the CloudBees platform may require updates to permissions in the GitHub App for full functionality. If the CloudBees platform requires a permissions update, all users of the GitHub App:

Receive an email notification from GitHub alerting them of the permissions change request.
Can access the permissions change request in the Installed GitHub applications listing for the connected GitHub organization.

Figure 2. Example GitHub App permissions update request.

To update GitHub App permissions:

Go to your list of installed GitHub Apps, and select Review request next to CloudBees platform.
Review the Developer note describing why this change is necessary.
Select Accept new permissions.

The CloudBees platform GitHub App permissions have been updated to enable full functionality for the new platform feature described in the Developer note.

If you choose not to accept the new permissions, your existing permissions are retained, and you will not be able to use the new platform feature.

For more information, refer to the GitHub documentation for approving updated permissions for a GitHub App.

Bitbucket

If you have an Atlassian Bitbucket repository in the cloud, you can use an access token to connect it to the platform.

To integrate with Bitbucket:

Select an organization, and then select Configurations Integrations.
Select Create integration.
Select Source code management.
Select Bitbucket access token.
Enter an integration Name (no spaces are allowed).
(optional) Enter a Description.
Enter your Token.

Figure 3. An example Bitbucket access token with the appropriate permissions.
The CloudBees platform requires only the following scopes from Bitbucket:

Repositories: Read and write

Pull requests: Read and write

Webhooks: Read and write
(Optional) Select Test integration to check the connection.
Select Submit.

Your Bitbucket account is connected to the platform and listed in Configurations Integrations.

Bitbucket Data Center

Enterprise teams who require an on-premises repository can use the Atlassian Bitbucket Data Center. You can connect Bitbucket Data Center to the platform using an access token.

To integrate with Bitbucket Data Center:

Select an organization, and then select Configurations Integrations.
Select Create integration.
Select Source code management.
Select Bitbucket Data Center access token.
Enter an integration Name (no spaces are allowed).
(optional) Enter a Description.
Enter your Bitbucket Data Center URL.

Enter your Token.

The CloudBees platform requires the following scopes from Bitbucket:

Repository admin permissions

Refer to the Bitbucket Data Center HTTP access token documentation for more information.

(Optional) Select Test integration to check the connection.
Select Submit.

Your Bitbucket Data Center account is connected to the platform and listed in Configurations Integrations.