Overview
Use a GitHub App connection when you want to onboard your own GitHub App instead of authenticating actions with the Datadog GitHub integration tile.
With this connection, Datadog authenticates as an installation of your GitHub App. You provide the GitHub App ID, installation ID, and private key, and Datadog uses these credentials to request short-lived access tokens automatically. This approach allows you to control the repositories and permissions available to your workflows and apps.
Create and install a GitHub App
If you already have an installed GitHub App with the permissions required by your actions, skip to Gather the connection credentials. For full details on GitHub App creation options, see GitHub’s Registering a GitHub App guide.
- In GitHub, navigate to your organization’s Settings > Developer settings > GitHub Apps.
- Click New GitHub App.
- Enter an app name and homepage URL.
- Under Webhook, clear the Active checkbox unless you use the app’s webhook for another purpose. A GitHub App connection does not require a webhook.
- Under Permissions, grant access only to the resources your actions require, such as repository contents, pull requests, or issues.
- Click Create GitHub App.
- On the app’s settings page, click Install App.
- Select the organization where you want to install the app, then select whether the app can access all repositories or only selected repositories.
- Click Install.
Depending on your organization’s GitHub Apps policy, installing the app might require approval from an organization owner.
Gather the connection credentials
Gather the following values from GitHub:
- App ID: On the GitHub App’s settings page, copy the numeric App ID displayed near the top of the page.
- Installation ID: Open the app’s installation settings. The installation ID is the numeric value at the end of the URL, such as
github.com/organizations/<org>/settings/installations/12345678. - Private key: On the GitHub App’s settings page, under Private keys, click Generate a private key. GitHub downloads a
.pem file. Store the file securely; you cannot download the same private key from GitHub again.
Create the connection in Datadog
After you set up the GitHub App, create the connection in Datadog:
- From the Action Catalog page, click the Connections tab.
- Click New Connection.
- Select the GitHub connection type.
- Select the GitHub App credential type.
- Enter a connection name.
- Enter the App ID and installation ID you copied from GitHub.
- In the Private Key field, paste the full contents of the
.pem file. - If you use GitHub Enterprise Server, enter its hostname in the GitHub Hostname field. Leave this field blank for
github.com. - Click Create.
The connection is private by default. To allow other users to use it in workflows or apps, configure access from the connection’s permissions settings. For more information, see Access and Authentication for Workflow Automation or App Builder.
Update GitHub App permissions
If you add permissions to a GitHub App after installing it, existing installations do not receive the permissions automatically. Open the app’s installation settings for each organization or account and accept the new permissions before using them in an action.
Troubleshooting
Actions use the wrong organization or repositories
Check that the installation ID in the connection matches the installation for the expected organization and repositories. You can find the installation ID in the app’s installation settings URL.
An action returns a permission error
Check the permissions configured for the GitHub App and the repositories available to its installation. If you added permissions after installing the app, open the installation settings and accept the new permission request.
Further reading
Additional helpful documentation, links, and articles:
Do you have questions or feedback? Join the #workflows or #app-builder channel on the Datadog Community Slack.