Sign InGet Started

GitHub

Connect a GitHub repository so the AI can reference your code, structure, and history.

Overview

The GitHub connection gives the AI read access to a specific repository in your workspace. Once connected, the AI can answer questions about the codebase, reference file structure and content when generating briefs, and provide more relevant suggestions when your work involves code.

You connect one repository at a time. You can add multiple GitHub connections if your project spans several repositories.

What It Syncs

  • Files and content — The contents of files in the repository at the specified branch
  • Repository structure — Directory layout and file organisation

GitHub uses a full sync model: data is indexed on connection and can be refreshed manually at any time from your connections page.

How to Connect

  1. Go to Settings > Connections and click the GitHub card.
  2. In the dialog, fill in the following:
    • Connection name — A label for this connection (e.g. "Main Repository" or "Frontend")
    • Repository — The repository in owner/repo format (e.g. acme/web-app)
    • Branch — The branch to sync (defaults to main)
    • Personal Access Token — A GitHub token with read-only access to the repository
  3. Click Connect Repository.

The connection appears in your active connections list and the data is indexed immediately.

Creating a Personal Access Token

You need a GitHub Personal Access Token (PAT) with the following permissions:

  • Contents: Read-only
  • Metadata: Read-only

To create one:

  1. Go to GitHub > Settings > Developer settings > Personal access tokens > Fine-grained tokens.
  2. Click Generate new token.
  3. Under Repository access, select the specific repository.
  4. Under Permissions, set Contents and Metadata to Read-only.
  5. Generate the token and copy it — you will not be able to see it again.

The Connect GitHub dialog includes a direct link that pre-fills these settings for the repository owner you enter.

Multiple Repositories

If your project spans multiple repositories, add a separate GitHub connection for each one. Give each connection a descriptive name so you can identify them on the connections page.

Keeping Data Current

GitHub data is synced on connection. If significant changes have been made to the codebase since you connected, you can trigger a manual re-sync from the connections page to pull in the latest content.

Connection Health Warnings

Hamster validates token capabilities and shows warning badges when a GitHub token is missing key scopes (for example, push or pull request access). This helps you spot incomplete permissions before running workflows that depend on those capabilities.

Tips

  • Use descriptive connection names when connecting multiple repositories. "API" and "Frontend" are more useful than "Repo 1" and "Repo 2".
  • Connect the branch that reflects your current active development — usually main or develop, not a feature branch.
  • If the repository is private, the token must have access to that specific repo. Organisation-level tokens with broad access also work.
  • The AI uses repository content as context, not as a code execution environment. It reads and references code but does not run it.

Related