Connect a GitLab project so the AI can reference your code and its structure — and so Delivery can open merge requests against it.
The GitLab Connection gives Hamster two things at once:
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.
Delivering to GitLab with Cloud Agents needs a Team or Enterprise plan, because Cursor Agents and OpenAI Agents deliver only to GitHub. The Hamster plugin delivers from your own checkout on any plan. See Billing.
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.
After you confirm your first selection, Hamster shows GitLab is Connected.
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 dialog.
If you click Cancel on GitLab, or authorization fails, Hamster shows "Couldn't connect to GitLab. Please try again." If you close the GitLab window before you finish, close the Continue to GitLab dialog too. Start again from the GitLab Repos tile.
This recording predates the Continue to GitLab dialog and GitLab's sign-in step.
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 drop out of code search, without affecting the Connection itself. Hamster keeps what it already indexed, so selecting a project again picks it back up. Archived projects show Archived on GitLab and can't be selected.
Only members who can manage connections see the GitLab Repos tile or can open a connected card's picker.
If the GitLab account belongs to more than 5,000 projects, counting projects it reaches through groups, the picker shows Couldn't load repositories with the message connection_repository_list_too_large. Connect with a GitLab account that belongs to fewer projects, such as a dedicated account added only to the projects Hamster needs.
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. You can't deliver to an empty project. Delivery stops and asks you to push an initial commit first.
Code updates normally appear after a push to the tracked branch. Hamster adds a webhook to each project you select so GitLab can tell Hamster about changes. Pushes to other branches and branch deletions don't update the index.
If the account that authorized the Connection isn't a Maintainer on a project, Hamster still indexes it but can't add its webhook. Updates then take longer to appear, and the project's activity can't start Routines. See Who Can Push.
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.
Index stale means Hamster hasn't confirmed recently that the project is up to date. Hamster checks again automatically. Hover over Indexed to see when a project was last indexed.
If the connected GitLab card shows Reconnect to continue syncing, click it and choose Reconnect GitLab. GitLab asks you to sign in. Sign in as the GitLab account you first connected with, and Hamster keeps your project selections. If you sign in as a different account, Hamster adds a second GitLab card, and the first one still needs reconnecting. If you can't manage connections, the card reads Ask an admin or creator on this account to reconnect instead.
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. If you clear every project, the button reads Stop indexing repositories. Confirming stops indexing all of them and keeps the Connection. To change which branch a project tracks, reopen the picker and choose a different one.
To remove the connection, hover over the connected GitLab card, click ×, then click Delete. You need permission to manage connections. Hamster stops indexing every project from that GitLab account and removes the indexed code.
Hamster also deletes the webhooks it added to your projects. To revoke Hamster's access on GitLab too, remove Hamster from the authorized applications in your GitLab user settings. If Hamster's access had already expired or was revoked, Hamster can't delete them, so delete them yourself from each project's Settings > Webhooks on GitLab.
If you rename a project or move it to another group, you don't need to reconnect it.
Delivery pushes as the GitLab account that authorized the Connection, so that account opens the merge request. It needs Developer access or higher on the project, directly or through its group. Without it, delivery stops and asks you to "Grant the connected GitLab account Developer access on this project, then retry delivery."
Delivery branches start with hamster/, and commits are authored as Hamster Agent (agent@tryhamster.com). If a protected branch or push rule on the project blocks that branch name or author, allow both before you deliver.
If a connected project is archived later, delivery stops with "The GitLab project is archived or otherwise read-only." Unarchive the project or deliver to a writable one, then retry.
You don't need Maintainer to connect, but without it a project updates more slowly and can't start Routines. To approve a merge request from Review, your GitLab account needs permission to approve merge requests on the project.
Deliver to GitLab with Hamster Cloud, which runs on Cloud Agents and needs an active or trialing Team or Enterprise plan. Without one, choosing it opens an upgrade prompt titled Cloud delivery is part of Team. See Choosing a delivery method.
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, even though the delivery thread's card calls it one. If a merge request is already open for that branch, Hamster reuses it instead of opening a second one.
The merge request description lists the Brief's tasks, links back to the Brief in Hamster, and names the teammate who triggered the delivery.
The merge request is linked back to the Brief that produced it. In the Brief header, the merge request control shows Draft, Open, Merged, or Closed and links out to GitLab. To link a merge request Hamster didn't open, select its project in the GitLab picker first, then see Link a Pull Request by Hand.
If your team has no GitHub connection, Deliver shows Connect a GitHub repository, even with GitLab connected. Ask for the delivery in the Brief's chat instead and name the project, for example "Deliver to mygroup/myproject with Hamster Cloud".
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. Until you do, Review says "Comments and approvals stay in Hamster until you sign in." Click Sign in with GitLab. If your sign-in expires, click Reconnect GitLab.
You can't approve a merge request you opened, and every merge request Hamster delivers opens under the GitLab account your team connected, so sign in to Review with your own GitLab account. Review also disables Ready when your GitLab account can't see the project. Ask for access to the project on GitLab.
Anyone else on the team, including a Reviewer, can approve it, as long as their GitLab account can approve merge requests on the project. If you started the delivery, ask one of them.
Review doesn't show GitLab pipelines. Check them on GitLab.
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. If nothing is connected, that list reads "No GitHub repositories connected." On GitLab, the triggers fire like this:
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.
The project must finish its first index before you can import from it. If nothing is connected yet, the dialog says Connect GitHub to import skills and offers Connect GitHub. Connect your project from the GitLab Repos tile instead.
Import from GitHub only takes public GitHub links, so it can't read a GitLab project.
main or develop, not a feature branch.