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 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 Knowledges 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

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

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

- 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

Usage as MCP

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 Knowledges agent that does not yet support the native MCP picker.

1. 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.

2. Copy the MCP credentials

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

3. Open your Knowledges project

   Navigate to Advanced > Tools.

4. Add an MCP tool

   Click Add and select the MCP tab.

5. Fill in the endpoint

   Paste the MCP Endpoint URL copied from the app instance.

6. Add the auth header

   In the Headers field, add the signed API key:

   {
     "mcp-api-key": "your-mcp-api-key"
   }
   
7. 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.

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.

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

External Resources

GitLab REST API

Official GitLab REST v4 API reference

Tool Agents

Plug MCP servers into Knowledges agents