Installing the GitHub App

What type of data does the GitHub app ingest?

The GitHub app collects data from two sources:

• GitHub webhooks that generate data for action runs and commits as well as real-time updates for Pull Requests, releases, and repositories.

• The Observe poller for GitHub that periodically collects metadata about issues, organizations, users, pull requests, releases, and repositories, as well as historical data for open Pull Requests and issues.

The following sections describe how to ingest data, install, and configure the collectors. For more about exploring this data, see GitHub.

Setup

Install the GitHub app using the App section under Workspace Setting.

Figure 1 - GitHub App Card

Webhook Configuration

On GitHub, set up a Webhook linked to your GitHub organization. As new activity happens, the Webhook pushes data to Observe. Observe ingests data for these GitHub sources:

• Activity Dashboard

• Action Run Dataset

• Administration Dashboard

• Commit Dataset

• Issues Dataset

• Pull Request Dataset

To configure the Webhook, navigate to your organization’s home page on GitHub and click Settings.

Figure 2 - GitHub Organization Home Page

If you don’t see the Settings tab, you may not have administrative permissions for your organization. Contact an organization administrator to confirm your permissions.

1. On the Settings menu, click on Webhooks.

2. Click Add webhook. You may need to authenticate to access the Webhook configuration page.

3. Configure the following settings:

   • Payload URL: https://${OBSERVE_TOKEN?}@${OBSERVE_CUSTOMER?}.collect.${OBSERVE_DOMAIN?}/v1/http/github

   • Content type: application/json

   

   Figure 3 - GitHub Webhook Configuration Page

   • Click Add webhook to save your configuration.

   For more about GitHub Webhooks, see Creating webhooks in the GitHub documentation.

Configuring the GitHub Poller

Pollers periodically request data from the GitHub API, allowing ingestion of existing details without relying on a triggering event. The poller ingests data from these sources:

• Administration Dashboard

• Issues Dataset

• Organization Dataset

• Pull Request Dataset

• Release Dataset

• Repository Dataset

• User Dataset

To create a GitHub API token, use the following steps:

1. Log into GitHub as the user you want to generate a token.

Note

Note that the user must at least have read permissions for the organizations and repositories you would like to ingest data. You can configure these roles by going to https://github.com/organizations/<organization name>/settings/roles.

2. Go to the Personal access token page and click on Generate new token in the top right then Generate new token (classic).

3. In the New personal access token (classic) dialog, add a name for the token under Note and set an expiration date suitable for your organization’s token rotation policies.

4. Define the scope for the token then click Generate token. Use the following scope to ingest all required data into Observe:

Figure 4 - GitHub Personal Access Token Scope-definition Page

Note that Observe only reads from GitHub.

In Observe, configure the GitHub Poller to collect and ingest data:

1. In the GitHub app, go to the Connections tab.

2. Under Data connection requirements, in the Onboard GitHub poller event section, click Create connection.

3. In the Create poller dialog, configure the following settings:

   • For GitHub Org, enter the name of your GitHub organization.

   • For GitHub Token, enter a GitHub API token associated with your GitHub account.

Figure 5 - GitHub Poller Configuration Page

You have now configured the GitHub app and can send your GitHub data to Observe.