# How to connect GitLab to Hermes Agent (no API keys)

> Connect GitLab to Hermes with ClawLink in one click — 58 tools your AI agent can call from chat via hosted OAuth. No API keys, no manual setup.

Web version: https://claw-link.dev/hermes/gitlab

Most guides for giving Hermes Agent GitLab access start with registering your own OAuth app or pasting API keys into env files, then leave the token refresh and tool wiring to you. ClawLink gives Hermes a more practical GitLab setup: pair once in the browser and your always-on Hermes agent can act on GitLab for you, reading and doing real work on your behalf with no auth, token refresh, or tool wiring to build yourself.

**Start here — paste this into Hermes to set up ClawLink:**

> Set up ClawLink for Hermes and tell me when it's ready.
> 1. Install the plugin: `hermes plugins install ClawLink-HQ/hermes-plugin --enable`
> 2. Start pairing with `hermes clawlink begin`. It prints an approval link, so show me the link and stop, don't wait.
> 3. I'll approve it in my browser, then reply "approved".
> 4. When I say approved, finish setup: `hermes clawlink finish`
> 5. Then run `hermes clawlink test` and tell me whether ClawLink is ready.

## Setup

It takes three steps to connect Hermes to GitLab.

1. **Install ClawLink** — add the plugin to Hermes Agent once.
2. **Connect GitLab** — one-click OAuth in the ClawLink dashboard.
3. **Use it from chat** — ask Hermes Agent in plain English.

**Alternative for any agent (no plugin needed):** if the Hermes Agent plugin route isn't available or doesn't work, any AI agent with shell access can use the ClawLink CLI instead:

```bash
npx -y @useclawlink/cli login          # sign in via browser — no API key to paste
npx -y @useclawlink/cli connect gitlab  # connect GitLab (browser OAuth)
npx -y @useclawlink/cli actions gitlab  # list available actions
npx -y @useclawlink/cli run gitlab <action> --input '<json>'  # execute (add --confirm for writes)
```

### Install by command

The prompt above walks Hermes through this. By hand, it is four commands and a browser approval:

```bash
hermes plugins install ClawLink-HQ/hermes-plugin --enable
hermes clawlink begin    # prints an approval link — open it and approve
hermes clawlink finish   # after approving in the browser
hermes clawlink test
```

