> ## Documentation Index
> Fetch the complete documentation index at: https://bloodhound.specterops.io/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.

export const source_0 = "GitHub"

export const env_0 = "organization"

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

This page covers downloading and running the OpenHound GitHub collector against your GitHub organization.

## 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.
* A [Personal Access Token (PAT)](/openhound/collectors/github/configure-pat) or [GitHub App Installation](/openhound/collectors/github/configure-app) configured with the required permissions

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

## Required Permissions

Both PAT and GitHub App authentication methods require the same set of Read-only permissions. The table below maps each permission to the collection functions it enables.

### 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
* Variables

## Configure OpenHound

The following OpenHound configuration parameters are required to run the Github collector. These can either be set
via the `[sources.source.github.credentials]` section of the secrets file or via environment variables using the `SOURCES__GITHUB__CREDENTIALS` prefix.

### Option 1: Github app installation

| Parameter Name | Environment Variable    | Description                                                      |
| -------------- | ----------------------- | ---------------------------------------------------------------- |
| `org_name`     | \{PREFIX}\_\_ORG\_NAME  | The name of the GitHub organization to collect data from.        |
| `app_id`       | \{PREFIX}\_\_APP\_ID    | The GitHub App ID used to authenticate to the GitHub API.        |
| `client_id`    | \{PREFIX}\_\_CLIENT\_ID | The GitHub App Client ID used to authenticate to the GitHub API. |
| `key_path`     | \{PREFIX}\_\_KEY\_PATH  | The path to the GitHub App private key file.                     |

### Option 2: Fine-grained Personal Access Token (PAT)

| Parameter Name | Environment Variable   | Description                                                                          |
| -------------- | ---------------------- | ------------------------------------------------------------------------------------ |
| `org_name`     | \{PREFIX}\_\_ORG\_NAME | The name of the GitHub organization to collect data from.                            |
| `token`        | \{PREFIX}\_\_TOKEN     | The fine-grained Personal Access Token (PAT) used to authenticate to the GitHub API. |

### Example Configuration

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

## 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.