GitHub

Connect a GitHub repository so the AI can reference your code and its structure — and so Delivery can open 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 repository you're actually working on.
  • A delivery target. When you deliver a Brief against a connected GitHub repository, Hamster pushes a delivery branch and opens a pull request on it.

GitHub connects by installing the Hamster GitHub App. One 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 branch you select, indexed for AI search and context.
  • Repository structure — Directory layout and file organization.
  • Code symbols — Functions, classes, and other named symbols extracted from 27 supported language and format variants and indexed for AI search and context.

Symbol extraction covers 27 language and format variants: TypeScript and TSX, JavaScript and JSX, Python, Go, Java, C, C++, C#, Rust, Ruby, PHP, Kotlin, Swift, shell scripts, Scala, Dart, Elixir, Lua, Vue, Svelte, Haskell, HTML, CSS, JSON, and TOML. Other indexed text files remain searchable even when they do not have symbol extraction.

Each repository tracks one branch, which you choose when you connect it.

How to Connect

  1. Go to Knowledge > Connections in your workspace and click the GitHub Repos tile. You need permission to manage connections.
  2. Review the access requested, then click Install GitHub App.
  3. On GitHub, choose the account or organization, choose which repositories the app can access, and approve the requested permissions.
  4. GitHub returns you to Hamster and opens the repository picker. Choose the repositories and branches to index, then confirm:
    • Hamster Free plan — Choose 1 repository across GitHub, GitLab, Bitbucket, and Cursor Origin. Selecting more than one offers you an upgrade before you can confirm.
    • Paid Hamster plan — Choose up to 100 repositories.

If installation is cancelled or fails, start again from the GitHub Repos tile.

Using an Existing Installation

If the Hamster GitHub App is already installed on an account or organization you can reach, and this workspace hasn't connected it yet, Hamster shows Connect an existing installation. Pick the installation to connect, or choose Install on a different account. The same installation can be used by multiple Hamster workspaces, and each workspace chooses its own repositories.

Repository Selection and Branches

For each repository you select, choose the branch to track — by default the repository's own default branch. Hamster indexes code from that branch.

Confirming the selection starts indexing each repository. Repositories you clear from the selection stop syncing and drop out of code search, without affecting the Connection itself. Hamster keeps what it already indexed, so selecting a repository again picks it back up.

Keeping the Index Fresh

Code updates normally appear after a push to the tracked branch. If an update is delayed, Hamster checks again automatically. Check the connection's indexing status if changes aren't appearing.

To check whether your repositories are ready, ask Hamster in chat. It reports the same indexing states the Connections page shows, and if a repository is still indexing, Hamster lets you know in the same conversation when it finishes.

Connection Health

Each connected GitHub card is named after the GitHub account or organization where the app is installed. It shows how many repositories are connected and one indexing status across them:

  • Indexing — Hamster is reading the repository.
  • Embedding — Code is being prepared for search; the card shows progress.
  • Indexed — Code is ready to search. Hover over the status to see when it was last indexed.
  • Index stale — The index has not been checked recently; Hamster checks again automatically.
  • Sync failed — Hover over the status to see what went wrong.

Managing the Connection

Click the connected GitHub card to reopen the repository picker, where you add or remove indexed repositories and change each repository's tracked branch. You need permission to manage connections to open it. To stop indexing everything, clear every repository; the button then reads Stop indexing repositories.

The repositories the app can see are chosen on GitHub. Use Manage or uninstall on GitHub on the card, or the GitHub link under the repository list in the picker, to change the installation's access.

To remove the connection, hover over the connected GitHub card, click ×, then click Delete. You need permission to manage connections. Hamster stops syncing and removes the indexed code. Deleting the connection doesn't uninstall the Hamster GitHub App. To uninstall it, use Manage or uninstall on GitHub first; uninstalling disconnects every Hamster workspace that uses that installation. Briefs, Tasks, and other data are kept.

Delivery and Pull Requests

Delivering a Brief with Hamster Cloud against a connected GitHub repository pushes the delivery branch and opens a draft pull request. It stays a draft when the run finishes — mark it ready yourself when you want reviewers on it. If a pull request is already open for that branch, Hamster reuses it instead of opening a second one.

The pull request is opened by the Hamster GitHub App, and the pull request body records the teammate who triggered the delivery.

An OpenAI Agents delivery also opens a draft pull request as the Hamster GitHub App, with the same body.

The pull request is linked back to the Brief that produced it. In the Brief header, the pull request control shows Draft, Open, Merged, or Closed and links out to GitHub.

GitHub App Permissions

Hamster reads repository contents for code context and needs write access to publish delivery branches and pull requests. It also reads reviews, comments, and checks for Review.

GitHub shows the exact permissions requested during installation. Use Manage or uninstall on GitHub to review the installation's permissions and repository access.

GitHub's API returns names and metadata for Actions secrets, but not their values. The GitHub App connection cannot read those stored secret values.

Tips

  • Track the branch you develop on — usually main or develop, not a feature branch.
  • One installation can include multiple repositories. Add another Connection only if you need a different GitHub App installation or account.
  • Connecting a repository indexes it, it does not run it. Cloud Agents run your code when you deliver a Brief.
  • Pair GitHub with Linear or Jira so the issue and the code that addresses it are both in reach when you ask.
  • You can connect GitHub, GitLab, and Cursor Origin side by side. They are separate Connections with separate repository selections.