> ## Documentation Index
> Fetch the complete documentation index at: https://specterops-bp-2735-release-notes.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure the Collector

> Configure the GitHub collector to gather data from your GitHub organization or enterprise.

export const source_0 = "GitHub"

export const env_0 = "organization or enterprise account"

<img noZoom src="https://mintcdn.com/specterops-bp-2735-release-notes/2djt2Sp9UeFPjBFr/assets/enterprise-AND-community-edition-pill-tag.svg?fit=max&auto=format&n=2djt2Sp9UeFPjBFr&q=85&s=a791748158fde5ff3b3b82b51497ab39" alt="Applies to BloodHound Enterprise and CE" width="482" height="45" data-path="assets/enterprise-AND-community-edition-pill-tag.svg" />

This page covers configuring the OpenHound GitHub collector for your GitHub organization or enterprise account. Use this page to choose an authentication method and configure the collector settings in the `secrets.toml` file or environment variables.

## Prerequisites

* OpenHound installed with the GitHub collector included.

  Follow the OpenHound [installation](/openhound/community) instructions to set up OpenHound for BloodHound Community Edition. The GitHub collector is included by default in the OpenHound container image.
* One of the following authentication setups configured:
  * [Enterprise GitHub App installation](/openhound/collectors/github/configure-enterprise-app) (<Badge color="green">recommended</Badge>)
  * [Organization GitHub App installation](/openhound/collectors/github/configure-app)
  * [Fine-grained Personal Access Token (PAT)](/openhound/collectors/github/configure-pat)

<Note>The OpenHound setup instructions for BloodHound Community Edition also apply to BloodHound Enterprise users, for now.</Note>

## Configure OpenHound

The GitHub collector needs different settings based on the authentication method you choose. You can set those values in one of two places:

| Method                | Set the values here                           |
| --------------------- | --------------------------------------------- |
| `secrets.toml` file   | `[sources.source.github.credentials]` section |
| Environment variables | `SOURCES__SOURCE__GITHUB__CREDENTIALS`        |

Click the tab that matches your authentication setup for details and example configurations.

<Tabs>
  <Tab title="Enterprise GitHub App">
    Use this option when you need enterprise-scoped collection.

    | Setting           | Description                                                            | Environment Variable                                    |
    | ----------------- | ---------------------------------------------------------------------- | ------------------------------------------------------- |
    | `client_id`       | The GitHub App Client ID used to authenticate to the GitHub API.       | `SOURCES__SOURCE__GITHUB__CREDENTIALS__CLIENT_ID`       |
    | `app_id`          | The GitHub App ID used to authenticate to the GitHub API.              | `SOURCES__SOURCE__GITHUB__CREDENTIALS__APP_ID`          |
    | `key_path`        | The path to the GitHub App private key file.                           | `SOURCES__SOURCE__GITHUB__CREDENTIALS__KEY_PATH`        |
    | `enterprise_name` | The slug of the GitHub enterprise to collect data from.                | `SOURCES__SOURCE__GITHUB__CREDENTIALS__ENTERPRISE_NAME` |
    | `api_uri`         | The GitHub API base URI. For GitHub.com, use `https://api.github.com`. | `SOURCES__SOURCE__GITHUB__CREDENTIALS__API_URI`         |

    **`secrets.toml`**

    ```toml title="secrets.toml" theme={null}
    [sources.source.github.credentials]
    client_id = "your-client-id"
    app_id = "your-app-id"
    key_path = "/path/to/private/key.pem"
    enterprise_name = "your-enterprise-slug"
    api_uri = "https://api.github.com"
    ```

    **Environment variables**

    ```text theme={null}
    SOURCES__SOURCE__GITHUB__CREDENTIALS__CLIENT_ID=your-client-id
    SOURCES__SOURCE__GITHUB__CREDENTIALS__APP_ID=your-app-id
    SOURCES__SOURCE__GITHUB__CREDENTIALS__KEY_PATH=/path/to/private/key.pem
    SOURCES__SOURCE__GITHUB__CREDENTIALS__ENTERPRISE_NAME=your-enterprise-slug
    SOURCES__SOURCE__GITHUB__CREDENTIALS__API_URI=https://api.github.com
    ```
  </Tab>

  <Tab title="Organization GitHub App">
    Use this option for organization-scoped collection with higher GitHub API rate limits.

    | Setting     | Description                                                      | Environment Variable                              |
    | ----------- | ---------------------------------------------------------------- | ------------------------------------------------- |
    | `org_name`  | The name of the GitHub organization to collect data from.        | `SOURCES__SOURCE__GITHUB__CREDENTIALS__ORG_NAME`  |
    | `app_id`    | The GitHub App ID used to authenticate to the GitHub API.        | `SOURCES__SOURCE__GITHUB__CREDENTIALS__APP_ID`    |
    | `client_id` | The GitHub App Client ID used to authenticate to the GitHub API. | `SOURCES__SOURCE__GITHUB__CREDENTIALS__CLIENT_ID` |
    | `key_path`  | The path to the GitHub App private key file.                     | `SOURCES__SOURCE__GITHUB__CREDENTIALS__KEY_PATH`  |

    **`secrets.toml`**

    ```toml title="secrets.toml" theme={null}
    [sources.source.github.credentials]
    org_name = "your-github-org"
    key_path = "/path/to/private/key.pem"
    app_id = "123456"
    client_id = "your-client-id"
    ```

    **Environment variables**

    ```text theme={null}
    SOURCES__SOURCE__GITHUB__CREDENTIALS__ORG_NAME=your-github-org
    SOURCES__SOURCE__GITHUB__CREDENTIALS__KEY_PATH=/path/to/private/key.pem
    SOURCES__SOURCE__GITHUB__CREDENTIALS__APP_ID=123456
    SOURCES__SOURCE__GITHUB__CREDENTIALS__CLIENT_ID=your-client-id
    ```
  </Tab>

  <Tab title="Fine-grained PAT">
    Use this option for smaller environments or testing.

    | Setting    | Description                                                                          | Environment Variable                             |
    | ---------- | ------------------------------------------------------------------------------------ | ------------------------------------------------ |
    | `org_name` | The name of the GitHub organization to collect data from.                            | `SOURCES__SOURCE__GITHUB__CREDENTIALS__ORG_NAME` |
    | `token`    | The fine-grained Personal Access Token (PAT) used to authenticate to the GitHub API. | `SOURCES__SOURCE__GITHUB__CREDENTIALS__TOKEN`    |

    **`secrets.toml`**

    ```toml title="secrets.toml" theme={null}
    [sources.source.github.credentials]
    org_name = "your-github-org"
    token = "github_pat_xxxxxxxxxxxxx"
    ```

    **Environment variables**

    ```text theme={null}
    SOURCES__SOURCE__GITHUB__CREDENTIALS__ORG_NAME=your-github-org
    SOURCES__SOURCE__GITHUB__CREDENTIALS__TOKEN=github_pat_xxxxxxxxxxxxx
    ```
  </Tab>
</Tabs>

## Running OpenHound and Collecting Data

After you set the required configuration parameters, [run](/openhound/community#collect) OpenHound to start the {source_0} collector and collect data from your {source_0} {env_0}. The collector will generate JSON files in the output directory that can be uploaded to BloodHound for analysis.

<Note>
  Large GitHub organizations or enterprises can trigger GitHub's API rate limits during collection. If you see failed or retried requests, tune the [HTTP request parameters](/openhound/configuration#http-request-parameters) to ride out rate limits instead of failing the run.
</Note>