io.github.mshegolev/gitlab-ci-mcp

Read a text file from the repository, truncated to 500 lines. For binaries, gets decoded as UTF-8 with errors replaced — you will likely get garbage; use for text content only. Examples: - "Show me .gitlab-ci.yml on master" → ``file_path='.gitlab-ci.yml'`` - "Read src/app.py from the release-1.2 tag" → ``file_path='src/app.py'``, ``ref='release-1.2'`` - Don't use for listings — use ``gitlab_list_repository_tree``.

List files and directories at a given path in the repository. Examples: - "Show top-level files" → default call - "All .py files recursively" → ``recursive=True`` then filter on ``.py`` in path - Don't use for full-text content — use ``gitlab_get_file`` for that.

Return basic metadata about a project: ID, default branch, visibility, counts. Examples: - "What's the project ID and default branch" → default call - "Is this repo public or private" → look at ``visibility``

List branches of a project, optionally filtered by substring. Includes ``default``, ``protected`` and ``merged`` flags, and the short id of the tip commit with its title and date. Examples: - "List all branches with 'release' in name" → ``search='release'`` - "Next page of branches" → ``page=2`` - Don't use when you want to check if a specific branch exists by exact name — use ``gitlab_get_file`` on that ref and look at the error instead.

List tags of a project, newest first. Useful for release-note generation or checking the last shipped version. Examples: - "What was the last release tag" → default call, take the first item - "All v2.x releases" → ``search='v2.'``

Compare two branches — returns up to 30 commits and the list of changed files. Use for "what's in ``release/x.y`` vs ``master``?" or for release-note drafting. Examples: - "What's new in release/1.5 vs master" → ``source='release/1.5'``, ``target='master'`` - Don't use to fetch full diffs of an MR — use ``gitlab_get_merge_request_changes``.

List recent pipelines of a project, newest first. Use for triage ("show failed pipelines on master"), release readiness checks, or feeding pipeline IDs into follow-up calls. Read-only and idempotent. Returns ``PipelinesListOutput``: ``project``, ``count``, ``pagination`` and ``pipelines[]`` (each ``PipelineSummary``). The tool result additionally carries a markdown table in its text content. Examples: - "Show failed pipelines on master" → ``status='failed'``, ``ref='master'`` - "Last nightly schedule runs" → ``source='schedule'`` - "Second page of pipelines" → ``page=2`` - Don't use when you have a specific pipeline ID — use ``gitlab_get_pipeline`` instead.

Get a single pipeline with full timing details. Useful right after ``gitlab_list_pipelines`` — lists only return summaries. Returns status, ref, source, durations (queued/total), and started/finished timestamps. Examples: - "Why was pipeline 123 slow" → check ``queued_duration`` and ``duration`` fields - "Is pipeline 456 still running" → look at ``status`` - Don't use to see individual jobs — use ``gitlab_get_pipeline_jobs``.

List jobs of a pipeline with stage, status, duration and web URL. Use after noticing a failed pipeline to drill down into which specific job broke and fetch its log via ``gitlab_get_job_log``. Examples: - "What jobs are in pipeline 123" → ``pipeline_id=123`` - "Which job failed in pipeline 456" → filter result by ``status='failed'`` client-side - Don't use for overall pipeline status — use ``gitlab_get_pipeline`` instead.

Fetch the trace/log of a job, with optional regex filter. Two modes: * Default: return the last ``tail`` lines (token-efficient, good for "why did this just fail?"). * With ``grep_pattern``: return only matching lines with ``grep_context`` surrounding lines on each side — ideal for finding "ERROR" / "Traceback" in megabyte-scale CI logs without pulling the whole trace into context. Examples: - "Why did job 789 fail" → default tail=100, look at the end of the log - "Show me the first stage output of job 789" → ``tail=5000`` and scan for stage separator - "Find every Traceback in job 789" → ``grep_pattern='Traceback'``, ``grep_context=5`` - "All ERROR lines from job 789" → ``grep_pattern='ERROR|FAIL'``

Create a new pipeline on the given ref, optionally with CI variables. **Not idempotent**: each call creates a new pipeline. Consumes minutes on your runners — avoid calling in loops. Examples: - "Run the pipeline on master" → default (``ref='master'``) - "Run the pipeline on feature/x with DEBUG=1" → ``ref='feature/x'``, ``variables={'DEBUG': '1'}`` - Don't call to retry — use ``gitlab_retry_pipeline`` which keeps the same pipeline ID.

