Automate GitLab operations including project management, issue tracking, merge request workflows, CI/CD pipeline monitoring, branch management, and user administration through Composio's GitLab toolkit.
Toolkit docs
:
composio.dev/toolkits/gitlab
Prerequisites
Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
Active GitLab connection via
RUBE_MANAGE_CONNECTIONS
with toolkit
gitlab
Always call
RUBE_SEARCH_TOOLS
first to get current tool schemas
Setup
Get Rube MCP
Add
https://rube.app/mcp
as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
Verify Rube MCP is available by confirming
RUBE_SEARCH_TOOLS
responds
Call
RUBE_MANAGE_CONNECTIONS
with toolkit
gitlab
If connection is not ACTIVE, follow the returned auth link to complete GitLab OAuth
Confirm connection status shows ACTIVE before running any workflows
Core Workflows
1. Manage Issues
When to use
User wants to create, update, list, or search issues in a GitLab project
Tool sequence
:
GITLAB_GET_PROJECTS
- Find the target project and get its ID [Prerequisite]
GITLAB_LIST_PROJECT_ISSUES
- List and filter issues for a project [Required]
GITLAB_CREATE_PROJECT_ISSUE
- Create a new issue [Required for create]
GITLAB_UPDATE_PROJECT_ISSUE
- Update an existing issue (title, labels, state, assignees) [Required for update]
GITLAB_LIST_PROJECT_USERS
- Find user IDs for assignment [Optional]
Key parameters
:
id
Project ID (integer) or URL-encoded path (e.g.,
"my-group/my-project"
)
title
Issue title (required for creation)
description
Issue body text (max 1,048,576 characters)
labels
Comma-separated label names (e.g.,
"bug,critical"
)
add_labels
/
remove_labels
Add or remove labels without replacing all
state
Filter by
"all"
,
"opened"
, or
"closed"
state_event
:
"close"
or
"reopen"
to change issue state
assignee_ids
Array of user IDs; use
[0]
to unassign all
issue_iid
Internal issue ID within the project (required for updates)
milestone
Filter by milestone title
search
Search in title and description
scope
:
"created_by_me"
,
"assigned_to_me"
, or
"all"
page
/
per_page
Pagination (default per_page: 20)
Pitfalls
:
id
accepts either integer project ID or URL-encoded path; wrong IDs yield 4xx errors
issue_iid
is the project-internal ID (shown as #42), different from the global issue ID
Labels in
labels
field replace ALL existing labels; use
add_labels
/
remove_labels
for incremental changes
Setting
assignee_ids
to empty array does NOT unassign; use
[0]
instead
updated_at
field requires administrator or project/group owner rights
2. Manage Merge Requests
When to use
User wants to list, filter, or review merge requests in a project
Tool sequence
:
GITLAB_GET_PROJECT
- Get project details and verify access [Prerequisite]
GITLAB_GET_PROJECT_MERGE_REQUESTS
- List and filter merge requests [Required]
GITLAB_GET_REPOSITORY_BRANCHES
- Verify source/target branches [Optional]
GITLAB_LIST_ALL_PROJECT_MEMBERS
- Find reviewers/assignees [Optional]
Key parameters
:
id
Project ID or URL-encoded path
state
:
"opened"
,
"closed"
,
"locked"
,
"merged"
, or
"all"
scope
:
"created_by_me"
(default),
"assigned_to_me"
, or
"all"
source_branch
/
target_branch
Filter by branch names
author_id
/
author_username
Filter by MR author
assignee_id
Filter by assignee (use
None
for unassigned,
Any
for assigned)
reviewer_id
/
reviewer_username
Filter by reviewer
labels
Comma-separated label filter
search
Search in title and description
wip
:
"yes"
for draft MRs,
"no"
for non-draft
order_by
:
"created_at"
(default),
"title"
,
"merged_at"
,
"updated_at"
view
:
"simple"
for minimal fields
iids[]
Filter by specific MR internal IDs
Pitfalls
:
Default
scope
is
"created_by_me"
which limits results; use
"all"
for complete listings
author_id
and
author_username
are mutually exclusive
reviewer_id
and
reviewer_username
are mutually exclusive
approved
filter requires the
mr_approved_filter
feature flag (disabled by default)
Large MR histories can be noisy; use filters and moderate
per_page
values
3. Manage Projects and Repositories
When to use
User wants to list projects, create new projects, or manage branches
Tool sequence
:
GITLAB_GET_PROJECTS
- List all accessible projects with filters [Required]
GITLAB_GET_PROJECT
- Get detailed info for a specific project [Optional]
GITLAB_LIST_USER_PROJECTS
- List projects owned by a specific user [Optional]
GITLAB_CREATE_PROJECT
- Create a new project [Required for create]
GITLAB_GET_REPOSITORY_BRANCHES
- List branches in a project [Required for branch ops]
GITLAB_CREATE_REPOSITORY_BRANCH
- Create a new branch [Optional]
GITLAB_GET_REPOSITORY_BRANCH
- Get details of a specific branch [Optional]
GITLAB_LIST_REPOSITORY_COMMITS
- View commit history [Optional]
GITLAB_GET_PROJECT_LANGUAGES
- Get language breakdown [Optional]
Key parameters
:
name
/
path
Project name and URL-friendly path (both required for creation)
visibility
:
"private"
,
"internal"
, or
"public"
namespace_id
Group or user ID for project placement
search
Case-insensitive substring search for projects
membership
:
true
to limit to projects user is a member of
owned
:
true
to limit to user-owned projects
project_id
Project ID for branch operations
branch_name
Name for new branch
ref
Source branch or commit SHA for new branch creation
order_by
:
"id"
,
"name"
,
"path"
,
"created_at"
,
"updated_at"
,
"star_count"
,
"last_activity_at"
Pitfalls
:
GITLAB_GET_PROJECTS
pagination is required for complete coverage; stopping at first page misses projects
Some responses place items under
data.details
; parse the actual returned list structure
Most follow-up calls depend on correct
project_id
; verify with
GITLAB_GET_PROJECT
first
Invalid
branch_name
/
ref
/
sha
causes client errors; verify branch existence via
GITLAB_GET_REPOSITORY_BRANCHES
first
Both
name
and
path
are required for
GITLAB_CREATE_PROJECT
4. Monitor CI/CD Pipelines
When to use
User wants to check pipeline status, list jobs, or monitor CI/CD runs
Tool sequence
:
GITLAB_GET_PROJECT
- Verify project access [Prerequisite]
GITLAB_LIST_PROJECT_PIPELINES
- List pipelines with filters [Required]
GITLAB_GET_SINGLE_PIPELINE
- Get detailed info for a specific pipeline [Optional]
GITLAB_LIST_PIPELINE_JOBS
- List jobs within a pipeline [Optional]
Key parameters
:
id
Project ID or URL-encoded path
status
Filter by
"created"
,
"waiting_for_resource"
,
"preparing"
,
"pending"
,
"running"
,
"success"
,
"failed"
,
"canceled"
,
"skipped"
,
"manual"
,
"scheduled"
scope
:
"running"
,
"pending"
,
"finished"
,
"branches"
,
"tags"
ref
Branch or tag name
sha
Specific commit SHA
source
Pipeline source (use
"parent_pipeline"
for child pipelines)
order_by
:
"id"
(default),
"status"
,
"ref"
,
"updated_at"
,
"user_id"
created_after
/
created_before
ISO 8601 date filters
pipeline_id
Specific pipeline ID for job listing
include_retried
:
true
to include retried jobs (default
false
)
Pitfalls
:
Large pipeline histories can be noisy; use
status
,
ref
, and date filters to narrow results
Use moderate
per_page
values to keep output manageable
Pipeline job
scope
accepts single status string or array of statuses
yaml_errors: true
returns only pipelines with invalid configurations
5. Manage Users and Members
When to use
User wants to find users, list project members, or check user status
Tool sequence
:
GITLAB_GET_USERS
- Search and list GitLab users [Required]
GITLAB_GET_USER
- Get details for a specific user by ID [Optional]
GITLAB_GET_USERS_ID_STATUS
- Get user status message and availability [Optional]
GITLAB_LIST_ALL_PROJECT_MEMBERS
- List all project members (direct + inherited) [Required for member listing]
GITLAB_LIST_PROJECT_USERS
- List project users with search filter [Optional]
Key parameters
:
search
Search by name, username, or public email
username
Get specific user by username
active
/
blocked
Filter by user state
id
Project ID for member listing
query
Filter members by name, email, or username
state
Filter members by
"awaiting"
or
"active"
(Premium/Ultimate)
user_ids
Filter by specific user IDs
Pitfalls
:
Many user filters (admins, auditors, extern_uid, two_factor) are admin-only
GITLAB_LIST_ALL_PROJECT_MEMBERS
includes direct, inherited, and invited members
User search is case-insensitive but may not match partial email domains
Premium/Ultimate features (state filter, seat info) are not available on free plans
Common Patterns
ID Resolution
GitLab uses two identifier formats for projects:
Numeric ID
Integer project ID (e.g.,
123
)
URL-encoded path
Namespace/project format (e.g.,
"my-group%2Fmy-project"
or
"my-group/my-project"
)
Issue IID vs ID
:
issue_iid
is the project-internal number (#42); the global
id
is different
User ID
Numeric; resolve via
GITLAB_GET_USERS
with
search
or
username
Pagination
GitLab uses offset-based pagination:
Set
page
(starting at 1) and
per_page
(1-100, default 20)
Continue incrementing
page
until response returns fewer items than
per_page
or is empty
Total count may be available in response headers (
X-Total
,
X-Total-Pages
)
Always paginate to completion for accurate results
URL-Encoded Paths
When using project paths as identifiers:
Forward slashes must be URL-encoded:
my-group/my-project
becomes
my-group%2Fmy-project
Some tools accept unencoded paths; check schema for each tool
Prefer numeric IDs when available for reliability
Known Pitfalls
ID Formats
Project
id
field accepts both integer and string (URL-encoded path)
Issue
issue_iid
is project-scoped; do not confuse with global issue ID
Pipeline IDs are project-scoped integers
User IDs are global integers across the GitLab instance
Rate Limits
GitLab has per-user rate limits (typically 300-2000 requests/minute depending on plan)
Large pipeline/issue histories should use date and status filters to reduce result sets
Paginate responsibly with moderate
per_page
values
Parameter Quirks
labels
field replaces ALL labels; use
add_labels
/
remove_labels
for incremental changes
assignee_ids: [0]
unassigns all; empty array does nothing
scope
defaults vary:
"created_by_me"
for MRs,
"all"
for issues
author_id
and
author_username
are mutually exclusive in MR filters
Date parameters use ISO 8601 format:
"2024-01-15T10:30:00Z"
Plan Restrictions
Some features require Premium/Ultimate:
epic_id
,
weight
,
iteration_id
,
approved_by_ids
, member
state
filter
Admin-only features: user management filters,
updated_at
override, custom attributes
The
mr_approved_filter
feature flag is disabled by default
Quick Reference
Task
Tool Slug
Key Params
List projects
GITLAB_GET_PROJECTS
search
,
membership
,
visibility
Get project details
GITLAB_GET_PROJECT
id
User's projects
GITLAB_LIST_USER_PROJECTS
id
,
search
,
owned
Create project
GITLAB_CREATE_PROJECT
name
,
path
,
visibility
List issues
GITLAB_LIST_PROJECT_ISSUES
id
,
state
,
labels
,
search
Create issue
GITLAB_CREATE_PROJECT_ISSUE
id
,
title
,
description
,
labels
Update issue
GITLAB_UPDATE_PROJECT_ISSUE
id
,
issue_iid
,
state_event
List merge requests
GITLAB_GET_PROJECT_MERGE_REQUESTS
id
,
state
,
scope
,
labels
List branches
GITLAB_GET_REPOSITORY_BRANCHES
project_id
,
search
Get branch
GITLAB_GET_REPOSITORY_BRANCH
project_id
,
branch_name
Create branch
GITLAB_CREATE_REPOSITORY_BRANCH
project_id
,
branch_name
,
ref
List commits
GITLAB_LIST_REPOSITORY_COMMITS
project ID, branch ref
Project languages
GITLAB_GET_PROJECT_LANGUAGES
project ID
List pipelines
GITLAB_LIST_PROJECT_PIPELINES
id
,
status
,
ref
Get pipeline
GITLAB_GET_SINGLE_PIPELINE
project_id
,
pipeline_id
List pipeline jobs
GITLAB_LIST_PIPELINE_JOBS
id
,
pipeline_id
,
scope
Search users
GITLAB_GET_USERS
search
,
username
,
active
Get user
GITLAB_GET_USER
user ID
User status
GITLAB_GET_USERS_ID_STATUS
user ID
List project members
GITLAB_LIST_ALL_PROJECT_MEMBERS
id
,
query
,
state
List project users
GITLAB_LIST_PROJECT_USERS
id
,
search
Powered by
Composio