gitlab · microsoft — Claude Code skill: GitLab tasks and installation
Use a Python CLI to inspect and update GitLab merge requests, notes, pipelines, and job logs. It works with GitLab.com and self-managed instances.
MIT ★ 1,627 updated 2026-10-25
npx skills add microsoft/hve-core --skill gitlab -a claude-codeWhat gitlab does
The skill runs GitLab operations through python scripts/gitlab.py. It can inspect or update merge requests, notes, pipelines, and job logs. Set GITLAB_PROJECT to select a project; otherwise, the CLI tries to read it from the Git remote named origin. Read commands can return selected fields with --fields.
Python 3.11 or later is required. Set GITLAB_URL and configure OAuth with GITLAB_OAUTH_CLIENT_ID, or explicitly choose legacy-token mode and provide GITLAB_TOKEN. OAuth is the default. On Windows, OAuth profile persistence fails closed, so use legacy-token mode there.
Set GITLAB_AUDIT_LOG to record requests. The CLI writes an attempt record before sending each request and aborts the operation if that write fails. This matters when an audit-log write failure must not block the GitLab operation.
What it helps with
- inspect open merge requests and select returned fields
- read notes attached to a merge request
- check a pipeline and its jobs
- retrieve GitLab job logs
Example prompts for the agent
- List this project's open merge requests with just the ID, title, and author.
- Show the jobs for pipeline
12345, including only their names, statuses, and stages. - Fetch the notes for this project's merge request.
How to install gitlab
1Skills CLI (Vercel)
npx skills add microsoft/hve-core --skill gitlab -a claude-code2Manually: put the files in place
~/.claude/skills/gitlab/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/gitlab/
1Skills CLI (Vercel)
npx skills add microsoft/hve-core --skill gitlab -a codex2Manually: put the files in place
.agents/skills/gitlab/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add microsoft/hve-core --skill gitlab -a cursor2Manually: put the files in place
.cursor/skills/gitlab/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install microsoft/hve-core .github/skills/project-planning/gitlab2Manually: put the files in place
.github/skills/gitlab/SKILL.md1Skills CLI (Vercel)
npx skills add microsoft/hve-core --skill gitlab -a gemini-cli2Platform CLI
gemini skills install https://github.com/microsoft/hve-core --path .github/skills/project-planning/gitlabManually: put the files in place
.devin/skills/gitlab/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about gitlab
How do I install gitlab in Claude Code?
Run npx skills add microsoft/hve-core --skill gitlab -a claude-code. The skill file is at ~/.claude/skills/gitlab/SKILL.md.
What does the gitlab skill do?
It uses a Python CLI to inspect and update GitLab merge requests, notes, pipelines, and job logs.
What does gitlab need before it can run?
Use Python 3.11 or later and set GITLAB_URL. OAuth requires GITLAB_OAUTH_CLIENT_ID; PAT authentication requires GITLAB_AUTH_MODE=legacy-token and GITLAB_TOKEN. On Windows, use legacy-token mode because OAuth profile persistence fails closed.
Source text
SKILL.md · MIT
---
name: gitlab
description: 'Manage GitLab merge requests and pipelines with a Python CLI'
license: MIT
compatibility: 'Requires Python 3.11+. GitLab OAuth public-client credentials or explicit legacy-token mode.'
metadata:
authors: "microsoft/hve-core"
spec_version: "1.0"
last_updated: "2026-08-18"
---
# 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_AUTH_MODE` | Optional | `oauth` | `oauth` or explicit `legacy-token` compatibility mode |
| `GITLAB_OAUTH_CLIENT_ID` | OAuth | Application ID | Non-confidential OAuth application ID; no client secret |
| `GITLAB_TOKEN` | Legacy mode | `glpat-...` | PAT accepted only with `GITLAB_AUTH_MODE=legacy-token` |
| `GITLAB_PROFILE` | No | `default` | Named OAuth profile |
| `GITLAB_TOKEN_STORE` | No | path | OAuth store override; parent must be owner-only on POSIX |
| `GITLAB_ALLOW_INSECURE` | No | `1` | Permit explicit loopback HTTP development endpoints only |
| `XDG_DATA_HOME` | No | path | POSIX data root used for the default OAuth store |
| `LOCALAPPDATA` | No | path | Reserved Windows data root; OAuth persistence currently fails closed on Windows |
| `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). |
| `GITLAB_DEBUG` | No | Set to `1` to print a redacted traceback on failure. Never disables redaction. |
### 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`.
```bash
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:
```bash
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 |
|---------------------|----------------------------|------------------------------------------------------------------------|
| `auth login` | None | Authenticate with Authorization Code and PKCE |
| `auth device-login` | None | Authenticate through human-assisted device authorization |
| `auth status` | None | Print secret-free local profile status |
| `auth logout` | None | Delete one local profile without revoking server authorization |
| `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:
```bash
python scripts/gitlab.py mr-list opened --fields iid,title,author.name,user_notes_count
```
Get one merge request:
```bash
python scripts/gitlab.py mr-get 42 --fields iid,title,state,source_branch,target_branch
```
Create a merge request from inline JSON:
```bash
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:
```bash
echo "CI passed. Ready for review." | python scripts/gitlab.py mr-comment 42
```
Inspect a failed pipeline:
```bash
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 for legacy-token mode` | Explicit legacy mode has no PAT | Export a PAT only with `GITLAB_AUTH_MODE=legacy-token` |
| `GITLAB_TOKEN must not be set in oauth mode` | Legacy PAT leaked into the OAuth configuration | Remove `GITLAB_TOKEN` or explicitly select legacy-token mode |
| OAuth persistence is unavailable on Windows | No protected Windows profile-store backend | Use explicit legacy-token mode or run OAuth from POSIX |
| `GITLAB_OAUTH_CLIENT_ID is not set` | OAuth application is not configured | Set the public client ID, then run `auth login` |
| Callback listener cannot bind | Port 8766 is unavailable or not forwarded | Free the port or use `auth device-login` |
| `timed out waiting for the GitLab OAuth token store lock` | Another process holds the profile-store lock | Wait for the other command to finish, then retry |
| `GitLab device response has invalid verification_uri` | The verification URI is unsafe to display or does not match `GITLAB_URL` | Confirm `GITLAB_URL` matches the instance that serves device verification |
| `cannot parse git remote URL` | Project autodetection failed | Set `GITLAB_PROJECT` explicitly |
| `HTTP 401` or `HTTP 403` | Credential is invalid or lacks access | Re-login for OAuth; rotate the PAT in explicit legacy mode |
| `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.
© microsoft · MIT · microsoft/hve-core
Similar skills
All skills for Git and GitHub →gitlab by other authors comes first.