GitHub integration

The GitHub integration lets you connect your GitHub repositories to CloudBees Software Delivery Management, thereby making repository and pull request data related to a product or deliverables visible. Additionally, the GitHub data is used to surface development process efficiency metrics and insights focused on how code moved from first commit to production.

The CloudBees Software Delivery Management app provides support for data ingestion from GitHub (github.com) and GitHub Enterprise (self-hosted). This data is stored in the System of Record.

GitHub and GitHub Enterprise both use the same integration app.

GitHub Enterprise has to be publicly accessible with internet access to contact CloudBees Engineering Efficiency to send and receive data.

GitHub Enterprise uses 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.

Refer to GitHub data usage and GitHub Enterprise data usage for information about how the service works, data usage, and GitHub permissions.

Once the integration is configured, the GitHub screen now displays a list of the authorized organizations and repositories. Use Configure GitHub to update the repositories list.

GitHub app page
Figure 1. GitHub app integration screen after configuration

Requirements

To integrate GitHub or GitHub Enterprise, you must have:

  • Administrative rights in CloudBees Engineering Efficiency.

  • GitHub: Administrative rights on your GitHub organization. For additional information, refer to the GitHub documentation on permissions levels for organizations.

  • GitHub Enterprise: You need to have admin rights for the GitHub Enterprise organization and the GitHub Enterprise server needs to be accessible from the internet.

The GitHub integration does not allow a GitHub organization to be associated with more than one CloudBees Engineering Efficiency organization.

Connecting to GitHub

To connect CloudBees Engineering Efficiency to GitHub.com, you must configure the GitHub app in CloudBees Engineering Efficiency and install the CloudBees Software Delivery Management app on GitHub. After you have connected GitHub, you can see your GitHub repository data in CloudBees Engineering Efficiency.

The app name is truncated on Github and is listed as "CloudBees Software Delivery Manage…​".

You must have administrative privileges in CloudBees Engineering Efficiency to integrate GitHub.

To connect GitHub to CloudBees Engineering Efficiency:

  1. Sign in to CloudBees Engineering Efficiency as an admin.

  2. In the top right, select your organization to open the User profile menu and then select your name.

  3. In the left navigation, select Engineering Efficiency  Apps.

  4. Select the GitHub app.

  5. On the GitHub screen, select Configuration.

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

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

    • To allow CloudBees Engineering Efficiency 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 the System of Record.

  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.

Once you have set up the GitHub integration, you can define 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 Engineering Efficiency 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 Engineering Efficiency.

  • Connect that app to CloudBees Engineering Efficiency.

Installing the GitHub Enterprise app

This procedure requires CloudBees Engineering Efficiency administrator rights.

To install the CloudBees GitHub Enterprise integration app:

  1. In the top right, select your organization to open the User profile menu and then select your name.

  2. In the left navigation, 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 Engineering Efficiency 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 authorized organizations and repositories are underneath the server list.

This procedure requires CloudBees Engineering Efficiency and GitHub administrator rights.

To authorize organizations and repositories:

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

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

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

  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.

Once the GitHub integration is set up, CloudBees Engineering Efficiency 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 Engineering Efficiency. When you do this, CloudBees Engineering Efficiency 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 Engineering Efficiency no longer receives repository data from GitHub. If you delete the integration in GitHub, CloudBees Engineering Efficiency 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 Engineering Efficiency.

Removing a GitHub organization

This procedure requires CloudBees Engineering Efficiency administrator rights.

To remove a GitHub organization:

  1. In the top right, select your organization to open the User profile menu and then select your name.

  2. In the left navigation, 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 Engineering Efficiency. You can remove an individual server by deleting the CloudBees Software Delivery Management app for that server or you can remove all GitHub Enterprise servers by uninstalling the GitHub Enterprise app.

This procedure requires CloudBees Engineering Efficiency administrator rights.

To remove integration with one GitHub Enterprise server:

  1. In the top right, select your organization to open the User profile menu and then select your name.

  2. In the left navigation, 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 Engineering Efficiency and a GitHub.com organization becomes disconnected in GitHub, CloudBees Engineering Efficiency 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 Engineering Efficiency administrator rights.

To reconnect a GitHub organization:

  1. In the top right, select your organization to open the User profile menu and then select your name.

  2. In the left navigation, 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 Engineering Efficiency 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 Engineering Efficiency administrator rights.

To add or remove repositories for an existing GitHub integration:

  1. In the top right, select your organization to open the User profile menu and then select your name.

  2. In the left navigation, 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.