Metadata
- name
- gitlab
- description
- 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.
- allowed-tools
- Bash(gitlab-client:*)
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.
