GitLab

Connect a GitLab project so the AI can reference your code and its structure — and so Delivery can open merge requests against it.

Overview

The GitLab 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 project you're actually working on.
  • A delivery target. When you deliver a Brief against a connected GitLab project, Hamster pushes a delivery branch and opens a merge request on it.

GitLab connects with an OAuth grant, not an app install, so one Connection covers every project the authorizing GitLab user is a member of. You add another GitLab Connection only if you need to bring in a second GitLab account.

gitlab.com only. Self-managed GitLab instances are not supported.

What It Syncs

  • Files and content — The contents of files in the project 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.

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

Once a project is indexed, ask about it in Chat and Hamster answers from that code.

How to Connect

  1. Go to Knowledge > Connections in your workspace and click the GitLab Repos tile.
  2. A GitLab consent popup opens straight away. There is no Hamster dialog before it and no personal access token to paste.
  3. Review and approve the access requested on GitLab. Hamster uses it to index your selected projects, keep their code current, and publish delivery changes.
  4. Hamster returns you to the Connections page and opens the repository picker.
  5. Select repositories — Choose which projects to index:
    • Hamster Free plan — You can connect 1 repository across GitHub, GitLab, and Cursor Origin.
    • Paid Hamster plan — The picker lets you connect up to 100 repositories per connection.
    • On the free plan, selecting more than one repository offers you an upgrade before you can confirm.

On the Hamster Free plan, if your workspace already has a repository connected, clicking the GitLab Repos tile opens an upgrade prompt instead of the GitLab popup.

If authorization is cancelled or fails, start again from the GitLab Repos tile.

Repository Selection and Branches

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

Confirming the selection starts indexing each project. Projects you clear from the selection stop syncing and their indexed content is removed, without affecting the Connection itself.

A brand-new project with no commits yet is selectable and connects normally. The first sync finds nothing to index and succeeds anyway, and the first push you make to the tracked branch is picked up and indexed like any other change.

Keeping the Index Fresh

Code updates normally appear after a push to the tracked branch.

Ask for Maintainer access on connected projects so Hamster can pick up code changes promptly. Without it, updates may take longer to appear. Check the connection's indexing status if changes aren't appearing.

Connection Health

The connected GitLab card shows how many repositories are connected and a rollup of indexing state across them: Indexing, Embedding, Indexed, Index stale, or Sync failed. A failed sync surfaces the reason so you can act on it.

If the connected GitLab card shows Reconnect to continue syncing, click it and choose Reconnect GitLab. Your project selections are kept.

Managing the Connection

Click the connected GitLab card to reopen the repository picker. Unlike GitHub, there is no installation to configure on GitLab's side and no Manage on GitLab link — an OAuth grant reaches every project the authorizing user is a member of, so the project selection is the thing you manage from Hamster.

To stop indexing a project, clear it from the selection and confirm. The picker can't confirm an empty selection, so you can't clear the last project. To change which branch a project tracks, reopen the picker and choose a different one.

Delivery and Merge Requests

Delivering a Brief against a connected GitLab project pushes the delivery branch and opens a merge request. It isn't a draft, so reviewers can pick it up right away. If a merge request is already open for that branch, Hamster reuses it instead of opening a second one.

Delivery pushes with the OAuth grant that connected GitLab, so the merge request is opened by the GitLab account that authorized the Connection. Commits are authored as Hamster Agent.

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

You can also start the delivery from chat by asking Hamster to deliver the Brief to your GitLab project.

Review on a Merge Request

Review shows a guided Tour of a delivered GitLab merge request, with file diffs and discussion threads. Sign in with GitLab so your comments and decisions post as you instead of staying in Hamster.

  • Ready approves the merge request on GitLab.
  • Not yet removes your approval and posts your explanation as a discussion note. A comment is required.
  • Reviews written on GitLab appear in Hamster as approvals or discussion notes, rather than a Not yet vote.

Starting Routines

Activity on a connected GitLab project can start a Routine. GitLab uses the GitHub triggers in the trigger picker, and connected projects appear in their Repository list. Only an approval counts as a submitted review. Withdrawing an approval doesn't start anything.

These events arrive through the project webhook, so a project where Hamster couldn't register the hook doesn't start routines.

Importing Skills

From the Skills tab, click New skill and select Sync repo skills, then pick your GitLab project. Hamster reads the SKILL.md files in its .agents/skills/, .claude/skills/, or skills/ folder from the last indexed snapshot and adds them to your Skills library.

Import from GitHub only takes public GitHub links, so it can't read a GitLab project.

Tips

  • Track the branch you develop on — usually main or develop, not a feature branch.
  • Ask for Maintainer on the projects that matter. It lets Hamster pick up code changes promptly and supports event-triggered routines.
  • Connecting a project indexes it, it does not run it. Indexing reads and references the code for context; running code is Delivery's job, not the Connection's.
  • Pair GitLab 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.