> ## Documentation Index
> Fetch the complete documentation index at: https://prismeai-legacy.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# GitLab
> Manage GitLab projects, issues, merge requests and CI/CD pipelines from Prisme.ai workflows and AI agents
The GitLab app provides read/write access to the [GitLab](https://gitlab.com) DevOps platform via its REST v4 API. It can be used either as a Builder app (automations call GitLab instructions directly) or as a remote MCP server consumed by an AI Knowledge agent — covering projects, issues, merge requests, pipelines, branches, commits, releases, CI/CD variables, deploy keys, webhooks, wikis, groups and users. Supports both static Personal Access Tokens and OAuth2 authorization-code per-user delegation.
Projects, issues, merge requests, labels, milestones and wikis
Pipelines, jobs, environments, CI variables, deploy keys and webhooks
Static PAT shared across the tenant, or OAuth2 per-user delegation (each user signs in with their own GitLab account)
## Prerequisites
* A **GitLab** account (gitlab.com or self-hosted)
* **Either** a Personal Access Token with `api` scope (Preferences > Access Tokens), **or** an OAuth application registered at **User Settings > Applications** (`https://gitlab.com/-/user_settings/applications`) with `api` scope
* Base URL (default: `https://gitlab.com/api/v4` — override for self-hosted instances)
***
## Installation
1. Go to **Apps** in your workspace
2. Search for **GitLab** and install it
3. Open the app instance configuration and fill in the required fields
## Configuration
| Field | Description |
| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| **GitLab API Base URL** | Base URL of the GitLab API (default `https://gitlab.com/api/v4`). Override for self-hosted instances. |
| **Personal Access Token** | GitLab PAT with `api` scope, stored as a workspace secret. Optional if OAuth2 is configured. Passed as `Authorization: Bearer `. |
| **OAuth2 Client ID** | GitLab OAuth Application Client ID. Create an OAuth application at `https://gitlab.com/-/user_settings/applications`. |
| **OAuth2 Client Secret** | OAuth Application Client Secret (shown once on creation), stored as a workspace secret. |
| **OAuth Callback URL** | Auto-populated on install — paste this value into the OAuth application's *Redirect URI* at GitLab. |
| **OAuth Scopes** | Space-separated scopes (default: `api`). |
| **MCP Endpoint** | Auto-populated on install — URL of the MCP endpoint for this instance. |
| **MCP API Key** | Auto-populated on install — signed key used in the `mcp-api-key` header. Do not modify. |
`MCP Endpoint` and `MCP API Key` are generated automatically by the `onInstall` flow and are only needed to expose this instance as an MCP server (see the next tab).
## Available Instructions
Every instruction resolves credentials from the workspace configuration.
### Projects
| Instruction | Arguments |
| ------------------ | --------------------------------------------------------------------------------------------------------- |
| `listProjects` | `search`, `visibility`, `owned`, `membership`, `order_by`, `sort`, `per_page`, `page` |
| `createProject` | `name`\*, `path`, `namespace_id`, `description`, `visibility`, `default_branch`, `initialize_with_readme` |
| `getProject` | `id`\* |
| `updateProject` | `id`\*, `name`, `path`, `description`, `visibility`, `default_branch` |
| `deleteProject` | `id`\* |
| `archiveProject` | `id`\* |
| `unarchiveProject` | `id`\* |
| `forkProject` | `id`\*, `namespace`, `namespace_id`, `name`, `path` |
### Issues
| Instruction | Arguments |
| ----------------- | ---------------------------------------------------------------------------------------------------- |
| `listIssues` | `id`\*, `state`, `labels`, `milestone`, `search`, `assignee_username`, `per_page`, `page` |
| `createIssue` | `id`*, `title`*, `description`, `labels`, `assignee_ids`, `milestone_id`, `confidential`, `due_date` |
| `getIssue` | `id`*, `iid`* |
| `updateIssue` | `id`*, `iid`*, `title`, `description`, `labels`, `assignee_ids`, `milestone_id`, `state_event` |
| `deleteIssue` | `id`*, `iid`* |
| `closeIssue` | `id`*, `iid`* |
| `reopenIssue` | `id`*, `iid`* |
| `listIssueNotes` | `id`*, `iid`*, `sort`, `order_by`, `per_page` |
| `createIssueNote` | `id`*, `iid`*, `body`\*, `confidential` |
| `getIssueNote` | `id`*, `iid`*, `note_id`\* |
| `updateIssueNote` | `id`*, `iid`*, `note_id`*, `body`* |
| `deleteIssueNote` | `id`*, `iid`*, `note_id`\* |
### Merge Requests
| Instruction | Arguments |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `listMergeRequests` | `id`\*, `state`, `source_branch`, `target_branch`, `labels`, `search`, `per_page` |
| `createMergeRequest` | `id`*, `source_branch`*, `target_branch`*, `title`*, `description`, `assignee_ids`, `reviewer_ids`, `labels`, `milestone_id`, `remove_source_branch`, `squash` |
| `getMergeRequest` | `id`*, `iid`* |
| `updateMergeRequest` | `id`*, `iid`*, `title`, `description`, `target_branch`, `assignee_ids`, `labels`, `milestone_id`, `state_event` |
| `deleteMergeRequest` | `id`*, `iid`* |
| `mergeMergeRequest` | `id`*, `iid`*, `merge_commit_message`, `squash_commit_message`, `squash`, `should_remove_source_branch`, `merge_when_pipeline_succeeds`, `sha` |
| `approveMergeRequest` | `id`*, `iid`*, `sha` |
| `unapproveMergeRequest` | `id`*, `iid`* |
| `listMergeRequestNotes` | `id`*, `iid`*, `sort`, `order_by`, `per_page` |
| `createMergeRequestNote` | `id`*, `iid`*, `body`\* |
| `getMergeRequestNote` | `id`*, `iid`*, `note_id`\* |
| `updateMergeRequestNote` | `id`*, `iid`*, `note_id`*, `body`* |
| `deleteMergeRequestNote` | `id`*, `iid`*, `note_id`\* |
### Branches
| Instruction | Arguments |
| -------------- | ---------------------------- |
| `listBranches` | `id`\*, `search`, `per_page` |
| `createBranch` | `id`*, `branch`*, `ref`\* |
| `getBranch` | `id`*, `branch`* |
| `deleteBranch` | `id`*, `branch`* |
### Commits
| Instruction | Arguments |
| ------------------ | ----------------------------------------------------------------------------------------------------------- |
| `listCommits` | `id`\*, `ref_name`, `since`, `until`, `path`, `author`, `per_page` |
| `createCommit` | `id`*, `branch`*, `commit_message`*, `start_branch`, `start_sha`, `author_email`, `author_name`, `actions`* |
| `getCommit` | `id`*, `sha`* |
| `cherryPickCommit` | `id`*, `sha`*, `branch`\*, `dry_run`, `message` |
| `revertCommit` | `id`*, `sha`*, `branch`\*, `dry_run` |
### Tags
| Instruction | Arguments |
| ----------- | ------------------------------------------------ |
| `listTags` | `id`\*, `search`, `order_by`, `sort`, `per_page` |
| `createTag` | `id`*, `tag_name`*, `ref`\*, `message` |
| `getTag` | `id`*, `tag_name`* |
### Releases
| Instruction | Arguments |
| --------------- | --------------------------------------------------------------- |
| `listReleases` | `id`\*, `order_by`, `sort`, `per_page` |
| `createRelease` | `id`*, `name`, `tag_name`*, `description`, `ref`, `released_at` |
| `getRelease` | `id`*, `tag_name`* |
| `deleteRelease` | `id`*, `tag_name`* |
### Pipelines & Jobs
| Instruction | Arguments |
| ------------------ | -------------------------------------------------------------------------- |
| `listPipelines` | `id`\*, `status`, `ref`, `sha`, `username`, `order_by`, `sort`, `per_page` |
| `createPipeline` | `id`*, `ref`*, `variables` |
| `getPipeline` | `id`*, `pipeline_id`* |
| `retryPipeline` | `id`*, `pipeline_id`* |
| `cancelPipeline` | `id`*, `pipeline_id`* |
| `listPipelineJobs` | `id`*, `pipeline_id`*, `scope`, `per_page` |
| `getJob` | `id`*, `job_id`* |
| `retryJob` | `id`*, `job_id`* |
### Environments
| Instruction | Arguments |
| ------------------ | ---------------------------------------------- |
| `listEnvironments` | `id`\*, `name`, `search`, `states`, `per_page` |
| `getEnvironment` | `id`*, `environment_id`* |
| `stopEnvironment` | `id`*, `environment_id`* |
### Labels
| Instruction | Arguments |
| ------------- | -------------------------------------------------------------------------- |
| `listLabels` | `id`\*, `with_counts`, `search`, `per_page` |
| `createLabel` | `id`*, `name`*, `color`\*, `description`, `priority` |
| `updateLabel` | `id`\*, `name`, `label_id`, `new_name`, `color`, `description`, `priority` |
| `deleteLabel` | `id`\*, `name`, `label_id` |
### Milestones
| Instruction | Arguments |
| ----------------- | --------------------------------------------------------------------------------------- |
| `listMilestones` | `id`\*, `state`, `search`, `per_page` |
| `createMilestone` | `id`*, `title`*, `description`, `due_date`, `start_date` |
| `getMilestone` | `id`*, `milestone_id`* |
| `updateMilestone` | `id`*, `milestone_id`*, `title`, `description`, `due_date`, `start_date`, `state_event` |
### Wiki
| Instruction | Arguments |
| ---------------- | ---------------------------------------- |
| `listWikiPages` | `id`\*, `with_content` |
| `createWikiPage` | `id`*, `title`*, `content`\*, `format` |
| `getWikiPage` | `id`*, `slug`*, `render_html`, `version` |
### Webhooks
| Instruction | Arguments |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `listProjectHooks` | `id`\*, `per_page` |
| `createProjectHook` | `id`*, `url`*, `token`, `push_events`, `issues_events`, `merge_requests_events`, `tag_push_events`, `note_events`, `job_events`, `pipeline_events`, `wiki_page_events`, `enable_ssl_verification` |
| `deleteProjectHook` | `id`*, `hook_id`* |
### CI/CD Variables
| Instruction | Arguments |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `listProjectVariables` | `id`\*, `per_page` |
| `createProjectVariable` | `id`*, `key`*, `value`\*, `variable_type`, `protected`, `masked`, `raw`, `environment_scope`, `description` |
| `updateProjectVariable` | `id`*, `key`*, `filter[environment_scope]`, `value`, `variable_type`, `protected`, `masked`, `raw`, `environment_scope`, `description` |
| `deleteProjectVariable` | `id`*, `key`*, `filter[environment_scope]` |
### Deploy Keys
| Instruction | Arguments |
| ----------------- | ------------------------------------ |
| `listDeployKeys` | `id`\*, `per_page` |
| `createDeployKey` | `id`*, `title`*, `key`\*, `can_push` |
| `deleteDeployKey` | `id`*, `key_id`* |
### Project Members
| Instruction | Arguments |
| --------------------- | ------------------------------------------------- |
| `listProjectMembers` | `id`\*, `query`, `per_page` |
| `addProjectMember` | `id`*, `user_id`*, `access_level`\*, `expires_at` |
| `removeProjectMember` | `id`*, `user_id`* |
### Users
| Instruction | Arguments |
| ---------------- | --------------------------------------------------- |
| `getCurrentUser` | – |
| `getUser` | `user_id`\* |
| `listUsers` | `active`, `blocked`, `username`, `per_page`, `page` |
| `searchUsers` | `search`\*, `per_page` |
### Groups
| Instruction | Arguments |
| ------------- | ------------------------------------------------------------------- |
| `listGroups` | `search`, `owned`, `min_access_level`, `top_level_only`, `per_page` |
| `createGroup` | `name`*, `path`*, `description`, `visibility`, `parent_id` |
| `getGroup` | `id`\* |
| `updateGroup` | `id`\*, `name`, `path`, `description`, `visibility` |
Arguments flagged with `*` are required.
## DSUL Examples
### List the user's own projects
```yaml theme={null}
- GitLab.listProjects:
membership: true
order_by: last_activity_at
sort: desc
per_page: 20
output: myProjects
```
### Create an issue with labels and an assignee
```yaml theme={null}
- GitLab.createIssue:
id: '{{projectId}}'
title: Investigate 500s on /api/v1/search
description: |
Spike of 500s since 14:00 UTC. Logs in Kibana (link).
labels: BUG,Incident
assignee_ids:
- '{{oncallUserId}}'
output: issue
```
### Open a merge request from a feature branch
```yaml theme={null}
- GitLab.createBranch:
id: '{{projectId}}'
branch: feature/auto-deploy
ref: main
output: branch
- GitLab.createMergeRequest:
id: '{{projectId}}'
source_branch: feature/auto-deploy
target_branch: main
title: Automate staging deploy
description: Closes #{{issue.iid}}
remove_source_branch: true
output: mr
```
### Trigger a pipeline on a specific ref
```yaml theme={null}
- GitLab.createPipeline:
id: '{{projectId}}'
ref: main
variables:
- key: DEPLOY_ENV
value: staging
output: pipeline
```
The GitLab app ships with a built-in MCP server. Each app instance gets its own signed `mcp-api-key` that encodes the workspace ID and a credentials lookup URL — the GitLab API key itself is never passed through headers and is resolved server-side from the app configuration.
## Legacy MCP Install (Advanced > Tools)
Use this flow to plug the GitLab MCP into an AI Knowledge agent that does not yet support the native MCP picker.
Install and configure the app in the same workspace as your agent (see the *Usage as App* tab). Once configured, `mcpEndpoint` and `mcpApiKey` are auto-populated.
Open the app instance config and copy the values of **MCP Endpoint** and **MCP API Key**.
Navigate to **Advanced > Tools**.
Click **Add** and select the **MCP** tab.
Paste the **MCP Endpoint** URL copied from the app instance.
In the **Headers** field, add the signed API key:
```json theme={null}
{
"mcp-api-key": "your-mcp-api-key"
}
```
The agent can now list and call GitLab tools through the MCP endpoint.
The signed `mcp-api-key` encodes the workspace ID and the `getConfig` webhook URL. The MCP server validates the signature using the central app secret and transparently fetches the GitLab API key and base URL from the installed app. Credentials are cached per tenant for 10 minutes.
## Output Formats
Every tool accepts an `outputFormat` parameter that controls the MCP response shape:
* **`verbose`** (default) — human-readable text for LLM consumption
* **`structured`** — machine-readable JSON in `structuredContent`
* **`both`** — both text and structured content
## Available Tools
### Projects
| Tool | Description |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `listProjects` | List GitLab projects accessible to the authenticated user. **Important**: by default this returns ALL accessible projects including publi... |
| `createProject` | Create a new project. |
| `getProject` | Get a project by ID or URL-encoded namespace/path. |
| `updateProject` | Update an existing project. |
| `deleteProject` | Delete a project. |
| `archiveProject` | Archive a project. |
| `unarchiveProject` | Unarchive a project. |
| `forkProject` | Fork a project into the authenticated user's namespace or given namespace. |
### Issues
| Tool | Description |
| ----------------- | ------------------------------------------------ |
| `listIssues` | List issues of a project. |
| `createIssue` | Create a new issue in a project. |
| `getIssue` | Get a single issue by iid. |
| `updateIssue` | Update an existing issue. |
| `deleteIssue` | Delete an issue. |
| `closeIssue` | Close an issue (via state\_event=close). |
| `reopenIssue` | Reopen a closed issue (via state\_event=reopen). |
| `listIssueNotes` | List notes (comments) of an issue. |
| `createIssueNote` | Create a new note (comment) on an issue. |
| `getIssueNote` | Get a specific note from an issue. |
| `updateIssueNote` | Update an existing issue note. |
| `deleteIssueNote` | Delete an issue note. |
### Merge Requests
| Tool | Description |
| ------------------------ | ------------------------------------------- |
| `listMergeRequests` | List merge requests of a project. |
| `createMergeRequest` | Create a new merge request. |
| `getMergeRequest` | Get a single merge request by iid. |
| `updateMergeRequest` | Update an existing merge request. |
| `deleteMergeRequest` | Delete a merge request. |
| `mergeMergeRequest` | Accept and merge an open merge request. |
| `approveMergeRequest` | Approve a merge request. |
| `unapproveMergeRequest` | Unapprove a merge request. |
| `listMergeRequestNotes` | List notes (comments) of a merge request. |
| `createMergeRequestNote` | Create a note (comment) on a merge request. |
| `getMergeRequestNote` | Get a specific note from a merge request. |
| `updateMergeRequestNote` | Update an existing MR note. |
| `deleteMergeRequestNote` | Delete a merge request note. |
### Branches
| Tool | Description |
| -------------- | -------------------------------------- |
| `listBranches` | List branches of a project repository. |
| `createBranch` | Create a new branch from a ref. |
| `getBranch` | Get a single branch. |
| `deleteBranch` | Delete a branch. |
### Commits
| Tool | Description |
| ------------------ | ---------------------------------------------- |
| `listCommits` | List commits of a project repository. |
| `createCommit` | Create a commit with one or more file actions. |
| `getCommit` | Get a single commit by SHA. |
| `cherryPickCommit` | Cherry-pick a commit onto a target branch. |
| `revertCommit` | Revert a commit on a target branch. |
### Tags
| Tool | Description |
| ----------- | ---------------------------------- |
| `listTags` | List tags of a project repository. |
| `createTag` | Create a new tag from a ref. |
| `getTag` | Get a single tag. |
### Releases
| Tool | Description |
| --------------- | --------------------------------- |
| `listReleases` | List releases of a project. |
| `createRelease` | Create a new release for a tag. |
| `getRelease` | Get a single release by tag name. |
| `deleteRelease` | Delete a release. |
### Pipelines & Jobs
| Tool | Description |
| ------------------ | --------------------------------------- |
| `listPipelines` | List pipelines of a project. |
| `createPipeline` | Trigger a new pipeline for a given ref. |
| `getPipeline` | Get a single pipeline. |
| `retryPipeline` | Retry failed jobs in a pipeline. |
| `cancelPipeline` | Cancel running jobs in a pipeline. |
| `listPipelineJobs` | List jobs belonging to a pipeline. |
| `getJob` | Get a single CI job. |
| `retryJob` | Retry a single job. |
### Environments
| Tool | Description |
| ------------------ | ------------------------------- |
| `listEnvironments` | List environments of a project. |
| `getEnvironment` | Get a single environment. |
| `stopEnvironment` | Stop a running environment. |
### Labels
| Tool | Description |
| ------------- | ------------------------------------------------- |
| `listLabels` | List labels of a project. |
| `createLabel` | Create a new project label. |
| `updateLabel` | Update an existing project label (by name or id). |
| `deleteLabel` | Delete a project label (by name or id). |
### Milestones
| Tool | Description |
| ----------------- | ------------------------------------ |
| `listMilestones` | List milestones of a project. |
| `createMilestone` | Create a new milestone in a project. |
| `getMilestone` | Get a single milestone. |
| `updateMilestone` | Update a milestone. |
### Wiki
| Tool | Description |
| ---------------- | ------------------------------- |
| `listWikiPages` | List wiki pages of a project. |
| `createWikiPage` | Create a new wiki page. |
| `getWikiPage` | Get a single wiki page by slug. |
### Webhooks
| Tool | Description |
| ------------------- | -------------------------- |
| `listProjectHooks` | List project webhooks. |
| `createProjectHook` | Add a new project webhook. |
| `deleteProjectHook` | Delete a project webhook. |
### CI/CD Variables
| Tool | Description |
| ----------------------- | ------------------------------------------ |
| `listProjectVariables` | List CI/CD variables of a project. |
| `createProjectVariable` | Create a new project CI/CD variable. |
| `updateProjectVariable` | Update an existing project CI/CD variable. |
| `deleteProjectVariable` | Delete a project CI/CD variable. |
### Deploy Keys
| Tool | Description |
| ----------------- | ----------------------------------- |
| `listDeployKeys` | List deploy keys of a project. |
| `createDeployKey` | Add a new deploy key to a project. |
| `deleteDeployKey` | Delete a deploy key from a project. |
### Project Members
| Tool | Description |
| --------------------- | ------------------------------------ |
| `listProjectMembers` | List direct members of a project. |
| `addProjectMember` | Add a user as a member to a project. |
| `removeProjectMember` | Remove a member from a project. |
### Users
| Tool | Description |
| ---------------- | ---------------------------------------- |
| `getCurrentUser` | Get the currently authenticated user. |
| `getUser` | Get a single user by ID. |
| `listUsers` | List users (admin-scoped or filtered). |
| `searchUsers` | Search users by name, username or email. |
### Groups
| Tool | Description |
| ------------- | ------------------------------------------------- |
| `listGroups` | List groups accessible to the authenticated user. |
| `createGroup` | Create a new group. |
| `getGroup` | Get a single group by ID or URL-encoded path. |
| `updateGroup` | Update a group. |
### OAuth Session
| Tool | Description |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `disconnect` | Disconnect the current GitLab OAuth session and revoke the access token at the provider (RFC 7009). Only call when the user explicitly as... |
| `connect` | Initiate an OAuth connection to GitLab. Returns a connect\_url for the user to click. \*\*Prefer calling data tools directly (listProjects, ... |
## Tool Details
### createIssue
Open an issue in a GitLab project.
```json theme={null}
{
"name": "createIssue",
"arguments": {
"id": "123456",
"title": "Investigate 500s on /api/v1/search",
"description": "Spike of 500s since 14:00 UTC.",
"labels": "BUG,Incident",
"assignee_ids": [987654]
}
}
```
| Parameter | Required | Description |
| -------------- | -------- | ------------------------------------------------------- |
| `id` | Yes | Project ID (numeric) or URL-encoded `namespace/project` |
| `title` | Yes | Issue title |
| `description` | No | Markdown body |
| `labels` | No | Comma-separated label names |
| `assignee_ids` | No | Array of user IDs |
| `milestone_id` | No | Milestone ID to associate |
| `confidential` | No | `true` to make the issue confidential |
| `due_date` | No | `YYYY-MM-DD` |
### createMergeRequest
```json theme={null}
{
"name": "createMergeRequest",
"arguments": {
"id": "123456",
"source_branch": "feature/auto-deploy",
"target_branch": "main",
"title": "Automate staging deploy",
"description": "Closes #42",
"remove_source_branch": true
}
}
```
`source_branch`, `target_branch` and `title` are required. Accepts `assignee_id`, `reviewer_ids`, `labels`, `milestone_id`, `squash`, `allow_collaboration`.
### createPipeline
Trigger a new pipeline on a given ref. Requires a `.gitlab-ci.yml` at the ref.
```json theme={null}
{
"name": "createPipeline",
"arguments": {
"id": "123456",
"ref": "main",
"variables": [
{ "key": "DEPLOY_ENV", "value": "staging" }
]
}
}
```
| Parameter | Required | Description |
| ----------- | -------- | ------------------------------------------------- |
| `id` | Yes | Project ID |
| `ref` | Yes | Branch or tag to run against |
| `variables` | No | Array of `{key, value, variable_type?}` overrides |
### listProjects
List accessible projects. By default returns ALL accessible projects including public ones. **Pass `membership: true` or `owned: true` to limit to the user's own projects.**
```json theme={null}
{
"name": "listProjects",
"arguments": {
"membership": true,
"order_by": "last_activity_at",
"sort": "desc",
"per_page": 20
}
}
```
| Parameter | Required | Description |
| ------------ | -------- | ---------------------------------------------- |
| `membership` | No | `true` → only projects the user is a member of |
| `owned` | No | `true` → only projects the user owns |
| `search` | No | Free-text filter on project name/path |
| `visibility` | No | `public` / `internal` / `private` |
| `order_by` | No | e.g. `last_activity_at`, `created_at`, `name` |
| `sort` | No | `asc` / `desc` |
| `per_page` | No | 1-100 (default 20) |
### createBranch
```json theme={null}
{
"name": "createBranch",
"arguments": {
"id": "123456",
"branch": "feature/auto-deploy",
"ref": "main"
}
}
```
`ref` is the source branch or commit SHA. To delete a branch later use `deleteBranch` with `{id, branch}`.
### mergeMergeRequest
Merge an open merge request. The MR must be in a mergeable state.
```json theme={null}
{
"name": "mergeMergeRequest",
"arguments": {
"id": "123456",
"iid": 1,
"squash": true,
"should_remove_source_branch": true
}
}
```
Accepts `merge_commit_message`, `squash_commit_message`, `sha` (to fail if HEAD changed).
***
## Error Handling
| HTTP Status | Error | Solution |
| ----------- | ------------ | --------------------------------------------------------------------- |
| 400 | Bad request | Check argument shapes (IDs, dates, enum values) |
| 401 | Unauthorized | Verify the PAT has `api` scope, or re-authorize OAuth |
| 403 | Forbidden | The token lacks permission on this project/group — check access level |
| 404 | Not Found | Verify the project ID (numeric or URL-encoded path) and resource IID |
| 409 | Conflict | Common on merge conflicts or concurrent updates |
| 429 | Rate Limited | GitLab.com enforces 2000 req/min per-token; back off and retry |
| 500 | Server Error | Transient GitLab issue; retry after a few seconds |
### Common Issues
**"Not configured"** — The app instance has no API key. Generate one at the provider and paste it in the app configuration.
**"Invalid API key" (MCP)** — The `mcp-api-key` header does not match the central app secret. Reinstall the app instance to regenerate a signed key.
**"Credentials lookup failed"** — The MCP endpoint could not reach the `getConfig` webhook of the installed app. Verify that the app instance is still installed in the expected workspace.
**"Can't approve own MR"** — A GitLab project access token's bot user counts as the MR author and cannot approve its own merge requests. Use a different token (PAT for a human user) for the approval step.
**"pipeline creation 404"** — The target ref has no `.gitlab-ci.yml` at its root. Either commit a CI config first or pick a ref that has one.
**OAuth per-user delegation** — Each GitLab user must click the `connect` tool once (from the AI agent) to authorize; the agent stores a per-user refresh token. Use `disconnect` to revoke.
## External Resources
Official GitLab REST v4 API reference
Plug MCP servers into AI Knowledge agents