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. Learn more about the preview program.

CloudBees SDM can pull data from GitHub (GitHub.com) and GitHub Enterprise (on-premise version of GitHub.com). This data, stored in the System of Record, can be used to generate reports and policies to perform actions such as highlighting blocked pull requests and adding status labels to identify stalled work.

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

GitHub

CloudBees SDM integrates with GitHub using the CloudBees SDM app, which connects a GitHub organization to your CloudBees SDM user profile. You need administrative rights on your GitHub organization to install the CloudBees SDM app.

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

GitHub Enterprise

CloudBees SDM integrates with GitHub Enterprise using an app that is created in your GitHub user account and is owned by the user. Once the app is created, it can be installed into any account on your GitHub Enterprise server, whether on an organization or a personal account.

To add repositories once the GitHub Enterprise connection is made, you need to have admin rights for the GitHub Enterprise organization.

How GitHub data changes affect the System of Record

Once GitHub integration is configured, data is imported into CloudBees SDM and stored in the 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 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 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 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 Page where data is used

Contents

Read-only

Repository

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

Products, product Overview, Pull requests, Repositories

Issues

Read-only

Repository

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

Products, product Overview, Pull requests

Metadata

Read-only

Repository

Provides descriptive information about repositories.

Products, product Overview, Repositories

Pull requests

Read-only

Repository

Enables list of pull requests.

Products, product Overview, Pull requests

Commit statuses

Read-only

Repository

Provides the status of commits.

Products, 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.

Products, 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.

Products, product Overview, Pull requests

Pull request review

Enabled

Subscribe to events

Notifications for pull request reviews.

Products, product Overview, Pull requests

Push

Enabled

Subscribe to events

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

Products, 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 to GitHub.com, 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. Select Apps.

  2. Select GitHub, and then select Install app.

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

  4. On the CloudBees SDM app screen, select Configuration.

  5. Select Configure GitHub and then select Configure GitHub on the pop-up window.

  6. Select Configure on the GitHub app.

  7. Select the GitHub organization you want to associate with your CloudBees SDM user profile. If you only have one user profile, that one is associated automatically.

  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.

The GitHub page now displays a list of the authorized organizations and repositories. Use Configure GitHub to update the repositories list.

Connecting to GitHub Enterprise

To use data resources from GitHub Enterprise in CloudBees SDM, you need to:

  • Install the GitHub app in CloudBees SDM.

  • Configure the connection with GitHub Enterprise automatically using your GitHub Enterprise URL, which creates a GitHub app so your GitHub Enterprise service can communication with CloudBees SDM.

  • Connect that app to CloudBees SDM.

To install the CloudBees GitHub Enterprise integration app:

  1. Select Apps.

  2. Verify that the GitHub Enterprise app has a green check and is listed in the Installed section.

  3. If the GitHub Enterprise app is listed in Available and not Installed, then continue to the next step.

  4. Select GitHub Enterprise.

  5. Select Install app and then Install on the Install GitHub Enterprise dialog.

Once the app is installed, you can add multiple GitHub Enterprise servers. To configure servers:

  1. Select the GitHub app.

  2. Select Configuration to configure your first connection.

  3. Select Configure GitHub Enterprise.

  4. Enter your GitHub Enterprise URL and select Continue. You may be required to sign on.

  5. On the Create GitHub App page, the app name CloudBees SDM is automatically populated. Select Create GitHub App. The window will automatically close.

  6. Select Continue to close the CloudBees SDM window.

When you return to CloudBees SDM, the GitHub page will display a list of connected servers. Underneath the server list, you can use the repositories section.

  1. Below the connected server table, select Add your repositories.

  2. When you are redirected to your GitHub Enterprise instance, select Install on the your CloudBees SDM app.

  3. 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.

  4. Select Install.

You can use Add GitHub Enterprise server to add additional servers. If you have both GitHub and GitHub Enterprise configured, then the GitHub apps page will list connected servers and authorized organizations. The Connected servers list will include github.com.

Removing a GitHub Cloud integration

There are two ways to remove a GitHub Cloud 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. Select Apps and then select GitHub.

  2. Select Remove organization.

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

  4. Select Remove.

Removing a GitHub Enterprise integration

You can have one or more GitHub Enterprise servers integrated with CloudBees SDM. You can remove an individual servers by deleting the CloudBees SDM app for that server or you can remove all GitHub Enterprise servers by uninstalling the GitHub Enterprise app.

To remove integration with one GitHub Enterprise server:

  1. Select Apps and select GitHub Enterprise.

  2. Select the name of the server to remove.

  3. Select Configure on the integration.

  4. Select the three-dot menu icon on the far left and select Remove.

Reconnecting a GitHub integration

If the integration between CloudBees SDM and a GitHub.com 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. Select Apps and then select GitHub.

  2. Select GitHub.

  3. In the warning message, select Reconnect.

  4. 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. Select Apps and then select GitHub.

  2. Select Configuration and then Configure next to the server you wish to update.

  3. Select Configure.

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

  5. 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.

  6. Select Save.