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:

text

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#

bash

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#

ActionUsageOptionslistprojects list``--search --owned --membership --visibilitygetprojects get <id>searchprojects search "term"createprojects create --name "name"``--description --visibility --namespace-id --initialize-with-readmeeditprojects edit <id>``--name --description --visibilitydeleteprojects delete <id>forkprojects fork <id>``--namespacemembersprojects members <id>hooksprojects hooks <id>

Issues#

ActionUsageOptionslistissues list --project <id>``--state --labels --milestone --assignee-id --searchgetissues get --project <id> --iid <iid>createissues create --project <id> --title "T"``--description --labels --assignee-ids --milestone-id --due-date --confidentialeditissues edit --project <id> --iid <iid>``--title --description --state-event --labels --assignee-idscloseissues close --project <id> --iid <iid>reopenissues reopen --project <id> --iid <iid>deleteissues delete --project <id> --iid <iid>notesissues notes --project <id> --iid <iid>add-noteissues add-note --project <id> --iid <iid> --body "text"

Merge Requests#

ActionUsageOptionslistmrs list --project <id>``--state --labels --milestone --source-branch --target-branch --searchgetmrs get --project <id> --iid <iid>createmrs create --project <id> --source-branch "src" --target-branch "tgt" --title "T"``--description --assignee-id --reviewer-ids --labels --milestone-id --remove-source-branch --squasheditmrs edit --project <id> --iid <iid>``--title --description --state-event --labels --assignee-idmergemrs merge --project <id> --iid <iid>``--merge-commit-message --squash --should-remove-source-branchchangesmrs changes --project <id> --iid <iid>commitsmrs commits --project <id> --iid <iid>notesmrs notes --project <id> --iid <iid>add-notemrs add-note --project <id> --iid <iid> --body "text"approvemrs approve --project <id> --iid <iid>pipelinesmrs pipelines --project <id> --iid <iid>

Branches#

ActionUsageOptionslistbranches list --project <id>``--searchgetbranches get --project <id> --branch "name"createbranches create --project <id> --branch "name" --ref "main"deletebranches delete --project <id> --branch "name"delete-mergedbranches delete-merged --project <id>

Commits#

ActionUsageOptionslistcommits list --project <id>``--ref-name --since --until --pathgetcommits get --project <id> --sha "abc123"diffcommits diff --project <id> --sha "abc123"commentscommits comments --project <id> --sha "abc123"add-commentcommits add-comment --project <id> --sha "abc123" --note "text"

Repository / Files#

ActionUsageOptionstreerepo tree --project <id>``--path --ref --recursivefilerepo file --project <id> --file-path "path"``--refrawrepo raw --project <id> --file-path "path"``--refcreate-filerepo create-file --project <id> --file-path "p" --branch "b" --content "c" --commit-message "m"update-filerepo update-file --project <id> --file-path "p" --branch "b" --content "c" --commit-message "m"delete-filerepo delete-file --project <id> --file-path "p" --branch "b" --commit-message "m"comparerepo compare --project <id> --from "main" --to "feat"

Pipelines#

ActionUsageOptionslistpipelines list --project <id>``--status --refgetpipelines get --project <id> --pipeline-id <pid>jobspipelines jobs --project <id> --pipeline-id <pid>job-logpipelines job-log --project <id> --job-id <jid>retrypipelines retry --project <id> --pipeline-id <pid>cancelpipelines cancel --project <id> --pipeline-id <pid>createpipelines create --project <id> --ref "main"``--variables "K1=v1,K2=v2"

Groups#

ActionUsageOptionslistgroups list``--search --ownedgetgroups get <id>projectsgroups projects <id>``--searchmembersgroups members <id>issuesgroups issues <id>``--statemrsgroups mrs <id>``--state

Users#

ActionUsagemeusers melistusers list [--search "john"]getusers get <id>projectsusers projects <id>

Labels#

ActionUsageOptionslistlabels list --project <id>createlabels create --project <id> --name "bug" --color "#FF0000"``--descriptioneditlabels edit --project <id> --name "bug"``--new-name --colordeletelabels delete --project <id> --name "bug"

Milestones#

ActionUsageOptionslistmilestones list --project <id>``--stategetmilestones get --project <id> --milestone-id <mid>createmilestones create --project <id> --title "v1.0"``--description --due-date --start-dateeditmilestones edit --project <id> --milestone-id <mid>``--title --state-eventdeletemilestones delete --project <id> --milestone-id <mid>

Tags & Releases#

ActionUsageOptionstags listtags list --project <id>``--searchtags createtags create --project <id> --tag-name "v1.0" --ref "main"``--messagetags deletetags delete --project <id> --tag-name "v1.0"releases listreleases list --project <id>releases createreleases create --project <id> --tag-name "v1.0" --name "R1"``--description

Snippets#

ActionUsageOptionslistsnippets list --project <id>getsnippets get --project <id> --snippet-id <sid>createsnippets create --project <id> --title "T" --file-name "f" --content "c"``--visibility

Search#

ActionUsageglobalsearch global --scope <scope> --search "query"projectsearch project --project <id> --scope <scope> --search "query"groupsearch 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#

ActionUsageOptionslistrunners list --project <id>allrunners all``--type --status

Webhooks#

ActionUsageOptionslisthooks list --project <id>createhooks create --project <id> --url "url"``--push-events --merge-requests-events --issues-events --tokendeletehooks 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.