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.

Parameters Reference

Common Option

Commands

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

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 REST API and OAuth form 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.

REST records include a UTC timestamp, actor, auth mode, normalized origin, operation, HTTP method, and event. OAuth records use bounded operation and failure kinds without actor, origin, client, profile, code, body, or free-form error fields. Resource paths, queries, profile names, and profile contents are excluded. The optional audit sink is operationally sensitive because origins can identify tenants or internal hosts. Place it at an access-controlled path and retain it only as long as operations require. Tokens and authorization headers are never written. Audit failures after the request emit a warning without altering the result.

Credential Rotation

OAuth is the default. Register a non-confidential user-, group-, or self-managed instance-owned application with redirect URI http://127.0.0.1:8766/callback and the api scope. Set only GITLAB_URL and GITLAB_OAUTH_CLIENT_ID, then run auth login or the human-assisted auth device-login. Browser login requires a rotating refresh token; access tokens refresh before expiry and replacements are stored atomically. Device login can return an access-token-only profile and then requires another device login after expiry. A provider/local crash window can still require re-login.

The default store is $XDG_DATA_HOME/hve-core/gitlab/gitlab-token.json on POSIX, falling back to ~/.local/share/hve-core/gitlab/gitlab-token.json. POSIX store and lock files use mode 0600 inside a dedicated owner-only directory. OAuth profile persistence fails closed on Windows because Python 3.11 mode bits cannot enforce an owner-only DACL. Use explicit legacy-token mode on Windows until a protected OAuth backend is available.

PAT authentication remains available through GITLAB_AUTH_MODE=legacy-token. Device authorization requires user approval on a browser-capable device and is not unattended workload identity.

Quick Start

Export your environment variables, then run a read command with --fields.

export GITLAB_URL="https://gitlab.com"
export GITLAB_OAUTH_CLIENT_ID="your-application-id"
export GITLAB_PROJECT="group/project"

python scripts/gitlab.py auth login
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

Troubleshooting

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