Terminal
Terminal/Skill
Lets your agent review and merge GitLab merge requests, commit files, run pipelines, and manage issues.
By Zapier
Works with
npx skills add zapier/connectors --skill gitlabAgent-callable tools for GitLab, the DevOps platform for source code, merge requests, and CI/CD. The connector wraps the GitLab REST API v4 (with one GraphQL island — the Work Items surface — reached through POST /api/graphql), giving an agent the ability to read and drive projects, issues, merge requests, repository contents, and pipelines. It is centered on the merge-request review loop and repository authoring: read an MR and its diffs and discussions, comment or approve, commit file changes atomically, and run or inspect CI. It targets GitLab SaaS (gitlab.com) by default; the host is configurable for self-managed and GitLab Dedicated instances.
Independent, unofficial connector for Gitlab. Not affiliated with, endorsed by, or sponsored by Gitlab. "Gitlab" is a trademark of its owner, used only to identify the service this connector works with.
This is an agentskills.io skill.
If the connector has not been installed as a skill yet, install it first with npx skills add zapier/connectors --skill gitlab (or your harness's own skill-install mechanism), then continue here. Installing the skill copies these files, not dependencies. Before running the CLI, a local MCP server, or zapier-sdk auth commands, run npm install --omit=dev here once. Importing the published package as a dependency in your own project instead? That npm install already resolves everything — see references/use-as-sdk.md.
Want the actual repo source instead — to browse references/, run this connector's tests, or hack on it? See README.md for a scoped git clone.
The connector runs on Node.js 22.18+. Pick the reference that matches how you're running it, and load it before doing anything else:
| You have... | Load |
|---|---|
An MCP-aware client — tools may already be loaded (e.g. mcp__gitlab__<tool>), or you can register a local server yourself (or guide the user to) | references/use-as-mcp.md |
Terminal / subprocess access (you can run node) | references/use-as-cli.md |
| Only your own code, importing this package as a dependency | references/use-as-sdk.md |
| No tool access, no terminal, no ability to import this package — you write your own code that calls the Gitlab API directly (e.g. a code-execution sandbox) | references/use-as-recipe.md |
All 47 scripts use the single connection gitlab. Project-scoped tools take a projectId (numeric id or URL-encoded group/project path); issues and MRs are addressed by their project-scoped iid, not the global id. The script's inputSchema / outputSchema (Zod) inside the file is the source of truth for its contract.
Projects & search
| Script | Script name | Connections | Description |
|---|---|---|---|
scripts/listProjects.ts | listProjects | gitlab | List or search projects the token can see (resolves projectId). |
scripts/getProject.ts | getProject | gitlab | Get one project's metadata by id or path (incl. default_branch). |
scripts/search.ts | search | gitlab | Search globally across projects, issues, MRs, milestones, users, code, or commits. |
scripts/searchProject.ts | searchProject | gitlab | Search within one project across issues, MRs, milestones, users, code, or commits. |
scripts/searchGroup.ts | searchGroup | gitlab | Search within one group across projects, issues, MRs, milestones, users, code, or commits. |
Issues
| Script | Script name | Connections | Description |
|---|---|---|---|
scripts/listIssues.ts | listIssues | gitlab | List issues in a project, filterable by state, labels, assignee, or milestone. |
scripts/getIssue.ts | getIssue | gitlab | Get one issue including its full markdown description. |
scripts/createIssue.ts | createIssue | gitlab | Open a new issue with a markdown description. |
scripts/updateIssue.ts | updateIssue | gitlab | Update an issue's fields, or close/reopen it. |
scripts/addIssueComment.ts | addIssueComment | gitlab | Add a comment (note) to an issue. |
Merge requests
| Script | Script name | Connections | Description |
|---|---|---|---|
scripts/listMergeRequests.ts | listMergeRequests | gitlab | List MRs assigned to or created by the token identity across all projects (global). |
scripts/listProjectMergeRequests.ts | listProjectMergeRequests | gitlab | List merge requests in one project. |
scripts/listGroupMergeRequests.ts | listGroupMergeRequests | gitlab | List merge requests across all projects in one group. |
scripts/getMergeRequest.ts | getMergeRequest | gitlab | Get one merge request's full detail (the entry point to the review loop). |
scripts/createMergeRequest.ts | createMergeRequest | gitlab | Open a merge request from a source branch into a target branch. |
scripts/updateMergeRequest.ts | updateMergeRequest | gitlab | Update an MR's fields, or close/reopen it. |
scripts/mergeMergeRequest.ts | mergeMergeRequest | gitlab | Merge a merge request (optionally squash, or guard with a head sha). |
scripts/approveMergeRequest.ts | approveMergeRequest | gitlab | Approve (or revoke approval on) a merge request. |
scripts/getMergeRequestDiffs.ts | getMergeRequestDiffs | gitlab | Get the paginated file diffs for a merge request. |
scripts/listMergeRequestCommits.ts | listMergeRequestCommits | gitlab | List the commits on a merge request. |
scripts/listMergeRequestNotes.ts | listMergeRequestNotes | gitlab | List the comments (notes) on a merge request. |
scripts/addMergeRequestComment.ts | addMergeRequestComment | gitlab | Add a top-level comment (note) to a merge request. |
scripts/addMergeRequestDiffComment.ts | addMergeRequestDiffComment | gitlab | Add a review comment pinned to a specific line of an MR diff. |
scripts/listMergeRequestDiscussions.ts | listMergeRequestDiscussions | gitlab | List discussion threads on an MR, incl. diff notes and resolved/resolvable status. |
Repository
| Script | Script name | Connections | Description |
|---|---|---|---|
scripts/listBranches.ts | listBranches | gitlab | List (or search) a project's branches. |
scripts/createBranch.ts | createBranch | gitlab | Create a branch from an existing ref (ref is required — no silent default). |
scripts/commitFiles.ts | commitFiles | gitlab | Create, update, delete, or move multiple files in a single atomic commit. |
scripts/listCommits.ts | listCommits | gitlab | List commits on a branch or across the repository. |
scripts/getFile.ts | getFile | gitlab | Read a file's contents at a ref. |
scripts/listRepositoryTree.ts | listRepositoryTree | gitlab | List files and directories in a repository path. |
scripts/compareRefs.ts | compareRefs | gitlab | Compare two refs and return the diff between them. |
CI/CD
| Script | Script name | Connections | Description |
|---|---|---|---|
scripts/triggerPipeline.ts | triggerPipeline | gitlab | Run a new pipeline on a ref, with optional CI/CD variables. |
scripts/listPipelines.ts | listPipelines | gitlab | List pipelines for a project, filterable by ref or status. |
scripts/getPipeline.ts | getPipeline | gitlab | Get one pipeline's status and metadata. |
scripts/listPipelineJobs.ts | listPipelineJobs | gitlab | List the jobs in a pipeline. |
scripts/getJobLog.ts | getJobLog | gitlab | Get the log (trace) output of a CI job. |
scripts/retryPipeline.ts | retryPipeline | gitlab | Retry the failed and canceled jobs in a pipeline, keeping the passed ones. |
scripts/cancelPipeline.ts | cancelPipeline | gitlab | Cancel a running pipeline, stopping its in-progress and pending jobs. |
scripts/playJob.ts | playJob | gitlab | Start a manual job waiting on a manual action (a play button). |
Work items (GraphQL)
| Script | Script name | Connections | Description |
|---|---|---|---|
scripts/listWorkItems.ts | listWorkItems | gitlab | List work items in a project or group, filterable by type and state. |
scripts/getWorkItem.ts | getWorkItem | gitlab | Get one work item's full detail including its description and type. |
scripts/createWorkItem.ts | createWorkItem | gitlab | Create a work item (epic, task, objective, etc.) in a project or group. |
scripts/updateWorkItem.ts | updateWorkItem | gitlab | Update a work item's fields, or close/reopen it. |
Metadata & resolvers
| Script | Script name | Connections | Description |
|---|---|---|---|
scripts/listLabels.ts | listLabels | gitlab | List a project's labels (resolves valid label names). |
scripts/listMilestones.ts | listMilestones | gitlab | List a project's milestones (resolves milestone_id). |
scripts/getCurrentUser.ts | getCurrentUser | gitlab | Get the identity of the authenticated token (also the connection test). |
scripts/findUsers.ts | findUsers | gitlab | Find users by username or search term (resolves assignee/reviewer ids). |
This connector resolves names to ids, then writes. Two situations trip up an action-biased agent — handle both before you write.
Before writing to a record you looked up by name — count how many returned records match the name the user gave exactly (case-insensitive). This applies to projects looked up by path/name via listProjects, users looked up by username via findUsers, and labels or milestones via listLabels / listMilestones:
.../api, two users both named "Jordan Lee", two labels both "backend") → stop. List them with a distinguishing field (id + path_with_namespace / username / description) and ask which one. Never pick one yourself and write against it.Before fulfilling a request, check that a script actually does it:
Every shape passes auth as one connection selector, not the secret — a [<resolver>:]<value> string. Every connector accepts zapier:<connection-id> (Zapier-managed auth — routes through Zapier's auth, retries, and governance layer); some also accept one or more direct-token resolvers (naming and count vary per connector) — check this connector's own resolvers rather than assuming. The <resolver>: prefix is optional; a bare value goes to the first resolver that claims it — a UUID-shaped bare value always claims zapier:. Each script declares the connections it needs and the resolvers each accepts. The exact syntax for passing a connection (and how to see this connector's resolver list) differs by shape — see the reference you loaded above.
Checking what's already configured first? Don't dump environment values to do it — env or env | grep <name> prints the value along with the name, leaking a live credential into the transcript if one is set. Check names only (env | cut -d= -f1 | grep -i <name>) or test a known name directly ([ -n "$VAR_NAME" ]).
No connection yet? Pick one — and follow the reference's own flow to obtain it; never just ask the user for a connection id or token as if they already have one memorized:
| Load | |
|---|---|
| Pass the credential directly | references/use-without-zapier.md |
| Route it through a Zapier connection | references/use-with-zapier.md |
Every script returns a { data, meta } envelope:
data — the script's result (the shape its outputSchema declares; see the reference you loaded above for how to inspect a script's exact schema in your shape).meta.outputDataValidation — what validating data did:
{ skipped: false, droppedPaths: null } — validated, nothing removed.{ skipped: false, droppedPaths: [...], instruction } — validated, but those paths were stripped from data: fields the script returned from the API that the outputSchema doesn't declare. If you need them, re-run with output validation skipped.{ skipped: true } — validation was bypassed; data is the raw, unchecked script output.Reading dropped fields / skipOutputDataValidation. To receive the raw, unvalidated result, opt out of output validation (the exact syntax differs by shape — see the reference you loaded above). Input validation is never skipped.
Trimming the result / filterOutputData. To shrink a large result down to the fields you need, pass a jq expression that post-processes data (again, exact syntax per shape). The jq runs against data only, NOT the { data, meta } envelope, so write it rooted at data (run the script's --help — or your shape's equivalent — to see its output schema). The transformed value replaces data, meta is preserved, and the result is NOT re-validated against the output schema.
Load the matching reference file before working in that area:
| Reference | Covers | Load it when |
|---|---|---|
references/gitlab-api-gotchas.md | Vendor behaviors that break a naive caller: PRIVATE-TOKEN vs OAuth Bearer auth and api/read_api scopes, numeric-id-vs-encoded-path and iid-vs-global-id, the JSON error shape and status codes, offset vs keyset pagination, gitlab.com rate limits, the singular POST .../pipeline, merge 405-when-not-mergeable and the sha guard, GraphQL-only work items. | Before any write, or when a call returns a non-2xx status, a 405 on merge, an empty/errored pipeline or work-item call, or an unexpected pagination result. |
references/gitlab-formatting.md | GitLab Flavored Markdown: blank-line paragraph breaks, #/!/@ references, task lists, tables, fenced code highlighting. | When composing a GitLab issue or merge-request description, a work-item body, or a note/diff comment. |