GitHub

Overview

Set up the GitHub integration to configure GitHub Apps that connect your GitHub organization or personal account to Datadog, allowing you to access source code-related functionality, collect valuable data, and help you monitor and secure your GitHub environment.

For example, once the GitHub App is installed with the relevant permissions enabled, you can use the Datadog source code integration to see code snippets in your stack traces, get automated feedback and suggested changes through pull request comments from CI Visibility and Code Security, and access multiple service definitions in GitHub from the Software Catalog.

The Repository Configuration tab on the GitHub integration tile

Setup

Follow these instructions to install a GitHub App and grant Datadog permission to access resources in GitHub.

Install and authorize a GitHub App to grant permissions

If you are an admin in your GitHub organization, you can configure GitHub Apps. You can also create GitHub Apps with a personal GitHub account.

Depending on the product feature, additional setup beyond the creation of a GitHub App may be required to fully enable that feature. Creating a GitHub App to connect your account only grants the GitHub permissions that these features require as prerequisites. You do not incur additional charges for creating GitHub Apps and no feature associated with a billable product is enabled by default, even if you grant the prerequisite permissions for those features.

In the GitHub integration tile, navigate to the Configuration tab.
Click Connect GitHub Account to create a new GitHub App.
In Configure App, either select Organization and enter the name of your organization in GitHub, or select Personal Account.
For self-hosted GitHub deployments, select Running GitHub enterprise server and enter the URL of your GitHub Enterprise Server instance (version 2.22 or above). Make sure that Datadog servers can connect to your GitHub instance. Server IPs are available in the Webhooks section of IP Ranges.
Optionally, if you do not wish to use Datadog’s recommended configuration, expand Edit GitHub App permissions to view and customize the GitHub permissions you want to grant to Datadog. The summary contains these sections:
- Datadog Features lists the general and product-specific features in Datadog that require specific GitHub permissions. Expand each feature for details on functionality and requirements.
- GitHub Permissions lists the related GitHub permissions. You can use the Access Level drop-downs to change the access allowed for specific aspects of your GitHub environment.
By default, Datadog selects the recommended permissions needed for all source code-related features. Changing the permissions will impact feature functionality. The Datadog Features section identifies any unavailable features and their missing requirements.
Click Create App in GitHub. If needed, you are prompted to authenticate into GitHub.
In GitHub, enter a name for your GitHub App and click Create GitHub App.
Choose whether to install the GitHub App for All repositories or Only select repositories, then click Install & Authorize.

You’re returned to where you left off in Datadog once you finish installing the GitHub App. To enable inline code snippets in APM, consider setting up Source Code Integration.

Notebooks

If you have granted your GitHub App read permissions for issues and pull requests, GitHub issues and pull requests automatically generate a preview hoverbox with details including the commit history, author, and date in Notebooks.

Navigate to Notebooks > New Notebook.
Add a Text cell and mention an issue or pull request on GitHub in the Edit field, for example: https://github.com/project/repository/pull/#.
Click Done. The GitHub icon appears next to your linked issue or pull request.
If needed, click Connect to Preview and Authorize.
Hover over the linked issue or pull request to see the description preview.

Audit Logs

Requirement: A GitHub Enterprise account is required to collect audit logs.

Audit logs encompass all activities and events across a GitHub organization. Follow the instructions on Setting up streaming to Datadog in GitHub’s documentation to forward your audit logs to Datadog. For more information about audit logs, see GitHub’s documentation for Audit log actions.

Data Collected

Metrics

The GitHub integration collects Code Scan Alert and Secret Scan Alert metrics. These metrics provide an overview of the organization’s Alert state by categorizing their state, repo, and secret type. They also provide long-term insights on Alert trends and their general progress.

github.code_scan_alert (gauge)	Github Code Scan Alerts Shown as alert
github.secret_scan_alert (gauge)	Github Secret Scan Alerts Shown as alert

To start collecting these metrics, select the respective permissions for read access upon the application’s installation. To opt-out of Code Scan or Secret Scan metrics, find the corresponding organization in the Telemetry tab on the integration tile, click the toggle for the respective sections, and click Update Account.

Events

Follow these instructions to configure webhooks in GitHub and Datadog, allowing events to appear in the Events Explorer.

Add a webhook in GitHub

In your GitHub project, navigate to Settings > Webhooks.
Click Add webhook.
Add the following URL in the Payload URL field: https:///intake/webhook/github?api_key=<DATADOG_API_KEY>. Don’t forget to replace <DATADOG_API_KEY> with your Datadog API Key.
Select application/json in the Content type dropdown menu.
Optionally, add a secret in the Secret field.

In the Which events would you like to trigger this webhook? section, click Let me select individual events. and select from the following supported options to send events to Datadog:

Event Name	Event Actions
Branch or tag creation
Commit comments
Issue comments	The following actions are supported: - `created` - `deleted` - `edited`
Issues	The following actions are supported: - `assigned` - `closed` - `deleted` - `demilestoned` - `edited` - `labeled` - `locked` - `milestoned` - `opened` - `pinned` - `reopened` - `transferred` - `unassigned` - `unlabeled` - `unlocked` - `unpinned`
Pull request review comments	The following actions are supported: - `created` - `deleted` - `edited`
Pull requests	The following actions are supported: - `assigned` - `unassigned` - `labeled` - `unlabeled` - `opened` - `edited` - `closed` - `reopened` - `synchronize` - `converted_to_draft` - `locked` - `unlocked` - `enqueued` - `dequeued` - `milestoned` - `demilestoned` - `ready_for_review` - `review_requested` - `review_request_removed` - `auto_merge_enabled` - `auto_merge_disabled`
Pushes
Repositories	The following actions are supported: - `archived` - `created` - `deleted` - `edited` - `privatized` - `publicized` - `renamed` - `transferred` - `unarchived`
Security Advisory
Team adds

Select Active to receive event details when the hook is triggered.
Click Add webhook to save the webhook.

Add a webhook in Datadog

In the GitHub integration tile, navigate to the Webhooks tab.
Specify the repositories and branches you want to monitor for each repository. To add all repositories for a user or organization, use wildcards (*). You can use wildcards on branch names. For example, dev-* includes all branches starting with dev-.
To gather all events related to the master branch of the DataDog/documentation GitHub repository, you can enter DataDog/documentation in the Repository field and master in the Branches field.
If you wanted to gather all events related to all master branches from the DataDog organization, enter DataDog/* in the Repository field and master in the Branches field. Note: When using a wildcard for the repository name, you must specify the user or organization. For example, ‘’ is not a valid repository name, but ‘DataDog/’ is.
Click the checkboxes for Commits and Issues to be alerted of these events.
Click Update Configuration to save the webhook configuration.

After you have added webhooks in the Webhooks tab on the integration tile, events in the GitHub repositories you specified above start to appear in the Events Explorer. For more information, see the Events Explorer documentation.

To filter events coming from GitHub, select Github in the Source facet menu under Core, or enter source:github in the search query. The bar chart of events automatically updates as you edit the search query.