gitlab

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

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

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 attempt record 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 outcome record (success or error, 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

Parameters Reference

Common Option

Commands

Script Reference

List recent open merge requests:

Get one merge request:

Create a merge request from inline JSON:

Add a merge request comment from standard input:

Inspect a failed pipeline:

Troubleshooting

GitLab uses MR IIDs such as !42 inside a project. This skill expects the numeric IID, not the global merge request ID.