gitlab-cli

Usage conventions

Note: The following script calls all use the folder where the current SKILL.md is located as the workdir.

Script invocation method (must be run directly as an executable command, do not use uv run python or python）：

cd skills/gitlab-cli && ./scripts/gitlab_cli.py --help

Incorrect example:

uv run python skills/gitlab-cli/scripts/gitlab_cli.py --help
python skills/gitlab-cli/scripts/gitlab_cli.py --help

When the target GitLab repository is not the current directory, use --cwd <repo> to specify the actual execution directory.
When a self-hosted instance needs to override the default host, use --hostname <host>。
When not in the target repository, or when the current directory is not a GitLab repository, use --project <id|group/project> to explicitly specify the project.

Body argument constraints

When creating or updating an MR / Issue, the body must be passed via --description-file <path> .
Do not use the shell to pass multi-line bodies directly; the script does not support --description。
--title Short text arguments like these can be passed directly; for long bodies, always write them to a file first and then reference it.

Example:

# 正确
./scripts/gitlab_cli.py mr update --cwd /path/to/repo 123 --description-file /tmp/mr-body.md

# 错误
./scripts/gitlab_cli.py mr update --cwd /path/to/repo 123 --description "multi-line body"

Pre-creation checks

Before creating an Issue or MR, first check the corresponding GitLab templates, forms, and current resource status.

Prioritize checking issue / MR templates, as well as .gitlab/issue_templates/、.gitlab/merge_request_templates/、.gitlab-ci.yml, project documentation, and other GitLab-specific configurations.
Issue/MR titles and bodies should be written in accordance with SKILL.md。
Before formal creation, check whether the current code, branch, and commit status are consistent with the content to be submitted to the platform, to avoid creating an Issue or MR that does not match the current state.

Create Issue (non-interactive)

The following specifications are based on the premise that the "pre-creation checks" have been completed.

Prepare the title and body first according to SKILL.md .
By default, write the Issue body to a local Markdown file first; prefer placing the draft in /tmp/*.md. Titles are usually short and can be passed directly with --title .
When creating and modifying, prefer using --description-file, for example:./scripts/gitlab_cli.py issue create --cwd /path/to/repo --title "..." --description-file /tmp/issue-body.md, or ./scripts/gitlab_cli.py issue update --cwd /path/to/repo 123 --title "..." --description-file /tmp/issue-body.md。
After successful creation, output the full Issue URL.

Create MR

The following specifications are based on the premise that the "pre-creation checks" have been completed.

First complete the "pre-creation checks".
Only create the MR after confirming that both the repository requirements and the local code/commit status are satisfied; if they are found not to be satisfied, fix them first, then create.
git status must be clean, and the current branch must have been pushed to the remote.
Prepare the title and body first according to SKILL.md .
By default, write the MR body to a local Markdown file first; prefer placing the draft in /tmp/*.md. Do not build multi-line strings in the shell, and do not rely on interactive editing. Titles are usually short and can be passed directly with --title .
When creating an MR, prefer using --description-file, for example:

./scripts/gitlab_cli.py mr create \
  --cwd /path/to/repo \
  --title "feat(scope): short summary" \
  --description-file /tmp/mr-body.md \
  --target-branch main \
  --squash true \
  --remove-source-branch true

When modifying an MR, also reuse the local file to avoid manual editing, for example:./scripts/gitlab_cli.py mr update --cwd /path/to/repo 123 --title "..." --description-file /tmp/mr-body.md。
After successful creation, output the full MR URL.

When to use glab directly

Viewing and listing:glab issue view、glab issue list、glab mr view、glab mr diff
CI blocking wait: prefer using glab ci status --live and other methods to wait for the pipeline to finish; when you need to follow a single job's logs, use glab ci trace <job-id|job-name>
Comments:glab issue note
Organizing review feedback: first read MR discussions / notes / diff comments, then organize them uniformly
When the user explicitly requests adjusting the project merge / squash strategy, refer to squash-merge-policy.md
First confirm the capability boundary:glab <group> --help、glab <group> <subcommand> --help
wiki: first check glab wiki --help; if the current version does not have the subcommand, then consider glab api

CI waiting and log following

When waiting for the latest pipeline of the current branch to complete, do not hand-write periodic polling; just run:

glab ci status --live --compact

When waiting for a pipeline on a specified branch or another repository to complete, use:

glab ci status --branch main --live --compact
glab ci status --branch main --live --compact -R group/project

When you need to watch a job's real-time logs and block until the logs end, use:

glab ci trace 123456
glab ci trace test --pipeline-id 123456 --branch main

glab ci status --live It is suitable for replacing the agent's own polling wait; after the wait ends, if you need to write the result into an MR / Issue / reply, first use glab ci status --output json、glab ci get --with-job-details or glab ci list --output json to do a final state read, to avoid drawing conclusions based only on dynamic terminal output.
When you need to lock onto a specific pipeline by pipeline ID, prefer using glab ci view --pipelineid <id> for interactive viewing; if the task requires a non-interactive, machine-parseable final state, switch to glab ci get or glab api to read that pipeline / jobs.

Scenarios supported by the script

GitLab CI lint: validate local .gitlab-ci.yml, supports --dry-run、--include-jobs、--ref、--json。
- --dry-run --ref refs/merge-requests/<iid>/head will switch to using the MR source branch to call CI Lint. When the caller knows the source branch, it can explicitly pass --source-branch <branch>; otherwise the script will query the MR metadata based on the MR IID in the ref. Some GitLab 14.x instances will, because the MR internal ref lacks source_branch , return 500 in the CI Lint dry-run, so the script avoids sending the MR internal ref directly to CI Lint.
MR create: create an MR non-interactively, can be used with --cwd、--hostname、--project .
MR update: non-interactively update MR title, body, labels, reviewers, assignees, milestone, and merge-related options.
Issue create: create an Issue non-interactively, can set body, labels, assignees, milestone, confidential, due date.
Issue update: non-interactively update Issue title, body, labels, assignees, milestone, confidential, due date.

Otherwise, prefer to directly use glab。

Script entry point: run gitlab_cli.py

Common subcommands

CI validation:

./scripts/gitlab_cli.py ci lint --cwd /path/to/repo
./scripts/gitlab_cli.py ci lint --cwd /path/to/repo --project group/project --ref main --dry-run --include-jobs
./scripts/gitlab_cli.py ci lint --cwd /path/to/repo --project 122477 --ref refs/merge-requests/9/head --dry-run
./scripts/gitlab_cli.py ci lint --cwd /path/to/repo --project 122477 --ref refs/merge-requests/9/head --source-branch chore/sync-knots-api-master --dry-run

Create MR:

./scripts/gitlab_cli.py mr create \
  --cwd /path/to/repo \
  --title "feat(scope): short summary" \
  --target-branch main \
  --description-file /tmp/mr-body.md \
  --squash true \
  --remove-source-branch true

Update MR:

./scripts/gitlab_cli.py mr update \
  --cwd /path/to/repo \
  123 \
  --description-file /tmp/mr-body.md

Create Issue:

./scripts/gitlab_cli.py issue create \
  --cwd /path/to/repo \
  --title "short summary" \
  --description-file /tmp/issue-body.md

Update Issue:

./scripts/gitlab_cli.py issue update \
  --cwd /path/to/repo \
  456 \
  --title "updated title" \
  --description-file /tmp/issue-body.md

Before creating or updating

Before updating an Issue or MR title/body, first read the current content, then modify it.
The body may only be passed via --description-file ; the script no longer supports --description, to avoid shell escaping and multi-line text handling issues.
Before creating an MR, first check whether the template, target branch, current branch, and workspace status meet the repository requirements; unless the repository or the user explicitly requires keeping multiple commits or keeping the source branch, explicitly pass --squash true and --remove-source-branch true。
When creating or updating an Issue/MR title and body, regenerate the text according to SKILL.md .
Before creating an Issue, first check whether the template, labels, reproduction information, and current status are consistent.