GitLab - Prisme.ai

The GitLab app provides read/write access to the GitLab 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.

Project Management

Projects, issues, merge requests, labels, milestones and wikis

CI/CD & DevOps

Pipelines, jobs, environments, CI variables, deploy keys and webhooks

Flexible Auth

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)

Usage as App
Usage as MCP

Installation

Go to Apps in your workspace
Search for GitLab and install it
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 <token>`.
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`

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

- GitLab.listProjects:
    membership: true
    order_by: last_activity_at
    sort: desc
    per_page: 20
    output: myProjects

Create an issue with labels and an assignee

- 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

- 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

- 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 the GitLab app

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.

Copy the MCP credentials

Open the app instance config and copy the values of MCP Endpoint and MCP API Key.

Open your AI Knowledge project

Navigate to Advanced > Tools.

Add an MCP tool

Click Add and select the MCP tab.

Fill in the endpoint

Paste the MCP Endpoint URL copied from the app instance.

Add the auth header

In the Headers field, add the signed API key:

{
  "mcp-api-key": "your-mcp-api-key"
}

Save

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.

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.

{
  "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

{
  "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.

{
  "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.

{
  "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

{
  "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.

{
  "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.

Integration Overview

Apps Marketplace

Project Management

CI/CD & DevOps

Flexible Auth

​Prerequisites

​Installation

​Configuration

​Available Instructions

​Projects

​Issues

​Merge Requests

​Branches

​Commits

​Tags

​Releases

​Pipelines & Jobs

​Environments

​Labels

​Milestones

​Wiki

​Webhooks

​CI/CD Variables

​Deploy Keys

​Project Members

​Users

​Groups

​DSUL Examples

​List the user’s own projects

​Create an issue with labels and an assignee

​Open a merge request from a feature branch

​Trigger a pipeline on a specific ref

​Legacy MCP Install (Advanced > Tools)

​Output Formats

​Available Tools

​Projects

​Issues

​Merge Requests

​Branches

​Commits

​Tags

​Releases

​Pipelines & Jobs

​Environments

​Labels

​Milestones

​Wiki

​Webhooks

​CI/CD Variables

​Deploy Keys

​Project Members

​Users

​Groups

​OAuth Session

​Tool Details

​createIssue

​createMergeRequest

​createPipeline

​listProjects

​createBranch

​mergeMergeRequest

​Error Handling

​Common Issues

​External Resources

GitLab REST API

Tool Agents

Prerequisites

Installation

Configuration

Available Instructions

Projects

Issues

Merge Requests

Branches

Commits

Tags

Releases

Pipelines & Jobs

Environments

Labels

Milestones

Wiki

Webhooks

CI/CD Variables

Deploy Keys

Project Members

Users

Groups

DSUL Examples

List the user’s own projects

Create an issue with labels and an assignee

Open a merge request from a feature branch

Trigger a pipeline on a specific ref

Legacy MCP Install (Advanced > Tools)

Output Formats

Available Tools

Projects

Issues

Merge Requests

Branches

Commits

Tags

Releases

Pipelines & Jobs

Environments

Labels

Milestones

Wiki

Webhooks

CI/CD Variables

Deploy Keys

Project Members

Users

Groups

OAuth Session

Tool Details

createIssue

createMergeRequest

createPipeline

listProjects

createBranch

mergeMergeRequest

Error Handling

Common Issues

External Resources