GitHub

Authentication methods

Personal Access Token

Read the official docs to learn how to generate a token.

API scopes

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

OAuth App

Read the official docs 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 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

• Pull Requests

• Pull Request Comments

• Pull Request Commits

Inbound Syncs

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

Stream	Sync strategies	Notes
commits	Full Refresh, Incremental	Commits across the selected repos and branches. Incremental tracks per-branch HWM.
pull_requests	Full Refresh, Incremental	Pull requests across the selected repos.
pull_request_comments	Full Refresh, Incremental	Review comments and conversation comments on pull requests.
pull_request_commits (depends on pull_requests)	Full Refresh, Incremental	Commits associated with each pull request. Populated as a by-product of pull_requests.
pull_request_events (depends on pull_requests)	Full Refresh, Incremental	Timeline events on pull requests (assignments, label changes, merges, etc.).
repositories	Full Refresh, Incremental	Repository metadata for everything that matches Repository Pattern.
branches	Full Refresh	Branches matching Branch Pattern, per repository.
organization_members	Full Refresh	Members of the selected organisation.
organization_teams	Full Refresh	Teams in the selected organisation.
organizations	Full Refresh	The selected organisation itself.

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.