Gitlab Agent Skill
Manage GitLab merge requests and pipelines with a Python CLI
Install
one command, takes just this skill from the repositorynpx skills add https://github.com/microsoft/hve-core --skill gitlabWhat comes with it
57 416 bytes besides the instructionThe instruction itself
12 sections, as written by the authorGitLab Skill
Overview
Use this skill to inspect and update GitLab merge requests, notes, pipelines,
and job logs against GitLab.com or self-managed GitLab instances.
This skill is the repository-local Python workflow for GitLab tasks. It is not
the official GitLab MCP server integration surface.
This first hve-core implementation is Python-only. Run the CLI through
python scripts/gitlab.py and prefer --fields for read operations to keep
output concise.
Prerequisites
The skill requires Python 3.11 or later.
Set these environment variables before running any command:
| Variable | Required | Example | Purpose |
|------------------|----------|----------------------|-----------------------------------------------|
| GITLAB_URL | Yes | https://gitlab.com | GitLab instance URL |
| GITLAB_TOKEN | Yes | glpat-... | Personal access token sent as PRIVATE-TOKEN |
| GITLAB_PROJECT | No | group/project | Project path or numeric project ID |
If GITLAB_PROJECT is not set, the script attempts to detect the project from
git remote get-url origin. Set the variable explicitly when you are not in a
git repository or when you want to target a different project.
Operational Variables
| Variable | Required | Purpose |
|----------------------|----------|-----------------------------------------------------------------------------------------|
| GITLAB_AUDIT_LOG | No | Path to a JSON Lines audit log. When set, every request is audited (see Audit Logging). |
| GITLAB_AUDIT_ACTOR | No | Overrides the recorded actor identity (for example, a CI service principal). |
Audit Logging
When GITLAB_AUDIT_LOG is set, the script writes a structured JSON Lines audit trail for every API request. Auditing is fail-closed and write-ahead:
- An
attemptrecord is written before the request is sent. If the audit log cannot be written, the operation is aborted and nothing is sent to GitLab. - An
outcomerecord (successorerror, with HTTP status on failure) is written after the request completes.
Each record includes a UTC timestamp, the actor (from GITLAB_AUDIT_ACTOR, otherwise gitlab-token), the operation, HTTP method, and the request path. Tokens, authorization headers, and query strings are never written. Audit failures after the request emit a warning without altering the result.
Credential Rotation
The script reads GITLAB_TOKEN from the environment on every invocation, so an external rotator can swap it between calls without code changes. A 401 or 403 response indicates the token may be expired or revoked; rotate the personal access token in GitLab user settings. Full OAuth-style refresh flows are out of scope for this CLI.
Quick Start
Export your environment variables, then run a read command with --fields.
export GITLAB_URL="https://gitlab.com"
export GITLAB_TOKEN="glpat-..."
export GITLAB_PROJECT="group/project"
python scripts/gitlab.py mr-list opened --fields iid,title,author.name
Read pipeline jobs for a known pipeline:
python scripts/gitlab.py pipeline-jobs 12345 --fields id,name,status,stage
Parameters Reference
Common Option
| Parameter | Applies To | Example | Description |
|------------|------------------------------------------------------------------|----------------------------|-----------------------------------------------------------------------------------------|
| --fields | mr-list, mr-get, mr-notes, pipeline-get, pipeline-jobs | --fields iid,title,state | Extract specific fields with dot notation and print concise tabular or key-value output |
Commands
| Command | Arguments | Description |
|-----------------|----------------------------|------------------------------------------------------------------------|
| mr-list | [state] [max] | List merge requests, defaulting to all states and 20 results |
| mr-get | <mr-iid> | Get one merge request by project-scoped IID |
| mr-create | <json> or stdin | Create a merge request from a JSON payload |
| mr-update | <mr-iid> <json> or stdin | Update merge request fields from a JSON payload |
| mr-comment | <mr-iid> <body> or stdin | Add a comment to a merge request |
| mr-notes | <mr-iid> [max] | List merge request notes, excluding system notes when using --fields |
| pipeline-get | <pipeline-id> | Get one pipeline by numeric ID |
| pipeline-run | <branch-or-tag> | Trigger a pipeline for a branch or tag |
| pipeline-jobs | <pipeline-id> | List jobs for a pipeline |
| job-log | <job-id> | Print raw log output for a job |
Script Reference
List recent open merge requests:
python scripts/gitlab.py mr-list opened --fields iid,title,author.name,user_notes_count
Get one merge request:
python scripts/gitlab.py mr-get 42 --fields iid,title,state,source_branch,target_branch
Create a merge request from inline JSON:
python scripts/gitlab.py mr-create '{
"source_branch": "feature/add-auth",
"target_branch": "main",
"title": "feat(auth): add OAuth login"
}'
Add a merge request comment from standard input:
echo "CI passed. Ready for review." | python scripts/gitlab.py mr-comment 42
Inspect a failed pipeline:
python scripts/gitlab.py pipeline-get 12345 --fields id,status,web_url
python scripts/gitlab.py pipeline-jobs 12345 --fields id,name,status,stage
python scripts/gitlab.py job-log 67890
Troubleshooting
| Symptom | Cause | Resolution |
|--------------------------------------------------|-----------------------------------------------|-------------------------------------------------------------|
| GITLAB_URL is not set | Required environment variable missing | Export GITLAB_URL before running the script |
| GITLAB_TOKEN is not set | Missing personal access token | Create a token with API access and export GITLAB_TOKEN |
| cannot parse git remote URL | Project autodetection failed | Set GITLAB_PROJECT explicitly |
| HTTP 401 or HTTP 403 | Token is invalid or lacks access | Verify token scope and project permissions |
| HTTP 404 | Wrong project, MR IID, pipeline ID, or job ID | Verify GITLAB_PROJECT and confirm the numeric identifiers |
| expected numeric ID | Non-numeric value passed to an ID argument | Use project MR IID values and numeric pipeline or job IDs |
| python3 is required or syntax errors on launch | Unsupported interpreter | Run the script with Python 3.11 or later |
GitLab uses MR IIDs such as !42 inside a project. This skill expects the
numeric IID, not the global merge request ID.
Other skills for the same job
different authors, same section of the catalogue
Guide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).
Automatically creates user-facing changelogs from git commits by analyzing commit history, categorizing changes, and transforming technical commits into clear, customer-friendly release notes. Turns hours of manual changelog writing into minutes of automated generation.
Use when implementation is complete, all tests pass, and you need to decide how to integrate the work - guides completion of development work by presenting structured options for merge, PR, or cleanup
Guide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).
React Native and Expo best practices for building performant mobile apps. Use when building React Native components, optimizing list performance, implementing animations, or working with native modules. Triggers on tasks involving React Native, Expo, mobile performance, or native platform APIs.
React and Next.js performance optimization guidelines from Vercel Engineering. This skill should be used when writing, reviewing, or refactoring React/Next.js code to ensure optimal performance patterns. Triggers on tasks involving React components, Next.js pages, data fetching, bundle optimization, or performance improvements.
Next.js best practices - file conventions, RSC boundaries, data patterns, async APIs, metadata, error handling, route handlers, image/font optimization, bundling
Use when starting feature work that needs isolation from current workspace or before executing implementation plans - creates isolated git worktrees with smart directory selection and safety verification
How to use it
Take microsoft/gitlab from the repository into ~/.claude/skills for personal
use, or into .claude/skills inside a project.
The agent identifies a skill by the name field in its header. Two skills with the
same name cannot sit side by side — one of them will be ignored.