> ## Documentation Index
> Fetch the complete documentation index at: https://docs.circuit.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# GitHub

> Sync repository contents from GitHub into a Circuit index using a personal access token.

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](#for-it-and-security-teams) below.
* An index in Circuit where the GitHub content should live. See [Indexes](/admin/indexes) if you need to create one.

GitHub offers two kinds of personal access tokens. Use fine-grained tokens when possible:

| Token type                         | When to use it                                                                                       | Notes                                                                                              |
| ---------------------------------- | ---------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| **Fine-grained PAT** (recommended) | Most cases                                                                                           | Per-repository selection, granular permissions, maximum 366-day expiry, org-level approval policy. |
| **Classic PAT**                    | Repositories in organizations that have not enabled fine-grained PATs, or unusual scope requirements | Broad `repo` scope grants access to every repository the user can read, including private ones.    |

## Connect GitHub

<Steps>
  <Step title="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.
  </Step>

  <Step title="Open the index's Integrations tab in Circuit">
    In Circuit, open the index that should receive the GitHub content, then choose **Integrations** > **New integration**.
  </Step>

  <Step title="Choose Import from GitHub">
    Select **Import from GitHub**.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## What Circuit accesses

Circuit uses the token you generate. For a fine-grained PAT, the recommended permissions are:

| Permission   | Access    | Why Circuit needs it                                                                                                                                        |
| ------------ | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Contents** | Read-only | Read files and commit history from the selected repositories.                                                                                               |
| **Metadata** | Read-only | List 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.

<Note>
  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).
</Note>

## 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](/it/integration-security).

## 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

<AccordionGroup>
  <Accordion title="&#x22;Bad credentials&#x22; or &#x22;401 Unauthorized&#x22; when saving the token">
    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.
  </Accordion>

  <Accordion title="A repository is missing from the selection list">
    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](#for-it-and-security-teams)).
  </Accordion>

  <Accordion title="&#x22;Resource not accessible by personal access token&#x22; in sync errors">
    Your token is missing **Contents: Read** or **Metadata: Read** for one of the selected repositories. Edit the token and add the missing permissions.
  </Accordion>

  <Accordion title="Sync stops working after about a year">
    Fine-grained PATs expire after at most 366 days. Generate a new token in GitHub and click **Reconnect** in the Circuit feed.
  </Accordion>

  <Accordion title="A file was updated in GitHub but the index still shows the old content">
    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.
  </Accordion>
</AccordionGroup>

## Reference

* **Authentication**: GitHub personal access token (PAT), supplied by the user
* **Recommended token type**: fine-grained PAT with **Contents: Read-only** and **Metadata: Read-only**
* **Classic PAT scope (if fine-grained is not available)**: `repo`
* **API endpoint**: `https://api.github.com`
* **GitHub's own docs**: [Managing your personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens), [Permissions required for fine-grained PATs](https://docs.github.com/en/rest/authentication/permissions-required-for-fine-grained-personal-access-tokens), [Setting a personal access token policy for your organization](https://docs.github.com/en/organizations/managing-programmatic-access-to-your-organization/setting-a-personal-access-token-policy-for-your-organization)