Configure an Organization GitHub App

Create a GitHub App in a GitHub organization for OpenHound data collection.

This page covers creating a GitHub App in a GitHub organization for OpenHound data collection. GitHub App installations provide a higher API rate limit of 15,000 requests per hour compared to 5,000 for Personal Access Tokens (PATs).

If you need enterprise-scoped collection for GitHub Enterprise, use Configure an Enterprise GitHub App.

Install a GitHub App

Follow these steps to create and configure a GitHub App for a single GitHub organization.

1. Navigate to GitHub Apps

   Navigate to your Organization Settings > Developer settings > GitHub Apps.

2. Click New GitHub App

   Click the New GitHub App button.

3. Configure the app

   1. Configure the app with the following settings:

      • GitHub App name: Choose a unique name (e.g., YourOrg-OpenHound)

      • Homepage URL: We recommend pointing to the OpenHound GitHub repository

      • Webhook: Clear Active because OpenHound does not require a webhook for collection

      • Permissions: Set the following permissions to Read-only:

        Show required permissions

        Repository permissions

        • Actions
        • Administration
        • Contents
        • Environments
        • Metadata
        • Secret scanning alerts
        • Secrets
        • Variables

        Organization permissions

        • Administration
        • Custom organization roles
        • Custom repository roles
        • Members
        • Personal access tokens
        • Personal access token requests
        • Secrets
        • Self-hosted runners
        • Variables

   2. Under Where can this GitHub App be installed?, select Only on this account.

4. Create the app

   Click Create GitHub App to create the app with the specified settings and permissions.

5. Generate a private key

   Scroll down and click Generate a private key. Save the downloaded .pem file securely and record the App ID and Client ID shown on the app settings page.

6. Install the app

   Click Install App in the left sidebar to install the app to your organization.

Get the Installation Details

1. Navigate to your Organization Settings > Third-party Access > GitHub Apps.
2. Find the app you just created and click Configure.
3. The numeric value in the URL is the App Installation ID.
4. Click App settings to access the Client ID and App ID.

Security Considerations

• Store the .pem private key securely and never commit it to version control.
• Rotate keys periodically and revoke old ones.
• Only install the app on organizations that require collection.
• Periodically verify the app has only the minimum required permissions.

Next Steps

After installing and configuring the GitHub App, proceed to configure the collector to start collection.