runspec-gitlab

A GitLab runnable for runspec, ported onto the GitLab REST API (v4) — not proxying GitLab's hosted MCP server. One runnable — gitlab — with 17 read verbs (autonomy = "autonomous"), 15 write verbs (autonomy = "confirm", so an agent asks before each one) and 4 delete verbs (autonomy = "manual", so only a person can run them). pip install it into a venv and it's discoverable by runspec local, runspec serve (MCP), and runspec-console.

runspec serve flattens each verb into a leaf MCP tool (gitlab_get-issue, …). Verb names are reconciled against GitLab's canonical MCP tool registry; the extras (whoami, get-project, search-projects, list-issues, get-file, list-tree) are useful REST reads GitLab has no MCP tool for.

Install

pip install runspec-gitlab

Verbs

Writes (all confirm):

Assignees and reviewers are given as usernames. Labels, assignees, reviewers and pipeline variables (KEY=VALUE) are repeatable args. Writes need a token with the api scope; reads work with read_api.

Deletes (all manual — refused to an agent, run from the command line or the console's Forms tab): delete-issue, delete-branch, delete-file, delete-pipeline. GitLab itself limits issue and pipeline deletes to project owners/admins and refuses protected or default branches.

get-merge-request-conflicts is best-effort — GitLab has no public /api/v4 conflicts endpoint, so it relays the web-UI endpoint and returns its JSON verbatim.

Auth — env vars only

export GITLAB_URL=https://gitlab.example.com        # default https://gitlab.com
export GITLAB_TOKEN=<personal-or-project-access-token>
export GITLAB_PROJECT=group/subgroup/project        # optional default

Every verb takes --env, selecting GITLAB_<ENV>_* prefixed vars. --project accepts a numeric id or a group/project path and falls back to GITLAB_PROJECT.

gitlab whoami
gitlab list-merge-requests --project group/app --state opened
gitlab get-job-log --project group/app --job-id 998877
gitlab create-issue --project group/app --title "Login fails" --label bug --assignee alice
gitlab write-file --project group/app --branch fix --start-branch main \
  --file-path docs/notes.md --content-file notes.md --commit-message "Add notes"

Public Python API

The pure logic is in runspec-gitlab-core — httpx-only, no runspec dependency, no entry points. Every op takes a GitlabConfig first arg and raises GitlabError, so a private wrapper can inject credentials and bake in a default project / env:

from runspec_gitlab_core import config_from_env, get_issue, list_merge_requests

cfg = config_from_env(env="prod")
mrs = list_merge_requests(cfg, state="opened")

Development

python -m venv .venv && . .venv/bin/activate
pip install -e ".[dev]"
ruff check . && ruff format --check .
pytest