gitlab_list_project_jobs
List and filter project jobs across GitLab CI/CD pipelines for monitoring, troubleshooting, and job history review. Supports pagination and status-based scoping for efficient navigation.
Instructions
List all jobs for a project Returns: Array of jobs across all pipelines with filtering options Use when: Monitoring project CI/CD, finding recent failures, browsing job history Pagination: Yes (default 20 per page) Filtering: By job status/scope (failed, success, running, etc.)
Example response: [{ "id": 67890, "name": "deploy:staging", "stage": "deploy", "status": "failed", "pipeline": {"id": 123, "ref": "main"}, "commit": {"short_id": "abc1234"}, "created_at": "2023-01-01T15:30:00Z", "user": {"name": "Jane Doe"} }]
Related tools:
gitlab_list_pipeline_jobs: Jobs for specific pipeline
gitlab_list_pipelines: Find pipeline information
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number for pagination Type: integer Range: ≥1 Default: 1 Example: 3 (to get the third page of results) Note: Use with per_page to navigate large result sets | |
| per_page | No | Number of results per page Type: integer Range: 1-100 Default: 20 Example: 50 (for faster browsing) Tip: Use smaller values (10-20) for detailed operations, larger (50-100) for listing | |
| project_id | No | Project identifier (auto-detected if not provided) Type: integer OR string Format: numeric ID or 'namespace/project' Optional: Yes - auto-detects from current git repository Examples: - 12345 (numeric ID) - 'gitlab-org/gitlab' (namespace/project path) - 'my-group/my-subgroup/my-project' (nested groups) Note: If in a git repo with GitLab remote, this can be omitted | |
| scope | No | Job scope filter Type: string Format: Filter jobs by status Options: 'created' | 'pending' | 'running' | 'failed' | 'success' | 'canceled' | 'skipped' | 'waiting_for_resource' | 'manual' Examples: - 'failed' (only failed jobs) - 'success' (only successful jobs) - 'running' (currently running jobs) |
Implementation Reference
- src/mcp_gitlab/tool_handlers.py:646-653 (handler)The main handler function that resolves the project ID (auto-detects from git repository if not provided), extracts optional scope filter and pagination parameters, and delegates to GitLabClient.list_project_jobs to fetch the list of CI/CD jobs for the project.def handle_list_project_jobs(client: GitLabClient, arguments: Optional[Dict[str, Any]]) -> Dict[str, Any]: """Handle listing jobs for a project""" project_id = require_project_id(client, arguments) scope = get_argument(arguments, "scope") per_page = get_argument(arguments, "per_page", DEFAULT_PAGE_SIZE) page = get_argument(arguments, "page", 1) return client.list_project_jobs(project_id, scope=scope, per_page=per_page, page=page)
- Pydantic/MCP schema definition for the tool, including input parameters (project_id optional with auto-detection, scope enum for job status filtering, standard pagination) and description.types.Tool( name=TOOL_LIST_PROJECT_JOBS, description=desc.DESC_LIST_PROJECT_JOBS, inputSchema={ "type": "object", "properties": { "project_id": {"type": "string", "description": desc.DESC_PROJECT_ID}, "scope": {"type": "string", "description": desc.DESC_JOB_SCOPE, "enum": ["created", "pending", "running", "failed", "success", "canceled", "skipped", "waiting_for_resource", "manual"]}, "per_page": {"type": "integer", "description": desc.DESC_PER_PAGE, "default": DEFAULT_PAGE_SIZE, "minimum": 1, "maximum": MAX_PAGE_SIZE}, "page": {"type": "integer", "description": desc.DESC_PAGE_NUMBER, "default": 1, "minimum": 1} } } ),
- src/mcp_gitlab/tool_handlers.py:1019-1021 (registration)Registration of the handler function in the central TOOL_HANDLERS dictionary mapping, which is used by server.py's @server.call_tool() to dispatch tool calls to the appropriate handler.TOOL_LIST_PIPELINE_JOBS: handle_list_pipeline_jobs, TOOL_LIST_PROJECT_JOBS: handle_list_project_jobs,
- src/mcp_gitlab/tool_handlers.py:1068-1071 (registration)Additional registration entry in the TOOL_HANDLERS dict (duplicate key overwrites with same handler).TOOL_LIST_PIPELINE_JOBS: handle_list_pipeline_jobs, TOOL_DOWNLOAD_JOB_ARTIFACT: handle_download_job_artifact, TOOL_LIST_PROJECT_JOBS: handle_list_project_jobs,
- src/mcp_gitlab/constants.py:213-213 (helper)Constant definition for the tool name string used across handler registration, schemas, and tests.TOOL_LIST_PROJECT_JOBS = "gitlab_list_project_jobs"