GitHub integration

CloudBees Software Delivery Management 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 Engineering Efficiency can pull data from GitHub (GitHub.com) and GitHub Enterprise, the on-premise version of GitHub.com. This data, stored in the System of Record, can be used to generate insights to highlight blocked pull requests and 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 Software Delivery Management integrates with GitHub using the CloudBees SDM app, which connects a GitHub organization to your CloudBees Software Delivery Management 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 Software Delivery Management user profile currently.

GitHub Enterprise

CloudBees Engineering Efficiency 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 Engineering Efficiency and stored in the System of Record. Data from GitHub is used to update CloudBees Engineering Efficiency screens like Investment areas and Activity.

Changes to data in GitHub are reflected in CloudBees Engineering Efficiency 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 System of Record.

When a repository is deleted on GitHub, the repository, branches, and pull requests are also removed from the System of Record. This data will no longer appear on a product’s 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 Software Delivery Management 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. However, these repositories are no longer updated unless the integration with the associated GitHub organization is restored.

Refer to GitHub permissions for details about permissions and data used from GitHub.

Connecting to GitHub

To connect to GitHub.com, you must install the CloudBees SDM app on GitHub. After you have connected GitHub to CloudBees Software Delivery Management, you can see your GitHub repository data in CloudBees Software Delivery Management. 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 Software Delivery Management.

To connect GitHub to CloudBees Software Delivery Management:

  1. Select User profile  Settings.

  2. Select Engineering Efficiency  Apps.

  3. Select the GitHub app.

  4. On the GitHubscreen, select Configuration.

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

  6. Select Install (first time) or Configure (additional configurations) on the GitHub app.

  7. Select the GitHub organization you want to associate with your CloudBees Software Delivery Management 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 Software Delivery Management, select All repositories. All future updates will automatically be imported into CloudBees Software Delivery Management.

    • To allow CloudBees Software Delivery Management 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 Software Delivery Management.

  9. Select Install & Authorize.

  10. Return to CloudBees Engineering Efficiency.

It may take several minutes for data to be imported, depending upon the number and size of repositories selected.

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

Once you have set up the GitHub integration, you can create a product and link repositories.

Connecting to GitHub Enterprise

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

  • Sign in to CloudBees Software Delivery Management as an admin and install the GitHub app. This app supports both GitHub and GitHub Enterprise.

  • 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 Software Delivery Management.

  • Connect that app to CloudBees Software Delivery Management.

Installing the GitHub Enterprise app

This procedure requires CloudBees Engineering Efficiency administrator rights.

To install the CloudBees GitHub Enterprise integration app:

  1. Select User profile  Organization settings.

  2. Select Engineering Efficiency  Apps.

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

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

  5. Select GitHub.

  6. Select Install app and then Install on the Install GitHub dialog.

Connecting GitHub Enterprise servers

This procedure requires CloudBees Software Delivery Management administrator rights.

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

  1. Select the GitHub app.

  2. Select the Configuration tab.

  3. Select Add GitHub Enterprise server to configure your first connection.

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

  5. On the Create GitHub App page, the app name CloudBees SDM is automatically populated. Do not change this value.

  6. Select Create GitHub App. The window will automatically close.

Authorizing organizations and repositories

When you return to CloudBees Engineering Efficiency, the GitHub page displays a list of connected servers, including the one you just added. The currently authorized organizations and repositories are underneath the server list.

This procedure requires CloudBees Software Delivery Management and GitHub administrator rights.

To authorize organizations and repositories:

  1. Select Configure next to the GitHub Enterprise Server you just added.

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

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

  4. Select one of the following options:

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

    • To allow CloudBees Software Delivery Management 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.

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

Once the GitHub integration is set up, CloudBees Software Delivery Management admins can create a product and link repositories.

Removing a GitHub integration

There are two ways to remove a GitHub Cloud integration:

  • Remove the GitHub organizations from CloudBees Software Delivery Management. When you do this, CloudBees Software Delivery Management 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 Software Delivery Management no longer receives repository data from GitHub. If you delete the integration in GitHub, CloudBees Software Delivery Management 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 Software Delivery Management.

Removing a GitHub organization

This procedure requires CloudBees Software Delivery Management administrator rights.

To remove a GitHub organization:

  1. Select User profile  Organization settings.

  2. Select Engineering Efficiency  Apps.

  3. Select Apps and then select GitHub.

  4. Select Remove organization.

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

  6. Select Remove.

Removing a GitHub Enterprise integration

You can have one or more GitHub Enterprise servers integrated with CloudBees Software Delivery Management. 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.

This procedure requires CloudBees Software Delivery Management administrator rights.

To remove integration with one GitHub Enterprise server:

  1. Select User profile  Organization settings.

  2. Select Engineering Efficiency  Apps.

  3. Select GitHub Enterprise.

  4. Select the name of the server to remove.

  5. Select Configure on the integration.

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

Reconnecting a GitHub integration

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

This procedure requires CloudBees Software Delivery Management administrator rights.

To reconnect a GitHub organization:

  1. Select User profile  Organization settings.

  2. Select Engineering Efficiency  Apps.

  3. Select GitHub from the list of apps.

  4. Select Reconnect next to the organization name.

  5. In the warning message, select Reconnect.

  6. 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 Software Delivery Management 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 Engineering Efficiency 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 appear.

This procedure requires CloudBees Software Delivery Management administrator rights.

To add or remove repositories for an existing GitHub integration:

  1. Select User profile  Organization settings.

  2. Select Engineering Efficiency  Apps.

  3. Select GitHub from the list of apps.

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

  5. Select Configure.

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

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

  8. Select Save.

Requesting data removal

Once data is imported into the System of Record, data will stay synchronized as part of normal operations as data changes. You can request to have data removed from your organization by contacting CloudBees support.

GitHub permissions

CloudBees Software Delivery Management 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 Engineering Efficiency.

CloudBees Software Delivery Management 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

Contents

Read-only

Repository

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

Issues

Read-only

Repository

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

Metadata

Read-only

Repository

Provides descriptive information about repositories.

Pull requests

Read-only

Repository

Enables list of pull requests.

Commit statuses

Read-only

Repository

Provides the status of commits.

Create

Enabled

Subscribe to events

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

Delete

Enabled

Subscribe to events

Allows CloudBees Software Delivery Management to track deleted branches, which helps keep active branches synchronized.

Fork

Enabled

Subscribe to events

Notifications when a repository is forked.

Issues

Enabled

Subscribe to events

Notifications when an issue is opened, edited, deleted, transferred, pinned, unpinned, closed, reopened, assigned, unassigned, labeled, unlabeled, milestoned, demilestoned, locked, or unlocked.

Label

Enabled

Subscribe to events

Allows CloudBees Software Delivery Management to read Labels, allowing for policies to disregard Work in Progress etc.

Pull request

Enabled

Subscribe to events

Notifications when a pull request status changes or is updated.

Pull request review

Enabled

Subscribe to events

Notifications for pull request reviews.

Push

Enabled

Subscribe to events

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

Repository

Enabled

Subscribe to events

Notifications on repository status changes.

Status

Enabled

Subscribe to events

Notifications for CI build statuses.