Sign InGet Started

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 a Cloud Agent or launch a Cloud Agent, the GitHub Connection is what lets the agent push commits and open pull requests against the repo.

One GitHub App installation can include multiple repositories. You add another GitHub Connection only if you need a different GitHub App installation or account.

What It Syncs

  • Files and content — The contents of files in the repository at the specified branch, indexed for AI search and context.
  • Repository structure — Directory layout and file organization.
  • Code symbols — Functions, classes, and other named symbols extracted from 27 programming languages (Python, JavaScript/TypeScript, Go, Rust, C++, Java, C#, Ruby, PHP, Swift, Kotlin, Scala, Clojure, Haskell, Elixir, Erlang, Perl, R, MATLAB, Groovy, VB.NET, F#, Objective-C, D, and others).

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

Hamster uses the GitHub App for authentication. This method is more secure and easier than manual token management — you authorize via GitHub's standard OAuth flow, and Hamster requests only the permissions it needs.

Initial Setup

  1. Go to Workspace Settings > Connections and click the GitHub card.
  2. Click Install and Connect GitHub.
  3. You'll be redirected to GitHub to authorize the Hamster App.
  4. Select your GitHub account — Choose the account (personal or organization) where your repository lives.
  5. Grant permissions — Review and approve the requested permissions (repository contents, pull requests, commit statuses).
  6. GitHub will redirect you back to Hamster.
  7. Select repositories — Hamster opens a repository selector where you can choose which repositories to connect:
    • Free plan — You can connect 1 repository per installation.
    • Paid plan — You can connect up to 100 repositories per installation.
    • If you connect just one repository that fits your plan limit, the Connection is added immediately.
    • If you try to exceed your plan limit, Hamster shows an upsell dialog allowing you to upgrade before confirming.

Fresh Installation

If you're installing the GitHub App for the first time, Hamster shows the repository picker so you can confirm which repos to index and, for each one, which branch to track. You can always adjust which repos are indexed (or switch branches) from the Connections page later.

Using an Existing GitHub App Installation

If the GitHub App is already installed in your account (perhaps you've used it with another tool or in another workspace):

  1. Hamster detects the existing installation(s) and presents an installation chooser.
  2. Select the installation you want to adopt for Hamster.
  3. The repository selection dialog opens.
  4. Choose which repositories to sync (subject to your plan limit).

You can use the same GitHub App installation across multiple Hamster workspaces. Each workspace independently chooses which repositories to index.

Per-Repository Configuration

Once connected, you can manage each repository independently:

  1. Go to Workspace Settings > Connections > GitHub and select a Connection.
  2. Branch selection — Each repository can track a different branch. By default, Hamster uses GitHub's default branch for that repository (usually main), but you can override it:
    • Click the repository to expand its settings.
    • Select a different branch to track (e.g., develop or staging).
    • Hamster will sync code from that branch instead.
  3. Remove a repository — Click the repository and select "Remove from sync" to stop indexing it (without affecting the Connection).

Connection Health and Error Messages

Hamster validates the Connection and shows status for each repository:

  • Indexed — The repository is successfully synced and indexed.
  • Indexing — Hamster is currently pulling and analyzing the code.
  • Error — Something went wrong. Click to see the specific error (e.g., "Repository not found", "Insufficient permissions"). You can try re-syncing from this state.

If OAuth fails during the initial setup (e.g., timeout, network error, or user cancellation), Hamster shows an error message and allows you to retry.

Managing the Connection

Modify Repositories

Go to Connections > GitHub and expand your Connection to add or remove repositories. Removing a repository stops its sync but doesn't delete the Connection.

Reconnect if Token Expires

GitHub OAuth tokens are long-lived, but they can expire or be revoked. If Hamster detects that your token is no longer valid:

  1. A Reconnect required badge appears on the GitHub Connection.
  2. Click the Connection card and authorize again via GitHub.
  3. Your existing repository selections are preserved.
  4. Sync resumes immediately.

Removing the Connection

Click the GitHub Connection card and select Remove. This:

  • Stops syncing and indexing repository code.
  • Uninstalls the GitHub App from your Hamster workspace (but the App remains installed in your GitHub account).
  • Does not delete any Briefs, Tasks, or other data.
  • Allows you to reconnect later.

Code Indexing and Search

Hamster indexes repository code to enable the AI to answer questions about your codebase. The indexing process:

  1. Reads files and extracts code symbols (functions, classes, constants, etc.) from 27 languages.
  2. Builds a full-text search index of code, comments, and file paths.
  3. Stores results in your workspace's Knowledge.
  4. Completes within minutes for most repositories (depending on size and complexity).

When you ask the AI a question, it searches this index to find the most relevant code snippets and context.

Re-syncing

If significant changes have been made to your codebase, you can manually trigger a re-sync from the Connections page. This re-indexes all code and updates the AI's context. Re-syncs typically take a few minutes.

Working with Cloud Agents

GitHub Connections are the foundation for Delivery in Hamster:

  • A Cloud Agent attaches one or more GitHub repositories and uses them to boot a sandbox snapshot. Briefs that target those repositories can deliver in parallel into the Agent's snapshot.
  • A delivery runs against the selected repository and branch, pushes its delivery branch, and opens a pull request under the Hamster GitHub App bot identity. The pull request body records the teammate who launched the delivery.

Delivery resolves short-lived installation credentials per request and does not store them in job payloads.

GitHub App Permissions

The Hamster GitHub App uses these repository permissions for indexing and delivery:

Permission Purpose Scope
Repository contents Read repository code and push delivery branches Read-write
Pull requests Open and update delivery pull requests Read-write
Metadata Identify the installation and selected repositories Read-only

GitHub shows the requested permissions during installation. Hamster does not receive GitHub Actions secret values or access to repository settings and security policies.

Tips

  • Use descriptive Connection names when connecting multiple repositories. "API" and "Frontend" are more useful than "Repo 1" and "Repo 2".
  • Track the branch you develop on — Usually main or develop, not a feature branch.
  • One installation can include multiple repos. Add another Connection only if you need a different GitHub App installation or account, each with its own branch.
  • The AI uses repository content as context, not code execution. 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.
  • Plan limits are enforced at Connection time. Trying to exceed your repository limit shows a clear upsell dialog, and you can upgrade before confirming additional repositories.

Related