GitHub integration

CloudBees SDM is a preview, with early access for select preview members. Product features and documentation are frequently updated. If you find an issue or have a suggestion, please contact CloudBees Support.

CloudBees SDM integrates with GitHub using the CloudBees SDM app, which connects a GitHub organization to your CloudBees SDM account.

You need administrative rights on your GitHub organization to install the CloudBees SDM app. For additional information, refer to the GitHub documentation on permissions levels for organizations.

You can associate a GitHub organization with only a single CloudBees SDM account currently.

How GitHub data changes affect the System of Record

Once GitHub integration is configured, data is imported into CloudBees SDM and stored in the unified system of record. Data from GitHub is used to update product pages, including the Overview and Pull requests screens. For example, if a pull request has not been reviewed in GitHub, a status label will appear for the pull request’s repository on the Pull request screen.

Changes to data in GitHub are reflected in CloudBees SDM for active repositories, including branches and pull requests within those repositories, within a GitHub organization. Changing the state of a repository by deleting it, for example, means that the data is then removed in CloudBees SDM.

When a repository is deleted on GitHub, then the repository, branches, and pull requests are also removed from the unified system of record in CloudBees SDM. This data will no longer appear on a product’s Pull requests and Overview screens. Deleting a branch on GitHub also removes the branch from the system of record, but does not delete pull request data.

When a repository is archived in GitHub, then the data’s status in CloudBees SDM changes to archived. This status change is reflected in the unified system of record. The data from an archived repository will still be present on product screens associated with that repository, but the data will be stale.

Removing a GitHub integration leaves all repositories associated with the GitHub organization in the unified system of record in CloudBees SDM. However, these repositories are no longer updated unless the integration with the associated GitHub organization is restored.

GitHub permissions

CloudBees SDM uses GitHub data to provide information about repository health, build failures, and pull requests. The CloudBees SDM app requires permissions to share data with CloudBees SDM.

CloudBees SDM accesses GitHub data or subscribes to notifications. Both permission types provide read-only access, which allows data to be accessed but not modified.

Permission Access Permission group Data or feature enabled Where data is used

Contents

Read-only

Repository

Repository activity, like contents, commits, branches, downloads, releases, and merges.

Product hub, product Overview, Pull requests, Repositories

Issues

Read-only

Repository

Provides information on issues, related comments, labels, assignees, and milestones.

Product hub, product Overview, Pull requests

Metadata

Read-only

Repository

Provides descriptive information about repositories.

Product hub, product Overview, Repositories

Pull requests

Read-only

Repository

Enables list of pull requests.

Product hub, product Overview, Pull requests

Commit statuses

Read-only

Repository

Provides the status of commits.

Product hub, product Overview, Pull requests

Create

Enabled

Subscribe to events

Provides a notification when a branch or tag is created, which updates the screens that display repository data.

Product hub, product Overview, Pull requests

Delete

Enabled

Subscribe to events

Allows CloudBees SDM to track deleted branches, which helps keep active branches synchronized.

Repositories

Label

Enabled

Subscribe to events

Allows CloudBees SDM to read Labels, allowing for policies to disregard Work in Progress etc.

Repositories

Pull request

Enabled

Subscribe to events

Notifications when a pull request status changes or is updated.

Product hub, product Overview, Pull requests

Pull request review

Enabled

Subscribe to events

Notifications for pull request reviews.

Product hub, product Overview, Pull requests

Push

Enabled

Subscribe to events

Notifications for push actions to update latest update times for repsitories and pull requests.

Product hub, product Overview, Pull requests

Status

Enabled

Subscribe to events

Notifications for CI build statuses.

Repositories, product Overview, Pull requests

Repository

Enabled

Subscribe to events

Notifications on repository status changes.

Repositories

Connecting to GitHub

To connect GitHub, you must install the CloudBees SDM app on GitHub. After you have connected GitHub to CloudBees SDM, you can see your GitHub repository data in CloudBees SDM. Then, you can link repositories and data to products to help you to prioritize work and locate blockers.

You must have administrative privileges in CloudBees to connect GitHub to CloudBees SDM.

To connect GitHub to CloudBees SDM:

  1. In the top right of any screen, select the organization name.

  2. Select Manage integrations.

  3. Select Add integration.

  4. On the Add integration screen, select GitHub, and then select Add.

  5. On the Add GitHub integration screen, verify that you want to install and configure the CloudBees SDM app, and then click Add.

  6. On the CloudBees SDM app screen, select Configure.

  7. Select the GitHub organization you want to associate with your CloudBees SDM account. If you only have one account, that account is associated automatically. You may be prompted for your GitHub password.

  8. Select one of the following options:

    • To make all repositories in the organization available in CloudBees SDM, select All repositories. All future updates will automatically be imported into CloudBees SDM.

    • To allow CloudBees SDM to access only specific repositories, select Only select repositories, and then select the repositories you want to add. Any time a new repository is added, you must update the list of approved repositories to import the updates into CloudBees SDM.

  9. Select Install and Authorize.

Removing a GitHub integration

There are two ways to remove a GitHub integration:

  • Remove the GitHub organizations from CloudBees SDM. When you do this, CloudBees SDM automatically deletes the integration from GitHub as well so you do not have to do it manually. This is the preferred method.

  • Delete the integration in GitHub. When you delete an integration in GitHub, CloudBees SDM no longer receives repository data from GitHub. If you delete the integration in GitHub, CloudBees SDM shows an alert to let you know which organizations are no longer sending repository data. Then, you should remove the affected GitHub organizations from CloudBees SDM.

To remove a GitHub organization:

  1. In the top right of any screen, select the organization name.

  2. Select Manage integrations.

  3. On the Integrations screen, select GitHub.

  4. Select Remove organization.

  5. Select the name of the organizations you want to remove.

  6. Select Remove.

Reconnecting a GitHub integration

If the integration between CloudBees SDM and a GitHub organization becomes disconnected in GitHub, CloudBees SDM shows an alert to let you know which organizations are affected. You can either remove the affected organization from CloudBees SDM or reconnect the integration in GitHub.

To reconnect a GitHub organization:

  1. In the top right of any screen, select the organization name.

  2. Select Manage integrations.

  3. On the Integrations screen, select GitHub.

  4. In the warning message, select Reconnect.

  5. In GitHub, reconnect the organization.

Adding or removing repositories for an existing GitHub integration

When GitHub integration is configured, either all repositories from an organization are included or only selected repositories are included. If you have administrative privileges, you can add or remove repositories.

CloudBees SDM will stop receiving data from removed repositories. Any products, screens, or other features using data from the removed repositories will become out of date. Adding the repositories back restores the associations.

Repositories added after completing GitHub integration automatically show up in CloudBees SDM when all repositories from an organization are included. If you selected individual repositories, then any repositories created later must be manually added.

Repositories may take several minutes to show up in CloudBees SDM.

To add or remove repositories for an existing GitHub integration:

  1. In the top right of any screen, select the organization name, and then select Manage integrations.

  2. On the Integrations screen, select GitHub.

  3. On the Integrations/GitHub screen, select Configure integration.

  4. On the GitHub App screen, select Configure.

  5. Select the organization for which you want to update repositories. You may be prompted for a password.

  6. Do one of the following:

    1. To add specific new repositories, select Select repositories, and then select the repositories you want to add.

    2. To add all repositories, select All repositories.

    3. To remove repositories, select the X next to the repositories you want to remove.

  7. Select Save.