# GitHub

> Connect GitHub to sanda: what to prepare, the fields the connection form asks for, and how its data lands in your warehouse.

## Connect GitHub

:::steps
1. **Open the catalogue.** In the console, go to **Data · Connections** and press **New connection**.
2. **Choose GitHub.** It is listed under product and operations; you can also search for it by name.
3. **Fill in the form.** Enter the fields below. Credentials go straight to sanda’s sync engine and are never stored in sanda’s database.
4. **Choose what to sync.** Pick the streams you want, and a sync mode for each. See [choose what to sync](https://docs.sanda-os.com.au/connections/choose-streams).
5. **Run the first sync.** sanda tests the connection, then lands each stream as a table in your warehouse.
:::

## Configuration fields

What the connection form asks for. Required fields are marked; the rest are optional.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| **Authentication** | one of 2 options | Yes | Choose how to authenticate to GitHub. |
| **GitHub Repositories** | array | Yes | List of GitHub organizations/repositories, e.g. `your-org/your-repo` for single repository, `your-org/*` for get all repositories from organization and `your-org/a*` for matching multiple repositories by pattern. |
| **Start date** | string | No | The date from which you'd like to replicate data from GitHub in the format YYYY-MM-DDT00:00:00Z. If the date is not set, all data will be replicated. For the streams which support this configuration, only data generated on or after the start date will be replicated. |
| **API URL** | string | No | Please enter your basic URL from self-hosted GitHub instance or leave it empty to use GitHub. Default `https://api.github.com/`. |
| **Branches** | array | No | List of GitHub repository branches to pull commits for, e.g. `your-org/your-repo/master`. If no branches are specified for a repository, the default branch will be pulled. |
| **Max Waiting Time (in minutes)** | integer | No | Max time (in minutes) the connector will wait when all API tokens are rate-limited before failing. GitHub rate limits reset every 60 minutes, so values above 60 allow the connector to wait for a full reset cycle. Default `120`. |
| **Number of Concurrent Threads** | integer | No | Number of concurrent threads for syncing. Higher values can speed up syncs but increase the risk of hitting GitHub's secondary rate limits. Default `4`. |

### Authentication

Choose how to authenticate to GitHub.

Choose one of the following. Each asks for its own fields.

**OAuth**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| **Access Token** | string, secret | Yes | OAuth access token. |
| **Client Id** | string, secret | No | OAuth Client Id. |
| **Client secret** | string, secret | No | OAuth Client secret. |

**Personal Access Token**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| **Personal Access Tokens** | string, secret | Yes | Log into GitHub and then generate a personal access token. To load balance your API quota consumption across multiple API tokens, input multiple tokens separated with ",". |


## Related

:::links
- [Sync modes](https://docs.sanda-os.com.au/connections/sync-modes): How sanda reads each stream on every run.
- [Sync schedules](https://docs.sanda-os.com.au/connections/schedules): How often a connection runs.
- [Allowlist sanda’s address](https://docs.sanda-os.com.au/connections/allowlist): For a system behind a firewall.
- [Troubleshoot connections](https://docs.sanda-os.com.au/connections/troubleshooting): What an error means and how to fix it.
:::