GitHub

Connect a GitHub repository so the AI can reference your code, structure, and history — and so Cloud Agents can ship pull requests against it.

Overview

The GitHub Connection gives Hamster two things at once:

Read access for the AI. Once connected, the AI can answer questions about the codebase, reference file structure and content when generating Briefs, and ground its suggestions in the repo you're actually working on.
A Delivery target. When you configure or launch a Cloud Agent, the GitHub Connection is what lets the agent push commits and open pull requests against the repo.

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

Go to Workspace Settings > Connections and click the GitHub card.
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.
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:

Go to GitHub > Settings > Developer settings > Personal access tokens > Fine-grained tokens.
Click Generate new token.
Under Repository access, select the specific repository.
Under Permissions, set Contents and Metadata to Read-only.
Generate the token and copy it — you won't 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.

If you intend to use the same Connection for Delivery through Cloud Agents, grant write access on Contents and Pull requests as well, so agents can push commits and open PRs.

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.

Working with Cloud Agents

GitHub Connections are the foundation for Delivery in Hamster:

A Cloud Agent attaches one or more GitHub repos and uses them to boot a sandbox snapshot.
Briefs, Tasks, Routines, and Slack slash flows can launch Delivery into any active Cloud Agent that has the right repo attached.
The Cloud Agent executes the work in a sandbox and opens a pull request authored by the user who launched it.

Both flows resolve credentials per-request and never store them in job payloads. PRs are attributed back to the human who triggered the delivery.

Keeping Data Current

GitHub data is synced on connection. If significant changes have been made to the codebase since you connected, 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. Common warnings include "missing push access" or "missing pull request access" — both required if the Connection will be used for Delivery. Catching incomplete permissions up front avoids a failed Delivery later.

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. Code execution happens inside Cloud Agent sandboxes when you deliver a Brief.
Pair GitHub with Linear or Jira so the AI can correlate issues with the code changes that address them.