Skip to main content
The GitHub feed connects an index to one or more GitHub repositories. Authentication uses a personal access token (PAT) that you generate in GitHub and paste into Circuit. After connecting, Circuit imports the files in the repositories the token can read and keeps them in sync as they change.

​
What you can do

  • Sync source files, markdown, and configuration: Anything stored in the repository tree is eligible for import.
  • Cover multiple repositories: A single token can grant access to several repositories in one feed.
  • Sync from public or private repositories: As long as the token has read access, the repository can be imported.
  • Stay in sync automatically: Circuit re-checks each repository periodically. New commits, file changes, and deletions are mirrored to the index.

​
Before you start

  • A GitHub account with read access to the repositories you want to sync.
  • If the repositories belong to an organization, check whether your org requires approval for fine-grained PATs. See For IT and security teams below.
  • An index in Circuit where the GitHub content should live. See Indexes if you need to create one.
GitHub offers two kinds of personal access tokens. Use fine-grained tokens when possible:
Token typeWhen to use itNotes
Fine-grained PAT (recommended)Most casesPer-repository selection, granular permissions, maximum 366-day expiry, org-level approval policy.
Classic PATRepositories in organizations that have not enabled fine-grained PATs, or unusual scope requirementsBroad repo scope grants access to every repository the user can read, including private ones.

​
Connect GitHub

1

Generate a fine-grained personal access token in GitHub

In GitHub, open Settings > Developer settings > Personal access tokens > Fine-grained tokens, then click Generate new token.Configure the token as follows:
  • Token name: something recognizable, for example Circuit feed: docs repos.
  • Expiration: up to 366 days. GitHub does not allow longer expirations for fine-grained PATs.
  • Resource owner: your personal account or the organization that owns the repositories.
  • Repository access: Only select repositories, then choose the repositories you want Circuit to read.
  • Repository permissions: set Contents to Read-only and Metadata to Read-only. Leave everything else at No access.
Click Generate token and copy the token. GitHub only shows it once.
2

Open the index's Integrations tab in Circuit

In Circuit, open the index that should receive the GitHub content, then choose Integrations > New integration.
3

Choose Import from GitHub

Select Import from GitHub.
4

Paste the token and choose the repositories

Paste the PAT into the Token field. Circuit verifies the token and lists the repositories it can read. Select the repositories you want imported into the index.
5

Start the import

Click Save. Circuit imports the chosen repositories. The initial import takes a few minutes to a few hours depending on repository size. Subsequent updates run in the background.

​
What Circuit accesses

Circuit uses the token you generate. For a fine-grained PAT, the recommended permissions are:
PermissionAccessWhy Circuit needs it
ContentsRead-onlyRead files and commit history from the selected repositories.
MetadataRead-onlyList branches, default branch, repository visibility, and similar metadata. This permission is mandatory for any fine-grained PAT and cannot be turned off.
For a classic PAT, the repo scope works. It is broader than necessary, because it also grants write access to every repository the user can see. Prefer fine-grained tokens whenever the target organization supports them.
Circuit only reads from the repositories the token grants access to. The token itself is the boundary: there is no separate in-app picker. To remove a repository from the feed, regenerate the token without it (or revoke the token and issue a new one).

​
For IT and security teams

The GitHub feed uses a user-issued personal access token rather than an OAuth flow, so there is no enterprise application to consent to. Two GitHub-side controls are relevant:
  • PAT policy for org-owned repos: Organization owners can require approval for fine-grained PATs that target org-owned repositories. When the policy is on, any new Circuit token stays in a Pending state and can only read public resources until an org owner approves it. Approval is configured at Settings > Third-party Access > Personal access tokens in the organization.
  • Token expiry: Fine-grained PATs expire after at most 366 days. Plan to rotate the token before it expires, or syncs will start failing with 401 Unauthorized.
For broader cross-integration security details, see Integration security and admin consent.

​
Disconnect or rotate access

  • From Circuit: open the index’s Integrations tab, select the GitHub feed, and click Remove. Circuit deletes the stored token and stops syncing. Already-imported documents stay in the index until you delete them.
  • From GitHub: at Settings > Developer settings > Personal access tokens, find the token and click Delete. Any sync attempt after that point fails. Generate a new token, then open the Circuit feed and click Reconnect to paste it in.
  • Org-wide revocation: an organization owner can revoke any fine-grained PAT that targets org resources from Settings > Third-party Access > Personal access tokens in the organization.

​
Troubleshooting

The token is invalid, expired, or was copied incorrectly. Generate a new token in GitHub and paste it again. Make sure you copied the full token, which starts with github_pat_ for fine-grained tokens or ghp_ for classic tokens.
The token does not have access to that repository. Edit the token in GitHub, add the repository under Repository access, and reconnect in Circuit. For org-owned repos, the token may also be pending approval (see For IT and security teams).
Your token is missing Contents: Read or Metadata: Read for one of the selected repositories. Edit the token and add the missing permissions.
Fine-grained PATs expire after at most 366 days. Generate a new token in GitHub and click Reconnect in the Circuit feed.
Updates are picked up on the next sync cycle, usually within a few hours. If the file remains out of date for longer, force a re-sync from the feed’s settings.

​
Reference