GitHub data integration

CloudBees Engineering Efficiency uses the CloudBees Software Delivery Management app to connect a GitHub organization to your CloudBees Engineering Efficiency user profile. You need administrative rights on your GitHub organization to install the app.

How the service works

The customer installs a GitHub app developed by CloudBees into their GitHub organization. Once installed, this app runs a sync operation to send CloudBees Engineering Efficiency data from GitHub, then updates as data is created, updated, and deleted. The sync operation also repeats periodically and resends all data created or updated since the last sync.

The app sends data that includes the following:

  • Repositories

  • Branches

  • Commits

  • PullRequests

  • PullRequestReviews

  • Issues

User information is removed from the above entities on ingestion and stored separately in the System of Record.

Data is sent to the CloudBees Engineering Efficiency backend service via the REST API. This service handles authentication and is responsible for verifying GitHub as a source of data updates. The backend receives and stores your data where it can be retrieved and used by the System of Record GraphQL for your applications. This is the same methodology that is used with GitHub Enterprise.

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 and GitHub Enterprise is included on 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 from 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, the data’s status in CloudBees Engineering Efficiency 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 is no longer synced.

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.

Data syncs between GitHub and System of Record

Data syncs between GitHub/GitHub Enterprise and CloudBees Engineering Efficiency use the same process.

After an integration to GitHub is created or updated, an installation scan fetches data entities related to the GitHub repositories the GitHub app has been authorized for.

This scan retrieves the repository data from GitHub at a maximum rate of 2 API calls per second, with a maximum of one concurrent request at once. If the scan reaches the GitHub API rate limits, the scan backs off subsequent API requests to prevent those requests from failing.

This continues until all the repository data has been fetched from GitHub. For large organizations, this can take a few hours.

After the initial synchronization completes, ongoing changes in GitHub will be triggered via webhook events to CloudBees Engineering Efficiency any time a repository, pull-request, branch, or issue is updated. These webhook events are processed directly and do not result in subsequent API calls back to GitHub from CloudBees Engineering Efficiency.

GitHub Cloud integration data

CloudBees Engineering Efficiency stores the following data from the GitHub integration:

This includes (embedded in the above objects) the following personally identifiable information:

  • User, but only the following fields:

    • Name (public profile name, for example, Brenda Wilson)

    • Login (GitHub handle, for example, bwilson834)

    • Url (URL for the user profile, for example, /https://github.com/bwilson834)

    • Email (for example, /bwilson@cloudbees.com)

  • Status

  • Label

GitHub permissions

CloudBees Engineering Efficiency uses GitHub data to provide information about repository health, build failures, and pull requests. The CloudBees Software Delivery Management requires permissions to share data with CloudBees Engineering Efficiency.

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

PermissionAccessPermission groupData 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 Engineering Efficiency 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 Engineering Efficiency 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.