Skip to main content

GitHub

Visualize GitHub users, teams, repositories, pull requests, issues, code scanning alerts and more. Map GitHub users to employees and training, and monitor software development activities, installations of GitHub apps, and outside collaborators.

Installation​

In order for this integration to run as expected, you will need to have an organization within the GitHub account for which you are creating the integration. Be sure to create an organization in your GitHub account to ensure having the required permissions. Learn more about GitHub organizations here.

info

GitHub Cloud & GitHub Enterprise Server Versions 3.3.3 and above have been verified as compatible with this integration. Other versions of GitHub Enterprise may work, but are not fully supported.

Configuration in JupiterOne​

To install the GitHub integration in JupiterOne, navigate to the Integrations tab in JupiterOne and select GitHub. Click New Instance to begin configuring the integration.

note

This integration limits the ingestion of pull requests and issues to the 500 most recently created or modified since the last execution.

In the new instance configuration, provide:

  • Account Name used to identify the GitHub account in JupiterOne. Ingested entities have this value stored in tag.AccountName when the AccountName toggle is enabled.

  • Description to assist in identifying the integration instance, if desired.

  • Polling Interval that you feel is sufficient for your monitoring needs. You may leave this as DISABLED and manually execute the integration.

  • For GitHub Enterprise Servers only: enable the toggle and provide the relevant Hostname, App ID, App Installation ID, and upload your API Private Key.

After creating a new GitHub integration configuration in JupiterOne, you will be re-directed to GitHub to install the JupiterOne GitHub app. The app requests read-only permissions to support ingestion of entities and relationships.

View GitHub permissions
Note

The Secrets API does not reveal the values of Secrets, only their names and creation dates.

Repository Permissions
  • Actions: Read-only
  • Administration: Read-only
  • Dependabot alerts: Read-only
  • Discussions: Read-only
  • Environments: Read-only
  • Issues: Read-only (enables both Issues and private-repo PRs)
  • Metadata: Read-only
  • Pages: Read-only
  • Pull requests: Read-only
  • Secrets: Read-only
  • Secret scanning alerts: Read-only
Organization Permissions
  • Administration: Read-only
  • Members: Read-only
  • Secrets: Read-only
  • Events: Read-only
User Permissioms
  • None
info

Refer to GitHub's documentation information on setting GitHub app permissions and secret permissions

Data Volume Configuration​

Control how much data is ingested from GitHub to manage storage and processing.

Ingestion Windows (Time Ranges)​

FieldDescriptionDefaultOptions
Pull Requests Ingestion WindowIngestion window for updated pull requests (days ago)9090, 180, 275, 365
Issues Ingestion WindowIngestion window for updated issues (days ago)9090, 180, 275, 365

How it affects data volume: Longer windows increase the number of pull requests and issues ingested. The integration limits ingestion to the 500 most recently created or modified items since the last execution.

Data Filtering Options​

FieldTypeDescriptionDefault
States Filter (Dependabot)Multi-selectLimit ingestion to Dependabot alerts with specified statesOpen
Severities Filter (Dependabot)Multi-selectLimit ingestion to Dependabot alerts with specified severitiesCritical, High, Moderate, Low
Ingest Generic Secret AlertsBooleanIngest generic secret alerts including default and generic patternsfalse

How it affects data volume:

  • Dependabot state filtering reduces alerts by excluding dismissed and fixed alerts. By default, only open alerts are ingested.
  • Dependabot severity filtering limits alerts to selected severities. By default, all severity levels are included.
  • Generic secret alerts, when enabled, increases the volume of secret scanning alerts by including generic patterns.

Hierarchy of data retrieval​

This integration uses many steps to retrieve data. Some of the steps depend on others. If there is a crash or error, it might be helpful to understand the hierarchy of step dependency:

  • The root step is fetch-account. All other steps depend on it.
  • There are four steps that depend only on fetch-account that could be considered primary steps. These are:
    1. fetch-apps
    2. fetch-repos
    3. fetch-users
    4. fetch-teams.
  • Other steps logically require multiple primary steps to complete. Examples include:
    • fetch-collaborators
    • fetch-team-members
    • fetch-team-repos
  • Finally, some sophisticated steps require both primary steps and secondary steps before they can execute. For example, fetch-prs needs both fetch-repos and fetch-collaborators in order to properly label reviewers and approvers.

Next steps​

Now that your integration instance has been configured, it will begin running on the polling interval you provided, populating data within JupiterOne. Continue on to our Instance management guide to learn more about working with and editing integration instances.