gitlab_list_project_jobs

Monitor CI/CD pipelines by retrieving all jobs for a GitLab project with filtering by status and pagination support.

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
`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)
`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
`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

Implementation Reference

src/mcp_gitlab/tool_handlers.py:646-653 (handler)

The main handler function that executes the gitlab_list_project_jobs tool. It resolves the project ID, extracts parameters like scope, pagination, and calls the GitLabClient's list_project_jobs method.

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)

src/mcp_gitlab/tool_handlers.py:1020-1020 (registration)
Registration of the handler function in the TOOL_HANDLERS dictionary, which is used by the server to dispatch tool calls to the appropriate handler.
```
TOOL_LIST_PROJECT_JOBS: handle_list_project_jobs,
```

src/mcp_gitlab/tool_definitions.py:814-826 (schema)

Pydantic/MCP schema definition for the gitlab_list_project_jobs tool, including input parameters like project_id, scope, and pagination.

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/server.py:953-965 (registration)

Tool registration in the server's list_tools() method, which exposes the schema to MCP clients.

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:75-81 (helper)

Helper function used by the handler to resolve or detect the project_id, raising an error if not available.

def require_project_id(client: GitLabClient, arguments: Optional[Dict[str, Any]]) -> str:
    """Get project_id or raise error if not found"""
    project_id = get_project_id_or_detect(client, arguments)
    if not project_id:
        raise ValueError(ERROR_NO_PROJECT)
    return project_id

MCP GitLab Server