Then connect GitLab in the [ClawLink dashboard](https://claw-link.dev/dashboard) — a one-click OAuth approval, no API keys.

Verify the connection by asking Hermes:

> Run gitlab_get_projects and list my projects, then for each one run gitlab_get_project_merge_requests with state=opened. Tell me which projects have open merge requests, who authored them, and which have been waiting longest. Do not modify anything.

### Using a different agent?

The Hermes plugin is one client of ClawLink's MCP server. Claude Code, Cursor, Codex, or any agent that can run a shell command pairs with the same ClawLink account through the CLI:

```bash
npx -y @useclawlink/cli login
```

`login` opens the same browser approval and stores a credential locally. Once GitLab is connected in the dashboard, that agent calls the same 58 GitLab tools over MCP. Full setup for MCP clients and shell agents: [connect apps to any AI agent](https://claw-link.dev/learn/connect-apps-to-any-ai-agent).

## GitLab MCP for Hermes

Looking for a GitLab MCP server for Hermes Agent? ClawLink connects GitLab to Hermes Agent and exposes 58 GitLab tools your agent can call over [MCP](https://claw-link.dev/learn/what-is-an-mcp-server), with [hosted auth](https://claw-link.dev/learn/oauth-for-ai-agents) and nothing to run or maintain yourself. Using OpenClaw instead? The [OpenClaw GitLab integration](https://claw-link.dev/openclaw/gitlab) works the same way.

The setup every search result teaches for GitLab plus Hermes starts with a command line: the AI Overview walks searchers through installing the Composio CLI, asking Hermes to authenticate, and editing ~/.hermes/config.yaml by hand. ClawLink is the other route: you pair Hermes in the browser once, connect GitLab with one OAuth approval, and the 58 tools below are callable from chat with nothing installed and no config file to keep in sync. That is the whole difference, and it is the reason the 403, token, and tool-not-found advice you will read elsewhere mostly does not apply here, because most of it assumes a token file or an MCP server exists on your machine.

## The official GitLab MCP server, and where this fits

The comparison engines actually teach on the MCP queries, because the official server is the answer they reach for.

- **GitLab's official MCP server is a thing you run.** Its setup is OAuth Dynamic Client Registration plus a locally running server, which is why the search results for "best gitlab mcp server" are all about running it, configuring it, and fixing it. Nothing in this page is run or configured by you.
- **The hosted option never appears in the comparison.** Every roundup we measured (the s10 AIO table included) compares official against community servers; a hosted, zero-maintenance connection is a category the engines do not know exists.
- **Which to pick is a real fork.** If you want GitLab access for coding agents running next to your projects, the official server is the reference. If you want one Hermes agent with GitLab plus dozens of other apps from one connection, this page's setup is the smaller amount of work.

If a self-hosted GitLab or an MCP server you control is a hard requirement, this integration is not that, and it is better to know it before connecting.

## What the Hermes Agent GitLab integration can do

58 GitLab tools are ready for Hermes Agent once the account is connected. The 30 below are the ones people reach for most; your agent can call all 58.

### 30 of 58 GitLab tools for Hermes

| Tool | What it does |
|---|---|
| **Archive project** `gitlab_archive_project` | Tool to archive a project. Use when you need to mark a project read-only after finishing active development. Call after confirming no further changes are required. |
| **Create group** `gitlab_create_group` | Tool to create a new group in GitLab. Use when you need to establish a new group for projects or collaboration. |
| **Create project** `gitlab_create_project` | Tool to create a new project in GitLab. Implements POST /projects endpoint. |
| **Create project issue** `gitlab_create_project_issue` | Tool to create a new issue in a GitLab project. Use when you need to report a bug, request a feature, or track a task within a specific project. |
| **Create repository branch** `gitlab_create_repository_branch` | Tool to create a new branch in a project. Use when you need to create a new branch from an existing branch or a specific commit in a GitLab project. |
| **Download project avatar** `gitlab_download_project_avatar` | Tool to download a project's avatar image. Use when you need the raw avatar bytes after confirming the project exists. |
| **Erase job** `gitlab_erase_job` | Tool to erase the content of a specified job within a project. Use when you need to remove job artifacts and logs. |
| **Get commit refs** `gitlab_get_commit_refs` | Tool to get all references (branches or tags) a commit is pushed to. Use when you need to find out which branches or tags a specific commit belongs to in a GitLab project. |
| **Get commit sequence** `gitlab_get_commit_sequence` | Tool to get the sequence number of a commit in a project by following parent links from the given commit. Use when you need to determine the order of a commit in the project's history. |
| **Get group** `gitlab_get_group` | Tool to retrieve information about a specific group by its ID. Use when you need to get details of a GitLab group. |
| **Get group member** `gitlab_get_group_member` | Tool to retrieve details for a specific group member. Use when you need to fetch membership information for a user in a group after you know both group ID and user ID. |
| **Get groups** `gitlab_get_groups` | Get Groups |
| **Get job details** `gitlab_get_job_details` | Retrieve details of a single job by its ID within a specified project |
| **Get merge request notes** `gitlab_get_merge_request_notes` | Fetch comments on a merge request |
| **Get project** `gitlab_get_project` | Get a single project by ID or URL-encoded path |
| **Get project languages** `gitlab_get_project_languages` | List programming languages used in a project with percentages |
| **Get project member** `gitlab_get_project_member` | Retrieve details for a specific project member |
| **Get project member all** `gitlab_get_project_member_all` | Retrieve details for a specific project member (including inherited and invited members) |
| **Get project merge request** `gitlab_get_project_merge_request` | Fetch full details for a single merge request when the MR IID is known |
| **Get project merge request commits** `gitlab_get_project_merge_request_commits` | Get commits of a merge request |
| **Get project merge requests** `gitlab_get_project_merge_requests` | Retrieve a list of merge requests for a specific project |
| **Get projects** `gitlab_get_projects` | List all projects accessible to the authenticated user |
| **Get projects ID merge requests iid diffs** `gitlab_get_projects_id_merge_requests_iid_diffs` | List all diff versions of a merge request |
| **Get repository branch** `gitlab_get_repository_branch` | Retrieve information about a specific branch in a project |
| **Get repository branches** `gitlab_get_repository_branches` | Retrieves a list of repository branches for a project |
| **Get single commit** `gitlab_get_single_commit` | Get a specific commit identified by the commit hash or name of a branch or tag |
| **Get single pipeline** `gitlab_get_single_pipeline` | Retrieve details of a single pipeline by its ID within a specified project |
| **Get user** `gitlab_get_user` | Retrieve information about a specific user by their ID |
| **Get user preferences** `gitlab_get_user_preferences` | Get the current user's preferences |
| **Get user status** `gitlab_get_user_status` | Get the current user's status |

## Example prompts

**List projects with open merge requests**

> Run gitlab_get_projects and list my projects, then for each one run gitlab_get_project_merge_requests with state=opened. Tell me which projects have open merge requests, who authored them, and which have been waiting longest. Do not modify anything.

**Triage an issue**

> List the issues in the GitLab project I name with gitlab_list_project_issues. Group them by label, tell me which are unassigned, and draft a reply for the two oldest that looks like a maintainer wrote it. Show me the drafts before you post them.

**Report a pipeline failure**

> Run gitlab_list_project_pipelines for my project, open the latest failed pipeline with gitlab_get_single_pipeline, then gitlab_list_pipeline_jobs. Tell me which job failed, quote its error output, and suggest the fix.

**Summarize a merge request**

> Open merge request 88 in my project with gitlab_get_project_merge_request and its diff with gitlab_get_projects_id_merge_requests_iid_diffs. Summarize what changed file by file and flag anything touching authentication or migrations before I review it.

## What the 58 GitLab tools cover

The set is the GitLab REST surface as tools, grouped so you can see the shape before connecting.

- **Projects and repositories**: create, archive, and delete projects; list and search projects (gitlab_get_projects applies membership: true by default); branches, tags, commits, and project housekeeping.
- **Merge requests and issues**: list and fetch merge requests with diffs and notes, create and update issues, and comment on requests through gitlab_get_merge_request_notes.
- **CI/CD**: list pipelines and jobs, fetch single pipeline and job details, and erase job artifacts and logs with gitlab_erase_job.
- **Groups and members**: create groups, list group projects, share a project with a group, and manage group and project members including invited and inherited membership.
- **Users and status**: get user preferences and status, list users, and set or clear the connected user's GitLab status from chat.

## ClawLink vs. building it yourself

The alternative to ClawLink is usually manual OAuth app setup plus your own token handling, permission troubleshooting, and tool plumbing for Hermes Agent. That is fine if you want to build and maintain the integration yourself. Most teams just want GitLab working from chat.

| | Manual | ClawLink |
|---|---|---|
| **Connection flow** | Register a GitLab app, configure redirect URLs, manage consent details, and reconnect users when auth settings drift. | Users connect GitLab through the hosted browser flow and ClawLink keeps the token lifecycle out of your app code. |
| **Ongoing maintenance** | You own refresh logic, permission debugging, environment config, and every provider-specific edge case for GitLab. | ClawLink handles the repetitive integration plumbing so your team can focus on the workflow instead of the infrastructure. |
| **Agent usability** | You still need to expose the right GitLab actions to the runtime in a format your agent can reliably use. | 58 tools for GitLab are already exposed through ClawLink, so the agent can read and act from chat immediately. |

## ClawLink vs. Composio

Composio also exposes GitLab to AI agents. It is developer infrastructure: Python and TypeScript SDKs, an MCP server, and a catalog past 1,000 apps, aimed at teams shipping agent products. ClawLink is built for Hermes Agent users instead. You install the plugin once, connect GitLab in the browser, and the 58 tools above work from chat. There is no SDK, no config file, and no API key handling. Choosing between them? Read the full [Composio alternatives](https://claw-link.dev/hub/composio-alternatives) comparison.

### Hermes paired but still can't use GitLab
Pairing is a two-step handshake: run `hermes clawlink begin`, approve the link in your browser, then run `hermes clawlink finish`. If you ran finish before approving, or the approval link expired, run `hermes clawlink begin` again to get a fresh link. Confirm the plugin was installed with `--enable`, then verify with `hermes clawlink test`.

### Connection succeeds but no tools appear
Reconnect GitLab from the dashboard, then start a fresh chat if the runtime still has the old tool catalog loaded.

### "Tool schema not loaded yet" error when calling GitLab tools
GitLab tool schemas load on demand the first time a tool runs and are cached after that, so this error usually clears on its own: wait a few seconds and retry the same request. If every GitLab call keeps failing with it in a fresh chat, reconnect from the dashboard, and contact support if it still persists — that pattern points to a configuration problem on our side, not something you can fix by reconnecting again.

### GitLab returns 403 or "permission denied" on one action while others work
Two usual causes. The connected account may not have access to the specific workspace, inbox, store, or project in the request — check that first. If access looks right, the agent may have sent a placeholder value (like "YOUR_ID" or an example id from documentation) instead of a real one: ask it to run a list or search tool first, then retry the action with a real id from those results. Most failures at this stage are one of these two, not ClawLink bugs.

### GitLab returns 403 "insufficient permissions" on a project the connected account should reach
Every engine answer for this error assumes a personal access token you can inspect: token scopes, user role, IP allowlist, project feature toggles. On a hosted connection there is no token to inspect, so start from the request instead. The most common cause is the membership boundary: gitlab_get_projects defaults to membership: true, so an agent that lists projects and then acts on a project outside that list hits a 403, and the list itself never shows the problem. The second is a feature boundary: GitLab returns 403 on a public project when the feature is disabled there, such as merge requests on a read-only mirror, and no scope change fixes that. The third is an IP allowlist on the project or group. List projects first with gitlab_get_projects, retry only with projects from that list, and check whether the failing feature is enabled for your role before touching the connection.

### GitLab MCP tool not found
The answer engines give for this is a Claude Desktop bug: rename the "gitlab" key in claude_desktop_config.json. There is no local config file in this setup, so that fix does not apply. Here, tool schemas load on demand the first time a tool runs, and a call made before the catalog is hydrated returns exactly this shape of error; retrying once normally resolves it. If the same name fails twice, the name is wrong rather than missing, and the error message lists the closest real tools. Retrying with one of those works. If every GitLab call fails in a fresh chat, reconnect from the dashboard rather than debugging a local server that does not exist.

### GitLab API rate limit exceeded
gitlab.com applies request budgets per IP and per account, and an agent that loops lists (list projects, then one call per project, then per merge request) can exhaust the per-minute budget in a few seconds of enumeration. The response is a 429 with a Retry-After value; the fix is waiting for the reset, not reconnecting. To avoid the loop in the first place, ask for targeted queries instead of enumerate-everything calls: one gitlab_get_project_merge_requests call for the repository you care about beats walking every repository you can see.

### OAuth finished in the browser but the account is still missing
Try reconnecting GitLab and complete the consent flow in the same browser session. Partial OAuth approvals or switching accounts mid-flow can leave the connection incomplete.

### Is there a Hermes Agent GitLab integration?
Yes. ClawLink is the fastest way to connect Hermes to GitLab: link your GitLab account once in the browser and Hermes Agent can call the GitLab API through 58 ready-made tools — no custom code or token handling.

### How do I connect GitLab to Hermes with ClawLink?
Install the plugin with `hermes plugins install ClawLink-HQ/hermes-plugin --enable`, then pair once: run `hermes clawlink begin`, approve the link in your browser, and run `hermes clawlink finish`. Connect GitLab in the dashboard and Hermes can use it from the next message — no config files or API keys to manage.

### How long does it take to connect GitLab to Hermes Agent?
About two minutes. Sign in, click Connect next to GitLab in the dashboard, authenticate, and Hermes Agent can use it from the next chat message.

### Why use ClawLink instead of wiring GitLab up myself?
The alternative to ClawLink is usually manual OAuth app setup plus your own token handling, permission troubleshooting, and tool plumbing for Hermes Agent. That is fine if you want to build and maintain the integration yourself. Most teams just want GitLab working from chat.

### Do I need a GitLab personal access token?
No. This connection is a hosted OAuth grant against gitlab.com, so there is no personal access token with read_repository or api scopes to create, paste, rotate, or revoke. GitLab's own no-PAT answer is its official MCP server using OAuth Dynamic Client Registration, which still asks you to run the server or be on a GitLab version where the feature is enabled. Nothing runs on your side here, and the grant appears under your GitLab account's authorized applications where you can revoke it.

### Which projects can the agent reach?
The projects your GitLab account is a member of. gitlab_get_projects defaults to membership: true when the field is omitted, so a listing returns your projects rather than the public firehose of all of gitlab.com; pass membership: false deliberately only to browse public projects. Organization-level access works as your account does: a group you were never added to stays invisible, and GitLab hides private resources you cannot see behind 404 rather than 403, which can look like a typo when it is actually an access boundary.

### Is it safe to connect GitLab to an AI agent?
The risk every engine names on this question is the over-privileged token: one long-lived credential with api scope that keeps working until someone revokes it. This connection removes that specific failure, because no token file exists on the machine running your agent and the OAuth grant is revocable from your GitLab account. What it does not change is that the agent acts as you: a merge request comment or issue description written by anyone can carry instructions aimed at the agent. Treat write actions as reviewable work, and keep protected-branch rules on anything that matters.

### Does this work with a self-hosted GitLab instance?
No. The connection targets gitlab.com. A self-hosted GitLab instance behind your own network is not reachable through this flow, and the MCP servers that do target one need a token you manage and a network path to the instance.

### Hermes paired but still can't use GitLab
Pairing is a two-step handshake: run `hermes clawlink begin`, approve the link in your browser, then run `hermes clawlink finish`. If you ran finish before approving, or the approval link expired, run `hermes clawlink begin` again to get a fresh link. Confirm the plugin was installed with `--enable`, then verify with `hermes clawlink test`.

## Related

- [SafetyCulture](https://claw-link.dev/hermes/safetyculture) — SafetyCulture (formerly iAuditor) is a workplace operations platform that enables teams to conduct digital inspections, manage audits, track issues, schedule tasks, and maintain compliance through mobile and web applications.
- [Hermes LaunchDarkly integration](https://claw-link.dev/hermes/launch-darkly) — A feature management platform that helps teams build better software faster using feature flags.
- [Hermes Crowdin integration](https://claw-link.dev/hermes/crowdin) — Manage translations, localization projects, and language resources