GitHub integration

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

You need administrative rights on your GitHub organization to install the CloudBees Product Hub 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 platform for SDM account currently.

How GitHub data changes affect the System of Record

Once GitHub integration is configured, data is imported into CloudBees platform for 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 platform for 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 platform for 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 platform for 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 platform for 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 platform for SDM. However, these repositories are no longer updated unless the integration with the associated GitHub organization is restored.

GitHub permissions

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

CloudBees platform for 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

Checks

Read-only

Repository

Checks on code, which include build failures, shown on the Pull requests and Product overview screens.

Pull requests, product Overview, Product hub

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

Email addresses

Read-only

User

Provides a GitHub user’s email address.

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 platform for SDM to track deleted branches, which helps keep active branches synchronized.

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

Repository

Enabled

Subscribe to events

Notifications on repository status changes.

Repositories

Connecting to GitHub

To connect GitHub, you must install the CloudBees Product Hub app on GitHub. After you have connected GitHub to CloudBees platform for SDM, you can see your GitHub repository data in CloudBees platform for 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 platform for SDM.

To connect GitHub to CloudBees platform for 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 Product Hub app, and then click Add.

  6. On the CloudBees Product Hub app screen, select Configure.

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

    • To allow CloudBees platform for 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 platform for 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 platform for SDM. When you do this, CloudBees platform for 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 platform for SDM no longer receives repository data from GitHub. If you delete the integration in GitHub, CloudBees platform for 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 platform for 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 platform for SDM and a GitHub organization becomes disconnected in GitHub, CloudBees platform for SDM shows an alert to let you know which organizations are affected. You can either remove the affected organization from CloudBees platform for 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 platform for 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 platform for 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 platform for 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.

Copyright © 2010-2020 CloudBees, Inc.Online version published by CloudBees, Inc. under the Creative Commons Attribution-ShareAlike 4.0 license.CloudBees and CloudBees DevOptics are registered trademarks and CloudBees Core, CloudBees Flow, CloudBees Flow Deploy, CloudBees Flow DevOps Insight, CloudBees Flow DevOps Foresight, CloudBees Flow Release, CloudBees Accelerator, CloudBees Accelerator ElectricInsight, CloudBees Accelerator Electric Make, CloudBees CodeShip, CloudBees Jenkins Enterprise, CloudBees Jenkins Platform, CloudBees Jenkins Operations Center, and DEV@cloud are trademarks of CloudBees, Inc. Most CloudBees products are commonly referred to by their short names — Accelerator, Automation Platform, Flow, Deploy, Foresight, Release, Insight, and eMake — throughout various types of CloudBees product-specific documentation. Oracle and Java are registered trademarks of Oracle and/or its affiliates. Jenkins is a registered trademark of the non-profit Software in the Public Interest organization. Used with permission. See here for more info about the Jenkins project. The registered trademark Jenkins® is used pursuant to a sublicense from the Jenkins project and Software in the Public Interest, Inc. Read more at www.cloudbees.com/jenkins/about. Apache, Apache Ant, Apache Maven, Ant and Maven are trademarks of The Apache Software Foundation. Used with permission. No endorsement by The Apache Software Foundation is implied by the use of these marks.Other names may be trademarks of their respective owners. Many of the designations used by manufacturers and sellers to distinguish their products are claimed as trademarks. Where those designations appear in this content, and CloudBees was aware of a trademark claim, the designations have been printed in caps or initial caps. While every precaution has been taken in the preparation of this content, the publisher and authors assume no responsibility for errors or omissions, or for damages resulting from the use of the information contained herein.