gitlab_list_releases
Retrieve project releases with descriptions, assets, and release notes to find versions and access release information.
Instructions
List project releases Returns: GitLab releases (not just tags) Use when: Finding versions, release notes Includes: Assets, release notes, links
Different from tags:
Releases have descriptions, assets
Tags are just git references
Related tools:
gitlab_list_tags: Simple tag list
gitlab_create_release: Create release
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| 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 | |
| order_by | No | Field to sort by Type: string (enum) Options vary by endpoint: - Commits: 'created_at', 'title' - Issues: 'created_at', 'updated_at', 'priority', 'due_date' - MRs: 'created_at', 'updated_at', 'title' Default: Usually 'created_at' Example: 'updated_at' to see recently modified items first | released_at |
| sort | No | Sort direction Type: string (enum) Options: 'asc' | 'desc' Default: Varies by context (usually 'desc' for time-based) Examples: - 'asc': A→Z, oldest→newest, smallest→largest - 'desc': Z→A, newest→oldest, largest→smallest | desc |
| 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:398-407 (handler)Handler function that implements the core logic for the gitlab_list_releases tool. Extracts parameters, detects project if needed, and calls the GitLabClient to fetch releases.
def handle_list_releases(client: GitLabClient, arguments: Optional[Dict[str, Any]]) -> Dict[str, Any]: """Handle listing project releases""" project_id = require_project_id(client, arguments) order_by = get_argument(arguments, "order_by", "released_at") sort = get_argument(arguments, "sort", "desc") per_page = get_argument(arguments, "per_page", DEFAULT_PAGE_SIZE) page = get_argument(arguments, "page", 1) return client.list_releases(project_id, order_by, sort, per_page, page) - src/mcp_gitlab/tool_handlers.py:1012-1013 (registration)Registration of the handler function in the TOOL_HANDLERS dictionary, mapping the tool name to its handler.
TOOL_LIST_TAGS: handle_get_tags, TOOL_LIST_RELEASES: handle_list_releases, - Tool schema definition and registration in the TOOLS list, including input schema validation for parameters like project_id, order_by, sort, pagination.
types.Tool( name=TOOL_LIST_RELEASES, description=desc.DESC_LIST_RELEASES, inputSchema={ "type": "object", "properties": { "project_id": {"type": "string", "description": desc.DESC_PROJECT_ID}, "order_by": {"type": "string", "description": desc.DESC_ORDER_BY, "enum": ["released_at", "created_at"], "default": "released_at"}, "sort": {"type": "string", "description": desc.DESC_SORT_ORDER, "enum": ["asc", "desc"], "default": "desc"}, "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:197-197 (helper)Constant definition for the tool name used across the codebase for consistency.
TOOL_LIST_RELEASES = "gitlab_list_releases"