Retry all failed jobs of an existing pipeline. Creates new job runs (new history entries). Safe to call when the pipeline has at least one failed/canceled job; has no effect if everything already passed. Examples: - "Retry the failed jobs in pipeline 123" → ``pipeline_id=123`` - Don't use to rerun a successful pipeline — use ``gitlab_trigger_pipeline`` instead.

Cancel a running pipeline. In-flight jobs will be interrupted. Destructive for *in-progress* work. Cancelling an already-finished pipeline is a no-op. Examples: - "Pipeline 123 is stuck, cancel it" → ``pipeline_id=123`` - Don't use on finished pipelines — no effect; use ``gitlab_retry_pipeline`` if you want to rerun it.

Aggregate success rate over 7 and 30 days with a trend indicator. Great for stand-ups and on-call hand-offs. Returns success rate %, totals, last-10 statuses and a trend (``up``/``down``/``flat``). Emits progress via the MCP Context (``info`` log + ``report_progress``) — useful in IDEs that show per-tool progress bars. Examples: - "How stable is master" → default (``ref='master'``, ``source='schedule'``) - "Push-driven pipeline health" → ``source='push'`` - Don't use for a single pipeline — use ``gitlab_get_pipeline``.

List merge requests of a project, optionally filtered by state. Examples: - "What MRs are open right now" → default (state='opened') - "What merged last week" → ``state='merged'`` then filter by ``updated_at`` client-side - "Everything regardless of state" → ``state='all'`` - Don't use when you have an MR IID — use ``gitlab_get_merge_request`` for detail.

Get full information about a merge request by internal ID (``iid``). Includes state, branches, author, assignees, reviewers, labels, conflict status, description and timestamps. Examples: - "Show me the description and state of !42" → ``mr_iid=42`` - Don't use to see changed files — use ``gitlab_get_merge_request_changes``.

List changed files in a merge request with truncated diffs (2KB per file). Useful for code-review-style queries ("what changed in !42?"). Diffs beyond 2KB are truncated — fetch the raw file via ``gitlab_get_file`` for full content. Examples: - "What did MR !42 change" → ``mr_iid=42`` - If you need full content of a changed file, use ``gitlab_get_file`` with the MR's source branch.

Create a merge request from ``source_branch`` into ``target_branch``. **Not idempotent**: creates a new MR each call. Check existing MRs first via ``gitlab_list_merge_requests`` if you want to avoid duplicates. Examples: - "Open an MR from feature/login to master" → ``source_branch='feature/login'`` - "Open a WIP MR with a label" → ``title='Draft: ...'``, ``labels=['wip']`` - Don't use to merge an already-open MR — use ``gitlab_merge_mr``.

Perform the actual merge if GitLab reports the MR can be merged. **Destructive**: writes to the target branch. Checks ``merge_status`` first and returns ``status='cannot_merge'`` if conflicts exist or pipelines are required. Examples: - "Merge !42" → ``mr_iid=42`` - Don't call without checking ``gitlab_get_merge_request`` first when you suspect conflicts.

List all CI/CD schedules of a project. Variable keys whose name hints at a secret (``TOKEN``, ``PASSWORD``, ``SECRET``, ``CREDENTIAL``, ``PRIVATE_KEY``, ``API_KEY``) keep the key but have the value replaced by ``***`` so the agent still sees which variables exist. Examples: - "What schedules do we have and are they all active" → default call - Don't use to *run* a schedule now — use ``gitlab_trigger_pipeline`` with the schedule's variables instead.

Create a new CI/CD schedule with the given cron and variables. **Not idempotent**: duplicate calls create duplicate schedules with auto-incrementing IDs. Examples: - "Schedule a nightly build on master at 02:00 Europe/Berlin" → ``description='Nightly build'``, ``cron='0 2 * * *'``, ``ref='master'``, ``timezone='Europe/Berlin'``, ``variables={'NIGHTLY': '1'}`` - Don't use to update existing schedules — use ``gitlab_update_schedule``.

Update an existing schedule. Only provided fields change. Destructive when ``variables`` is set: the entire variable set is replaced, so ensure the caller sends a full list. Examples: - "Deactivate schedule 42" → ``schedule_id=42``, ``active=False`` - "Change cron of schedule 42 to hourly" → ``schedule_id=42``, ``cron='0 * * * *'`` - Don't pass ``variables`` unless you want to *replace* them entirely.

Delete a schedule by ID. Cannot be undone. Examples: - "Delete schedule 42" → ``schedule_id=42`` - If you only want to pause it temporarily, call ``gitlab_update_schedule`` with ``active=False`` instead.