> For the complete documentation index, see [llms.txt](https://docs.omnata.com/omnata-product-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.omnata.com/omnata-product-documentation/omnata-sync-for-snowflake/apps/github.md).

# GitHub

## Authentication methods

#### Personal Access Token

Read the [official docs](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) to learn how to generate a token.

<figure><img src="/files/VV5WvKHIYAu2r8AQuzCl" alt=""><figcaption></figcaption></figure>

**API scopes**

The token needs scope to read `repo` to access the below objects.

#### **OAuth App**

Read the [official docs](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/creating-an-oauth-app) to learn how to create a GitHub OAuth App and generate an OAuth token.

**API scopes**

The OAuth App requires the following scopes:

* `repo` — grants access to repository data including commits, branches, pull requests, and pull request comments
* `read:org` — grants read-only access to organisation membership and team data

#### **GitHub App (organisation-owned)**

A [GitHub App](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app) owned by a GitHub organisation can also be used to authenticate. This is the recommended approach for teams that require organisation-level credential ownership and do not want authentication tied to an individual user account.

The connector authenticates using a user access token generated via the GitHub App's OAuth flow. To set this up, generate a user access token from your GitHub App and provide it during connection configuration in the same way as a Personal Access Token.

**Required permissions**

GitHub Apps use fine-grained permissions rather than OAuth scopes. Configure the following permissions on your GitHub App:

| Permission        | Level                               | Required for                                               |
| ----------------- | ----------------------------------- | ---------------------------------------------------------- |
| **Contents**      | Read-only                           | Commits, Branches, Repositories                            |
| **Pull requests** | Read-only                           | Pull Requests, Pull Request Comments, Pull Request Commits |
| **Metadata**      | Read-only                           | Automatically required for all repository access           |
| **Members**       | Read-only (Organisation permission) | Organisation, Organisation Members, Organisation Teams     |

## Inbound Syncs

The following streams are supported, with Full Refresh and Incremental strategies:

* [Commits](https://docs.github.com/en/rest/commits/commits?apiVersion=2022-11-28)
* [Pull Requests](https://docs.github.com/en/rest/pulls/pulls?apiVersion=2022-11-28)
* [Pull Request Comments](https://docs.github.com/en/rest/pulls/comments?apiVersion=2022-11-28)
* [Pull Request Commits](https://docs.github.com/en/rest/pulls/pulls?apiVersion=2022-11-28#list-commits-on-a-pull-request)

### Inbound Syncs

The plugin supports ten streams. All operate within the selected organisation and, where applicable, the repositories matched by **Repository Pattern**.

<table><thead><tr><th>Stream</th><th>Sync strategies</th><th>Notes</th><th data-hidden>Primary key</th><th data-hidden>Default cursor</th><th data-hidden>Depends on</th></tr></thead><tbody><tr><td><code>commits</code></td><td>Full Refresh, Incremental</td><td>Commits across the selected repos and branches. Incremental tracks per-branch HWM.</td><td><code>sha</code></td><td><code>last_commit_date</code></td><td>—</td></tr><tr><td><code>pull_requests</code></td><td>Full Refresh, Incremental</td><td>Pull requests across the selected repos.</td><td><code>id</code></td><td><code>updated_at</code></td><td>—</td></tr><tr><td><code>pull_request_comments</code></td><td>Full Refresh, Incremental</td><td>Review comments and conversation comments on pull requests.</td><td><code>id</code></td><td><code>updated_at</code></td><td>—</td></tr><tr><td><code>pull_request_commits</code> <sub>(depends on pull_requests)</sub></td><td>Full Refresh, Incremental</td><td>Commits associated with each pull request. Populated as a by-product of <code>pull_requests</code>.</td><td>composite <code>pull_request_id</code> + <code>commit_sha</code></td><td><code>commit_sha</code></td><td><code>pull_requests</code></td></tr><tr><td><code>pull_request_events</code> <sub>(depends on pull_requests)</sub></td><td>Full Refresh, Incremental</td><td>Timeline events on pull requests (assignments, label changes, merges, etc.).</td><td><code>id</code></td><td><code>updated_at</code></td><td><code>pull_requests</code></td></tr><tr><td><code>repositories</code></td><td>Full Refresh, Incremental</td><td>Repository metadata for everything that matches <strong>Repository Pattern</strong>.</td><td><code>id</code></td><td><code>updated_at</code></td><td>—</td></tr><tr><td><code>branches</code></td><td>Full Refresh</td><td>Branches matching <strong>Branch Pattern</strong>, per repository.</td><td><code>name</code></td><td>—</td><td>—</td></tr><tr><td><code>organization_members</code></td><td>Full Refresh</td><td>Members of the selected organisation.</td><td>composite <code>id</code> + <code>organization_id</code></td><td>—</td><td>—</td></tr><tr><td><code>organization_teams</code></td><td>Full Refresh</td><td>Teams in the selected organisation.</td><td>composite <code>id</code> + <code>organization_id</code></td><td>—</td><td>—</td></tr><tr><td><code>organizations</code></td><td>Full Refresh</td><td>The selected organisation itself.</td><td><code>id</code></td><td>—</td><td>—</td></tr></tbody></table>

## Outbound Syncs

There is currently no outbound sync functionality for GitHub. If you have a use case, please let us know!

## Managing performance

#### GitHub API rate limits

GitHub enforces request-rate limits per authenticating identity:

| Authentication type                               | Limit                |
| ------------------------------------------------- | -------------------- |
| Personal Access Token / OAuth user token          | 5,000 requests/hour  |
| GitHub App user access token (Enterprise account) | 15,000 requests/hour |

A large sync against many repositories can approach these limits, especially when several incremental-capable streams (`commits`, `pull_requests`, `pull_request_comments`, `pull_request_events`) run together. GitHub returns `403 Forbidden` with `X-RateLimit-Remaining: 0` in the response header when you exhaust the bucket; the plugin surfaces this in the sync run log.

If you see rate-limit errors, options in increasing order of effort are: reduce the number of streams selected per sync, split repositories across multiple syncs (each with a narrower `repository_pattern`), or stagger sync schedules so concurrent syncs don't compete for the same bucket.

## Troubleshooting

**"Connection failed" on the connect step**

* Confirm the credential type matches the connection method you selected (a PAT pasted into the OAuth flow won't work, and vice versa).
* For a PAT, confirm the token has the **`repo`** and **`read:org`** scopes (Classic PAT) or the equivalent fine-grained permissions, and that it hasn't expired.
* For a fine-grained PAT or GitHub App, confirm the token is scoped to the organisation and to the repositories you intend to sync.
* For OAuth, the user who authorises the connection must be a member of every organisation the sync needs to reach.

**Some repositories are missing from a sync**

* Check the **Repository Pattern** value — remember it's a `re.match` pattern, so the start of the name must match.
* For fine-grained PATs and GitHub Apps, confirm the token is authorised against the repositories that aren't appearing. Tokens scoped to a subset of repositories silently exclude the rest.
* The authenticating user (or GitHub App) must have read access to the repository. Private repositories that the token can't see will not appear.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.omnata.com/omnata-product-documentation/omnata-sync-for-snowflake/apps/github.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.