GitLab API Client

Interact with GitLab API for managing projects, issues, merge requests, branches, pipelines, users, groups, and more. Use when the user needs to perform GitLab operations like creating issues, reviewing merge requests, managing branches, or querying project data via the GitLab REST API.

GitLab API Skill

Node.js client for the GitLab REST API (v4). Reads config from ./.env.

Security Rules

• NEVER read, cat, print, grep, or expose the GITLAB_TOKEN value.
• NEVER use curl, wget, or any tool to call GitLab API directly. All access MUST go through gitlab-client.
• AI may read/write .env to manage GITLAB_URL, but GITLAB_TOKEN must be set by the user manually.

Setup

Requires ./.env with:

GITLAB_URL=https://gitlab.fullnine.com.cn
GITLAB_TOKEN=<your-personal-access-token>

If token is missing, prompt the user to edit ./.env and create a token at <GITLAB_URL>/-/profile/personal_access_tokens (scope: api).

Install (first time): source ~/.nvm/nvm.sh && npm install

Quick Start

gitlab-client users me                                    # Current user
gitlab-client projects list --owned                       # My projects
gitlab-client issues list --project 42 --state opened     # Project issues
gitlab-client mrs create --project 42 --source-branch feat --target-branch main --title "My MR"

Commands Reference

Format: gitlab-client <resource> <action> [id] [--key value ...]

All list actions support --page N --per-page N (default 20, max 100).

Projects

Action	Usage	Options
list	projects list	--search --owned --membership --visibility
get	projects get <id>
search	projects search "term"
create	projects create --name "name"	--description --visibility --namespace-id --initialize-with-readme
edit	projects edit <id>	--name --description --visibility
delete	projects delete <id>
fork	projects fork <id>	--namespace
members	projects members <id>
hooks	projects hooks <id>

Issues

Action	Usage	Options
list	issues list --project <id>	--state --labels --milestone --assignee-id --search
get	issues get --project <id> --iid <iid>
create	issues create --project <id> --title "T"	--description --labels --assignee-ids --milestone-id --due-date --confidential
edit	issues edit --project <id> --iid <iid>	--title --description --state-event --labels --assignee-ids
close	issues close --project <id> --iid <iid>
reopen	issues reopen --project <id> --iid <iid>
delete	issues delete --project <id> --iid <iid>
notes	issues notes --project <id> --iid <iid>
add-note	issues add-note --project <id> --iid <iid> --body "text"

Merge Requests

Action	Usage	Options
list	mrs list --project <id>	--state --labels --milestone --source-branch --target-branch --search
get	mrs get --project <id> --iid <iid>
create	mrs create --project <id> --source-branch "src" --target-branch "tgt" --title "T"	--description --assignee-id --reviewer-ids --labels --milestone-id --remove-source-branch --squash
edit	mrs edit --project <id> --iid <iid>	--title --description --state-event --labels --assignee-id
merge	mrs merge --project <id> --iid <iid>	--merge-commit-message --squash --should-remove-source-branch
changes	mrs changes --project <id> --iid <iid>
commits	mrs commits --project <id> --iid <iid>
notes	mrs notes --project <id> --iid <iid>
add-note	mrs add-note --project <id> --iid <iid> --body "text"
approve	mrs approve --project <id> --iid <iid>
pipelines	mrs pipelines --project <id> --iid <iid>

Branches

Action	Usage	Options
list	branches list --project <id>	--search
get	branches get --project <id> --branch "name"
create	branches create --project <id> --branch "name" --ref "main"
delete	branches delete --project <id> --branch "name"
delete-merged	branches delete-merged --project <id>

Commits

Action	Usage	Options
list	commits list --project <id>	--ref-name --since --until --path
get	commits get --project <id> --sha "abc123"
diff	commits diff --project <id> --sha "abc123"
comments	commits comments --project <id> --sha "abc123"
add-comment	commits add-comment --project <id> --sha "abc123" --note "text"

