list_pipelines
Retrieve and filter GitLab project pipelines by status, branch, commit, or other criteria to monitor CI/CD workflow execution.
Instructions
List pipelines in a project
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | Project ID or path | |
| status | No | Filter by pipeline status | |
| ref | No | Filter by branch or tag name | |
| sha | No | Filter by commit SHA | |
| yaml_errors | No | Filter pipelines with YAML errors | |
| name | No | Filter by pipeline name | |
| username | No | Filter by username of the user who triggered the pipeline | |
| updated_after | No | Filter pipelines updated after this date (ISO 8601 format) | |
| updated_before | No | Filter pipelines updated before this date (ISO 8601 format) | |
| order_by | No | Order pipelines by field | id |
| sort | No | Sort order | desc |
| per_page | No | Number of results per page (max 100) |
Implementation Reference
- src/handlers/pipelines.ts:13-38 (handler)The main handler function that implements the list_pipelines tool by querying the GitLab API for pipelines in a project, applying filters from params, and returning JSON-formatted response.
async listPipelines(args: ListPipelinesParams) { const params = new URLSearchParams(); if (args.status) params.append('status', args.status); if (args.ref) params.append('ref', args.ref); if (args.sha) params.append('sha', args.sha); if (args.yaml_errors !== undefined) params.append('yaml_errors', String(args.yaml_errors)); if (args.name) params.append('name', args.name); if (args.username) params.append('username', args.username); if (args.updated_after) params.append('updated_after', args.updated_after); if (args.updated_before) params.append('updated_before', args.updated_before); if (args.order_by) params.append('order_by', args.order_by); if (args.sort) params.append('sort', args.sort); params.append('per_page', String(args.per_page || 20)); const data = await this.client.get(`/projects/${encodeURIComponent(args.project_id)}/pipelines?${params.toString()}`); return { content: [ { type: 'text', text: JSON.stringify(data, null, 2), }, ], }; } - src/types.ts:347-360 (schema)TypeScript interface defining the input parameters for the list_pipelines handler.
export interface ListPipelinesParams { project_id: string; status?: GitLabPipeline['status']; ref?: string; sha?: string; yaml_errors?: boolean; name?: string; username?: string; updated_after?: string; updated_before?: string; order_by?: 'id' | 'status' | 'ref' | 'updated_at' | 'user_id'; sort?: 'asc' | 'desc'; per_page?: number; } - src/tools/pipelines.ts:5-68 (schema)JSON schema defining the input parameters and validation for the list_pipelines tool, used in MCP tool registration.
name: 'list_pipelines', description: 'List pipelines in a project', inputSchema: { type: 'object', properties: { project_id: { type: 'string', description: 'Project ID or path', }, status: { type: 'string', enum: ['created', 'waiting_for_resource', 'preparing', 'pending', 'running', 'success', 'failed', 'canceled', 'skipped', 'manual', 'scheduled'], description: 'Filter by pipeline status', }, ref: { type: 'string', description: 'Filter by branch or tag name', }, sha: { type: 'string', description: 'Filter by commit SHA', }, yaml_errors: { type: 'boolean', description: 'Filter pipelines with YAML errors', }, name: { type: 'string', description: 'Filter by pipeline name', }, username: { type: 'string', description: 'Filter by username of the user who triggered the pipeline', }, updated_after: { type: 'string', description: 'Filter pipelines updated after this date (ISO 8601 format)', }, updated_before: { type: 'string', description: 'Filter pipelines updated before this date (ISO 8601 format)', }, order_by: { type: 'string', enum: ['id', 'status', 'ref', 'updated_at', 'user_id'], description: 'Order pipelines by field', default: 'id', }, sort: { type: 'string', enum: ['asc', 'desc'], description: 'Sort order', default: 'desc', }, per_page: { type: 'number', description: 'Number of results per page (max 100)', maximum: 100, default: 20, }, }, required: ['project_id'], }, }, - src/server.ts:287-290 (registration)Dispatch case in the main server tool call handler that routes 'list_pipelines' calls to the PipelineHandlers.listPipelines method.
case "list_pipelines": return await this.pipelineHandlers.listPipelines( args as unknown as ListPipelinesParams ); - src/tools/pipelines.ts:4-68 (registration)Tool definition and registration in the pipelineTools array, which is aggregated into allTools for the MCP list_tools response.
{ name: 'list_pipelines', description: 'List pipelines in a project', inputSchema: { type: 'object', properties: { project_id: { type: 'string', description: 'Project ID or path', }, status: { type: 'string', enum: ['created', 'waiting_for_resource', 'preparing', 'pending', 'running', 'success', 'failed', 'canceled', 'skipped', 'manual', 'scheduled'], description: 'Filter by pipeline status', }, ref: { type: 'string', description: 'Filter by branch or tag name', }, sha: { type: 'string', description: 'Filter by commit SHA', }, yaml_errors: { type: 'boolean', description: 'Filter pipelines with YAML errors', }, name: { type: 'string', description: 'Filter by pipeline name', }, username: { type: 'string', description: 'Filter by username of the user who triggered the pipeline', }, updated_after: { type: 'string', description: 'Filter pipelines updated after this date (ISO 8601 format)', }, updated_before: { type: 'string', description: 'Filter pipelines updated before this date (ISO 8601 format)', }, order_by: { type: 'string', enum: ['id', 'status', 'ref', 'updated_at', 'user_id'], description: 'Order pipelines by field', default: 'id', }, sort: { type: 'string', enum: ['asc', 'desc'], description: 'Sort order', default: 'desc', }, per_page: { type: 'number', description: 'Number of results per page (max 100)', maximum: 100, default: 20, }, }, required: ['project_id'], }, },