Docs
Connections

GitHub

Connect github.com with a read-only fine-grained personal access token and read repositories, commits, pull requests, issues, releases and Actions runs.

A GitHub connection reads github.com repositories with a fine-grained personal access token that has read-only permissions. It calls only api.github.com. For the tables, columns and limits that every forge shares, see the Git overview.

Preview

Git connections are in Preview and are enabled on request: contact support@xentropy.ai. Until GitHub is enabled for your account it is not offered in the forge selector, and its reads fail with PROVIDER_DISABLED.

Create a read-only token

Use a fine-grained personal access token (it starts with github_pat_). It can be limited to the repositories you choose and to read-only access.

On GitHub, open Settings → Developer settings → Personal access tokens → Fine-grained tokens and choose Generate new token.
Name the token and set an expiration date.
Choose the Resource owner: your account, or the organization that owns the repositories.
Under Repository access, choose Only select repositories and pick the repositories to read, or choose All repositories.
Under Repository permissions, set the permissions in the table below to Read-only. Leave everything else at No access.
Generate the token and copy it.

If the organization requires approval for fine-grained tokens, the token can read its private repositories only after an organization owner approves it.

Token permissions

The form lists these permissions with a copy button.

PermissionUnlocks
Metadata: Read-onlyRepositories, branches, tags, contributors. GitHub always adds it
Contents: Read-onlyCommits and releases
Pull requests: Read-onlyPull requests
Issues: Read-onlyIssues
Actions: Read-onlyWorkflow runs (pipeline_runs)

You can leave out a permission for a resource you will not read. Reading that resource then fails at the permissions stage and names the missing permission.

Set up the connection

Open Connections, choose New connection, then Git, and choose GitHub.
Name the connection and paste the token.
Choose Test connection. The stages are Authentication (the token) and Repository access. The test lists the repositories the token can read.
Choose the repositories to allow, or none to allow every repository the token can read. Choose Save connection.
Open the connection, choose a resource, repositories and a date range, pick fields, preview 100 rows and save a dataset.

Connect with GitHub (sign-in through a GitHub App, with per-repository consent) appears only when GitHub sign-in is available for your account. Until then, connect with a token as above.

Resources

ResourceAvailableNotes
repositoriesYesRepositories the token can read
commitsYesThe default branch, or the branch you choose, in the date range
pull_requestsYesAll states; merged comes from the merge time
issuesYesPull requests are left out
releasesYesGitHub lists draft releases only to tokens that can push, so a read-only token does not see drafts
tagsYes
branchesYes
contributorsYesAll-time commit counts from GitHub; anonymous contributors are left out
pipeline_runsYesGitHub Actions workflow runs

Columns left empty

GitHub's list endpoints do not return these columns, so they are always empty. Xentropy does not make one extra request per row to fill them.

ResourceEmpty columns
commitsadditions, deletions
pull_requestsadditions, deletions, changed_files, comments
tagstagged_at
contributorsname, email

Limits

A fine-grained token has 5,000 requests per hour, shared by every tool that uses the same GitHub account. GitHub also has a secondary rate limit on bursts of requests. Xentropy reads the x-ratelimit-* headers and waits for the reset when the budget runs out. See Limits and refresh for pages, rows and deadlines.

Errors

ResponseCodeCauseWhat to do
401PROVIDER_ACCESS_DENIED, stage authThe token expired, was revoked, or was mistypedGenerate a new token and choose Replace configuration
403PROVIDER_ACCESS_DENIED, stage permissionsA permission is missing. details.missingScopes names it, for example Pull requests: Read-onlyEdit the token on GitHub, set the permission to Read-only, then test again
404NOT_FOUNDThe repository does not exist, or the token cannot see it. GitHub answers 404, not 403, for a private repository outside the token's accessAdd the repository to the token's Repository access, or ask an organization owner to approve the token
RedirectNOT_FOUNDThe repository moved or was renamedSelect the repository under its new name
403 or 429 with rate limit headersRATE_LIMITEDThe hourly or secondary rate limit is used upRetry after details.retryAt; scheduled refreshes wait by themselves

An empty repository reads as no rows, not as an error.

On this page