Repository / Files

Action	Usage	Options
tree	repo tree --project <id>	--path --ref --recursive
file	repo file --project <id> --file-path "path"	--ref
raw	repo raw --project <id> --file-path "path"	--ref
create-file	repo create-file --project <id> --file-path "p" --branch "b" --content "c" --commit-message "m"
update-file	repo update-file --project <id> --file-path "p" --branch "b" --content "c" --commit-message "m"
delete-file	repo delete-file --project <id> --file-path "p" --branch "b" --commit-message "m"
compare	repo compare --project <id> --from "main" --to "feat"

Pipelines

Action	Usage	Options
list	pipelines list --project <id>	--status --ref
get	pipelines get --project <id> --pipeline-id <pid>
jobs	pipelines jobs --project <id> --pipeline-id <pid>
job-log	pipelines job-log --project <id> --job-id <jid>
retry	pipelines retry --project <id> --pipeline-id <pid>
cancel	pipelines cancel --project <id> --pipeline-id <pid>
create	pipelines create --project <id> --ref "main"	--variables "K1=v1,K2=v2"

Groups

Action	Usage	Options
list	groups list	--search --owned
get	groups get <id>
projects	groups projects <id>	--search
members	groups members <id>
issues	groups issues <id>	--state
mrs	groups mrs <id>	--state

Users

Action	Usage
me	users me
list	users list [--search "john"]
get	users get <id>
projects	users projects <id>

Labels

Action	Usage	Options
list	labels list --project <id>
create	labels create --project <id> --name "bug" --color "#FF0000"	--description
edit	labels edit --project <id> --name "bug"	--new-name --color
delete	labels delete --project <id> --name "bug"

Milestones

Action	Usage	Options
list	milestones list --project <id>	--state
get	milestones get --project <id> --milestone-id <mid>
create	milestones create --project <id> --title "v1.0"	--description --due-date --start-date
edit	milestones edit --project <id> --milestone-id <mid>	--title --state-event
delete	milestones delete --project <id> --milestone-id <mid>

Tags & Releases

Action	Usage	Options
tags list	tags list --project <id>	--search
tags create	tags create --project <id> --tag-name "v1.0" --ref "main"	--message
tags delete	tags delete --project <id> --tag-name "v1.0"
releases list	releases list --project <id>
releases create	releases create --project <id> --tag-name "v1.0" --name "R1"	--description

Snippets

Action	Usage	Options
list	snippets list --project <id>
get	snippets get --project <id> --snippet-id <sid>
create	snippets create --project <id> --title "T" --file-name "f" --content "c"	--visibility

Search

Action	Usage
global	search global --scope <scope> --search "query"
project	search project --project <id> --scope <scope> --search "query"
group	search group --group <id> --scope <scope> --search "query"

Scopes — global: projects|issues|merge_requests|milestones|snippet_titles|users. Project: issues|merge_requests|milestones|notes|wiki_blobs|commits|blobs. Group: projects|issues|merge_requests|milestones.

Runners

Action	Usage	Options
list	runners list --project <id>
all	runners all	--type --status

Webhooks

Action	Usage	Options
list	hooks list --project <id>
create	hooks create --project <id> --url "url"	--push-events --merge-requests-events --issues-events --token
delete	hooks delete --project <id> --hook-id <hid>

Usage Notes

• Auth: Uses PRIVATE-TOKEN header. Scopes: api (full), read_api (read-only), read_user, read_repository.
• Project ID: Use numeric ID or URL-encoded path (my-group%2Fmy-project).
• Output: JSON. Pipe to jq for filtering: gitlab-client projects list | jq '.[].name'
• Dates: ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ).
• Labels: Comma-separated: --labels "bug,feature,urgent".
• Errors: 401 unauthorized, 403 forbidden, 404 not found, 422 validation, 429 rate limited.