GitLab API Operator — REST & GraphQL for Any Instance

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

1. 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.
2. Locate the host. It builds the correct REST and GraphQL base URLs, including relative URL roots.
3. Verify. One cheap call to /user confirms that the host and token work together before any write.
4. 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 curl 7.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 glab CLI 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.