gitlab_list_commits

View and filter repository commit history by date, branch, or file path to track changes and find specific modifications.

Instructions

List repository commits Returns: Array of commits with details Use when: Viewing history, finding specific changes Filtering: By date range, file path, branch Pagination: Yes (default 20 per page)

Example response: [{ "id": "e83c5163316f89bfbde7d9ab23ca2e25604af290", "short_id": "e83c516", "title": "Fix critical bug", "author_name": "John Doe", "committed_date": "2024-01-15T14:30:00Z", "message": "Fix critical bug\n\nDetailed explanation..." }]

Related tools:

gitlab_get_commit: Full commit details
gitlab_get_commit_diff: See changes
gitlab_search_in_project: Search commits

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
`ref_name`	No	Git reference Type: string Format: branch name, tag name, or tag name Optional: Yes - defaults to project's default branch Examples: - 'main' (branch) - 'feature/new-login' (feature branch) - 'v2.0.0' (tag) - 'abc1234' (short tag name) - 'e83c5163316f89bfbde7d9ab23ca2e25604af290' (full SHA) Default: Project's default branch (usually 'main' or 'master')
`since`	No	Start date for filtering Type: string Format: ISO 8601 (YYYY-MM-DD or full timestamp) Optional: Yes Examples: - '2024-01-01' (from start of year) - '2024-01-01T00:00:00Z' (with time, UTC) - '2024-01-01T09:00:00+02:00' (with timezone) Timezone: Defaults to UTC if not specified Use case: Filter commits/events after a specific date
`until`	No	End date for filtering Type: string Format: ISO 8601 (YYYY-MM-DD or full timestamp) Optional: Yes Examples: - '2024-12-31' (until end of year) - '2024-12-31T23:59:59Z' (end of day, UTC) - '2024-12-31T17:00:00-05:00' (with timezone) Timezone: Defaults to UTC if not specified Use case: Filter commits/events before a specific date
`path`	No	File path filter for commits Type: string Format: Relative file path Optional: Yes Examples: - 'src/main.py' (commits touching this file) - 'docs/' (commits in docs directory) - 'package.json' (dependency updates) Use case: Track history of specific files
`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:186-197 (handler)

Handler function that processes arguments and calls GitLabClient.get_commits to list commits for a project.

def handle_get_commits(client: GitLabClient, arguments: Optional[Dict[str, Any]]) -> Dict[str, Any]:
    """Handle getting commits"""
    project_id = require_project_id(client, arguments)
    ref_name = get_argument(arguments, "ref_name")
    since = get_argument(arguments, "since")
    until = get_argument(arguments, "until")
    path = get_argument(arguments, "path")
    per_page = get_argument(arguments, "per_page", DEFAULT_PAGE_SIZE)
    page = get_argument(arguments, "page", 1)
    
    return client.get_commits(project_id, ref_name, since, until, path, per_page, page)

src/mcp_gitlab/tool_handlers.py:1010-1011 (registration)
Maps the tool name 'gitlab_list_commits' to its handler function in TOOL_HANDLERS dictionary, used by server.call_tool.
```
TOOL_LIST_COMMITS: handle_get_commits,
TOOL_LIST_REPOSITORY_TREE: handle_get_repository_tree,
```

src/mcp_gitlab/tool_definitions.py:285-299 (schema)

Pydantic/MCP schema definition for gitlab_list_commits tool inputs.

    name=TOOL_LIST_COMMITS,
    description=desc.DESC_LIST_COMMITS,
    inputSchema={
        "type": "object",
        "properties": {
            "project_id": {"type": "string", "description": desc.DESC_PROJECT_ID},
            "ref_name": {"type": "string", "description": desc.DESC_REF.replace("commit SHA", "tag name")},
            "since": {"type": "string", "description": desc.DESC_DATE_SINCE},
            "until": {"type": "string", "description": desc.DESC_DATE_UNTIL},
            "path": {"type": "string", "description": desc.DESC_PATH_FILTER},
            "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:424-438 (registration)

Explicit registration of gitlab_list_commits tool in MCP server's @list_tools handler.

    name=TOOL_LIST_COMMITS,
    description=desc.DESC_LIST_COMMITS,
    inputSchema={
        "type": "object",
        "properties": {
            "project_id": {"type": "string", "description": desc.DESC_PROJECT_ID},
            "ref_name": {"type": "string", "description": desc.DESC_REF.replace("commit SHA", "tag name")},
            "since": {"type": "string", "description": desc.DESC_DATE_SINCE},
            "until": {"type": "string", "description": desc.DESC_DATE_UNTIL},
            "path": {"type": "string", "description": desc.DESC_PATH_FILTER},
            "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/constants.py:191-191 (helper)
Constant definition for the tool name 'gitlab_list_commits'.
```
TOOL_LIST_COMMITS = "gitlab_list_commits"
```

MCP GitLab Server