- Home
- Skills
- APIs & Backend
- GitLab API Operator — REST & GraphQL for Any Instance
Works with the AI Agents you already use
GitLab API Operator — REST & GraphQL for Any Instance
Let your agent read and change GitLab issues, merge requests, pipelines, epics and vulnerabilities on gitlab.com or self-hosted, safely, with environment-only credentials.
Free
GitLab API Operator — REST & GraphQL for Any Instance
Example session with this skill installed
Take a look at this milestone: https://gitlab.example.com/groups/acme/case-portal/-/milestones/12
Give me a status report of its work items. I need:
- A short overall summary: milestone title, start and due dates, and whether it looks on track.
- Progress: how many items are open vs. closed, and the completion percentage.
- A table of all items with: reference (#iid), title, type (issue, task, epic...), state, assignee(s), labels, and the closing date for the ones already done.
- A breakdown per assignee: how many items each person has, and how many they have completed.
- Risks: open items that are overdue or have no assignee, and anything that looks blocked.
Read-only, please. Don't change anything in GitLab.
- Read your context and instructions
- Compiled the gitlab api operator
Agent asked: I found two GitLab token variables, GITLAB_PERSONAL_TOKEN and GITLAB_BOT_TOKEN. Which one should I use for this read-only query?
Buyer chose:
GITLAB_PERSONAL_TOKEN
Milestone 12: Release 2.4 - Sprint 1
Nothing was changed in GitLab. I used GITLAB_PERSONAL_TOKEN (authenticated as dev.user).
Milestone 12 belongs to the group acme/case-portal. I read its work items through GraphQL, including subgroups. The count matches a REST cross-check: 33 total, 0 open.
1. Summary
- Dates: 2026-09-01 to 2026-09-15. The milestone is closed.
Verdict: finished on time. The first item closed on 2026-09-04 and the last on 2026-09-14, one day before the due date.
2. Progress
| Open | Closed | Total | Completion |
|---|---|---|---|
| 0 | 33 | 33 | 100% |
Every item is an Issue (no tasks or epics): 16 in api-service and 17 in web-app. Each project has its own #iid numbering, so references carry the project name.
3. Items
All 33 are closed. Abridged for this listing: 16 of 33 rows shown; the agent returned all of them.
api-service
| Ref | Title | Assignee | Labels | Closed |
|---|---|---|---|---|
| #97 | US: Edit Profile (UAT) | alice.silva | Improvement, Done | 09-04 |
| #96 | Absence: set absence period on user creation | bruno.costa | Improvement, Done | 09-08 |
| #95 | US: Absence: set absence period on user edit | bruno.costa | Improvement, Done | 09-08 |
| #94 | US: Absence: block login during absence | bruno.costa | Improvement, Done | 09-09 |
| #93 | US: Unrestricted case editing: case list | alice.silva | Improvement, Done | 09-08 |
| #86 | UAT: show reopening reason on case edit | alice.silva | Improvement, Done | 09-04 |
| #81 | Import: handle user not found | carla.mendes | Improvement, Done | 09-08 |
| #78 | Unidentified user: view cases | carla.mendes | Done (listed twice), no type label | 09-14 |
| … | 8 more closed items, all assigned to alice.silva | Improvement, Done | 09-04 to 09-08 |
web-app
| Ref | Title | Assignee | Labels | Closed |
|---|---|---|---|---|
| #105 | Unidentified user: view cases | carla.mendes | Improvement, Done | 09-10 |
| #104 | Import: handle user not found | carla.mendes | Done, no type label | 09-11 |
| #103 | UAT: approve case, case list | alice.silva | Improvement, Done | 09-08 |
| #98 | US: Edit Profile (UAT) | alice.silva | Improvement, Done | 09-08 |
| #91 | US: Absence: block login during absence | bruno.costa | Improvement, Done | 09-08 |
| #90 | US: Absence: set absence period on user edit | bruno.costa | Improvement, Done | 09-04 |
| #88 | Absence: set absence period on user creation | bruno.costa | Improvement, Done | 09-04 |
| #83 | [QA] View case | bruno.costa | Bug, Done | 09-11 |
| … | 9 more closed items, all assigned to alice.silva | Improvement, Done | 09-08 to 09-09 |
All closing dates are in 2026.
4. Per assignee
Each item has exactly one assignee.
| Assignee | Items | Completed |
|---|---|---|
| alice.silva | 22 (67%) | 22 |
| bruno.costa | 7 | 7 |
| carla.mendes | 4 | 4 |
5. Risks
- Overdue or open items: none. All 33 are closed, and all closed on or before the 2026-09-15 due date.
- Unassigned items: none.
Blocked items: none. The only links are relates_to links to issues in acme/case-portal/docs, and no item has a blocking or blocked-by link. Most of those linked docs issues are still open and sit outside this milestone. You may want to check whether they were carried over to later sprints.
- Label problems:
api-service#78 andweb-app#104 have no type label.api-service#78 showsstatus:Donetwice, probably the same label defined at two levels.web-app#83 is the only Bug, and it came out of QA.
Behind the scenes (summarized)
- The
12in the URL is the milestone'siid, not its global ID. A direct lookup returned 404, so the agent resolved it through the group's milestone list byiid. - Work items were fetched with one GraphQL query, reading assignees, labels and dates from work-item widgets, with pagination checked (1 page, 33 items).
- The total was cross-checked against the REST issues count for the same milestone.
Connects securely to your tools. The creator never sees your data.
About this skill
Stop hand-writing curl calls and guessing which GitLab endpoint to use. This skill teaches your agent to work with GitLab the careful way: right host, right API, right token, and no surprise writes.
About this skill
GitLab API Operator gives your agent a complete, safety-first procedure for reading and changing GitLab resources through the REST and GraphQL APIs. It works on gitlab.com and on self-hosted instances, including ones installed under a subpath. It figures out where to send requests, picks the API that actually supports what you asked for, and verifies the connection before it touches anything.
What it does
- Finds your GitLab host automatically. It reads it from your message, the git remote (HTTPS or SSH), or CI config. It never assumes gitlab.com, and it asks only when it truly can't tell.
- Picks REST or GraphQL for you. REST for straightforward single-resource work, GraphQL for multi-resource queries and for features REST doesn't fully cover: epics and work items, and vulnerabilities.
- Covers day-to-day GitLab work. Issues, merge requests, branches, pipelines, labels, milestones, members, notes, search, epics, work items, and vulnerabilities.
- Keeps your token private. Credentials come only from an exported environment variable. The token is never printed, written to a file, or put on a command line or in a URL.
- Confirms before it acts. It states the host, project and action before the first write, and asks for explicit approval before anything destructive or hard to reverse, such as merging, deleting or bulk-closing.
- Reports results properly. It paginates fully instead of stopping at page 1, tells 401 from 403 from 404, respects rate limits, checks the errors hidden inside GraphQL 200 responses, and returns links, not bare IDs.
How it works
- Authenticate. It lists the names of exported GitLab token variables, never their values, and uses the one that matches. If there are several, it asks you which to use. If there are none, it walks you through creating a scoped Personal Access Token.
- Locate the host. It builds the correct REST and GraphQL base URLs, including relative URL roots.
- Verify. One cheap call to
/userconfirms that the host and token work together before any write. - Choose the API and act. It runs the request with safe curl and jq patterns, then validates the response.
Frameworks & tools
Plain Bash with curl 7.76+ and jq. No scripts to install, no dependencies, and no packages fetched at runtime. Network access goes only to the GitLab host you point it at. Includes REST and GraphQL reference guides the agent loads on demand.
Why this beats prompting it yourself
A generic prompt will usually assume gitlab.com, try the deprecated Epics REST API, leak a token into a command line, or report page 1 as the full list. This skill encodes those lessons, including the GitLab-specific traps: id vs iid, URL-encoded project paths, GraphQL global IDs, silent no-op assignments, and the work-item migration for epics.
Use cases
- Creating and assigning issues from a conversation
- Listing open merge requests, or checking what's blocking one
- Triggering and monitoring pipelines
- Checking who owns an epic or its health status
- Reviewing vulnerability findings across a project
- Automating triage on self-hosted company GitLab instances
Known limitations
- Requires
curl7.76 or later,jq, and network access to your GitLab host. - CI/CD job tokens (
CI_JOB_TOKEN) are not supported. Use a personal, project or group access token, or OAuth. - It will not fall back to the
glabCLI or read tokens from files. This is deliberate, so it never picks up a stale credential. - Some features depend on your GitLab version and tier.
- Requires Bash, curl 7.76 or later and jq. Windows needs WSL or Git Bash.
- Credentials come only from an exported environment variable. There is no fallback to files, the glab CLI or stored logins, so if no token variable is set the skill stops and tells you how to create one.
- CI/CD job tokens (CI_JOB_TOKEN) are not supported.
- Covers the API only. It does not run git operations such as clone or push.
- Common resources are documented in the bundled references. For anything else, the agent is pointed to GitLab's official API docs and needs to be able to read them.
- Some features depend on your GitLab version and tier, notably epics and work items, and vulnerabilities (Premium/Ultimate).
- GitLab's epic GraphQL types are deprecated, with removal planned for GitLab 19.0. The skill uses work items for epics, so check it against your instance version.
- GraphQL queries are limited by GitLab's complexity cap, so large queries may need to be split.
- Developed and tested on Claude Code. Other agents have not been verified yet.
How to use
- 1
Connect your agent to the Agensi MCP
Copy the prompt and paste it into Claude, ChatGPT, Cursor or any agent that supports MCP. It sets up the connection for you. Manual setup
- 2
Sign in to Agensi
Your agent shows a sign-in link. Sign in and click Allow.
- 3
Ask for what you need
Your agent loads this skill and uses it on your task. It always asks before any payment.
Reviews
No reviews yet
Be one of the first to try it. Every listed skill goes through the trust checks below.
Security scanned
Checked by our 8-point scan before listing
1 use
Times used to date
Free forever
No account required to browse
Trust & safety
Security scan
Security scan passed 28 days ago
- Free with an Agensi account
Requires
Permissions
Allowed Hosts
File Scopes
Environment variables: the skill lists the NAMES of exported variables matching *GITLAB*TOKEN* (never their values) to find your token. It uses that token only in an HTTP header passed through a pipe, so the value never appears on a command line, in a URL, in a file, or in the output. Network: requests go only to the GitLab host you provide or that is detected from your git remote (REST at /api/v4 and GraphQL at /api/graphql). Nothing is sent anywhere else, and nothing is downloaded or executed at runtime. Files: read-only access to .gitlab-ci.yml, .git/config and README files, solely to detect the host. The skill never reads .env, .netrc, CLI config or other credential files, and it never writes files. Token scope: read_api is enough for read-only use. The api scope is needed for anything that creates or changes data. The skill confirms before outward-facing writes and asks for explicit approval before destructive ones.