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:

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 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 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.