Gitlab Automation

1---
2name: gitlab-automation
3description: "Automate GitLab project management, issues, merge requests, pipelines, branches, and user operations via Rube MCP (Composio). Always search tools first for current schemas."
4requires:
5  mcp: [rube]
6---
7 
8# GitLab Automation via Rube MCP
9 
10Automate GitLab operations including project management, issue tracking, merge request workflows, CI/CD pipeline monitoring, branch management, and user administration through Composio's GitLab toolkit.
11 
12## Prerequisites
13 
14- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
15- Active GitLab connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `gitlab`
16- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas
17 
18## Setup
19 
20**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.
21 
22 
231. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
242. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `gitlab`
253. If connection is not ACTIVE, follow the returned auth link to complete GitLab OAuth
264. Confirm connection status shows ACTIVE before running any workflows
27 
28## Core Workflows
29 
30### 1. Manage Issues
31 
32**When to use**: User wants to create, update, list, or search issues in a GitLab project
33 
34**Tool sequence**:
351. `GITLAB_GET_PROJECTS` - Find the target project and get its ID [Prerequisite]
362. `GITLAB_LIST_PROJECT_ISSUES` - List and filter issues for a project [Required]
373. `GITLAB_CREATE_PROJECT_ISSUE` - Create a new issue [Required for create]
384. `GITLAB_UPDATE_PROJECT_ISSUE` - Update an existing issue (title, labels, state, assignees) [Required for update]
395. `GITLAB_LIST_PROJECT_USERS` - Find user IDs for assignment [Optional]
40 
41**Key parameters**:
42- `id`: Project ID (integer) or URL-encoded path (e.g., `"my-group/my-project"`)
43- `title`: Issue title (required for creation)
44- `description`: Issue body text (max 1,048,576 characters)
45- `labels`: Comma-separated label names (e.g., `"bug,critical"`)
46- `add_labels` / `remove_labels`: Add or remove labels without replacing all
47- `state`: Filter by `"all"`, `"opened"`, or `"closed"`
48- `state_event`: `"close"` or `"reopen"` to change issue state
49- `assignee_ids`: Array of user IDs; use `[0]` to unassign all
50- `issue_iid`: Internal issue ID within the project (required for updates)
51- `milestone`: Filter by milestone title
52- `search`: Search in title and description
53- `scope`: `"created_by_me"`, `"assigned_to_me"`, or `"all"`
54- `page` / `per_page`: Pagination (default per_page: 20)
55 
56**Pitfalls**:
57- `id` accepts either integer project ID or URL-encoded path; wrong IDs yield 4xx errors
58- `issue_iid` is the project-internal ID (shown as #42), different from the global issue ID
59- Labels in `labels` field replace ALL existing labels; use `add_labels`/`remove_labels` for incremental changes
60- Setting `assignee_ids` to empty array does NOT unassign; use `[0]` instead
61- `updated_at` field requires administrator or project/group owner rights
62 
63### 2. Manage Merge Requests
64 
65**When to use**: User wants to list, filter, or review merge requests in a project
66 
67**Tool sequence**:
681. `GITLAB_GET_PROJECT` - Get project details and verify access [Prerequisite]
692. `GITLAB_GET_PROJECT_MERGE_REQUESTS` - List and filter merge requests [Required]
703. `GITLAB_GET_REPOSITORY_BRANCHES` - Verify source/target branches [Optional]
714. `GITLAB_LIST_ALL_PROJECT_MEMBERS` - Find reviewers/assignees [Optional]
72 
73**Key parameters**:
74- `id`: Project ID or URL-encoded path
75- `state`: `"opened"`, `"closed"`, `"locked"`, `"merged"`, or `"all"`
76- `scope`: `"created_by_me"` (default), `"assigned_to_me"`, or `"all"`
77- `source_branch` / `target_branch`: Filter by branch names
78- `author_id` / `author_username`: Filter by MR author
79- `assignee_id`: Filter by assignee (use `None` for unassigned, `Any` for assigned)
80- `reviewer_id` / `reviewer_username`: Filter by reviewer
81- `labels`: Comma-separated label filter
82- `search`: Search in title and description
83- `wip`: `"yes"` for draft MRs, `"no"` for non-draft
84- `order_by`: `"created_at"` (default), `"title"`, `"merged_at"`, `"updated_at"`
85- `view`: `"simple"` for minimal fields
86- `iids[]`: Filter by specific MR internal IDs
87 
88**Pitfalls**:
89- Default `scope` is `"created_by_me"` which limits results; use `"all"` for complete listings
90- `author_id` and `author_username` are mutually exclusive
91- `reviewer_id` and `reviewer_username` are mutually exclusive
92- `approved` filter requires the `mr_approved_filter` feature flag (disabled by default)
93- Large MR histories can be noisy; use filters and moderate `per_page` values
94 
95### 3. Manage Projects and Repositories
96 
97**When to use**: User wants to list projects, create new projects, or manage branches
98 
99**Tool sequence**:
1001. `GITLAB_GET_PROJECTS` - List all accessible projects with filters [Required]
1012. `GITLAB_GET_PROJECT` - Get detailed info for a specific project [Optional]
1023. `GITLAB_LIST_USER_PROJECTS` - List projects owned by a specific user [Optional]
1034. `GITLAB_CREATE_PROJECT` - Create a new project [Required for create]
1045. `GITLAB_GET_REPOSITORY_BRANCHES` - List branches in a project [Required for branch ops]
1056. `GITLAB_CREATE_REPOSITORY_BRANCH` - Create a new branch [Optional]
1067. `GITLAB_GET_REPOSITORY_BRANCH` - Get details of a specific branch [Optional]
1078. `GITLAB_LIST_REPOSITORY_COMMITS` - View commit history [Optional]
1089. `GITLAB_GET_PROJECT_LANGUAGES` - Get language breakdown [Optional]
109 
110**Key parameters**:
111- `name` / `path`: Project name and URL-friendly path (both required for creation)
112- `visibility`: `"private"`, `"internal"`, or `"public"`
113- `namespace_id`: Group or user ID for project placement
114- `search`: Case-insensitive substring search for projects
115- `membership`: `true` to limit to projects user is a member of
116- `owned`: `true` to limit to user-owned projects
117- `project_id`: Project ID for branch operations
118- `branch_name`: Name for new branch
119- `ref`: Source branch or commit SHA for new branch creation
120- `order_by`: `"id"`, `"name"`, `"path"`, `"created_at"`, `"updated_at"`, `"star_count"`, `"last_activity_at"`
121 
122**Pitfalls**:
123- `GITLAB_GET_PROJECTS` pagination is required for complete coverage; stopping at first page misses projects
124- Some responses place items under `data.details`; parse the actual returned list structure
125- Most follow-up calls depend on correct `project_id`; verify with `GITLAB_GET_PROJECT` first
126- Invalid `branch_name`/`ref`/`sha` causes client errors; verify branch existence via `GITLAB_GET_REPOSITORY_BRANCHES` first
127- Both `name` and `path` are required for `GITLAB_CREATE_PROJECT`
128 
129### 4. Monitor CI/CD Pipelines
130 
131**When to use**: User wants to check pipeline status, list jobs, or monitor CI/CD runs
132 
133**Tool sequence**:
1341. `GITLAB_GET_PROJECT` - Verify project access [Prerequisite]
1352. `GITLAB_LIST_PROJECT_PIPELINES` - List pipelines with filters [Required]
1363. `GITLAB_GET_SINGLE_PIPELINE` - Get detailed info for a specific pipeline [Optional]
1374. `GITLAB_LIST_PIPELINE_JOBS` - List jobs within a pipeline [Optional]
138 
139**Key parameters**:
140- `id`: Project ID or URL-encoded path
141- `status`: Filter by `"created"`, `"waiting_for_resource"`, `"preparing"`, `"pending"`, `"running"`, `"success"`, `"failed"`, `"canceled"`, `"skipped"`, `"manual"`, `"scheduled"`
142- `scope`: `"running"`, `"pending"`, `"finished"`, `"branches"`, `"tags"`
143- `ref`: Branch or tag name
144- `sha`: Specific commit SHA
145- `source`: Pipeline source (use `"parent_pipeline"` for child pipelines)
146- `order_by`: `"id"` (default), `"status"`, `"ref"`, `"updated_at"`, `"user_id"`
147- `created_after` / `created_before`: ISO 8601 date filters
148- `pipeline_id`: Specific pipeline ID for job listing
149- `include_retried`: `true` to include retried jobs (default `false`)
150 
151**Pitfalls**:
152- Large pipeline histories can be noisy; use `status`, `ref`, and date filters to narrow results
153- Use moderate `per_page` values to keep output manageable
154- Pipeline job `scope` accepts single status string or array of statuses
155- `yaml_errors: true` returns only pipelines with invalid configurations
156 
157### 5. Manage Users and Members
158 
159**When to use**: User wants to find users, list project members, or check user status
160 
161**Tool sequence**:
1621. `GITLAB_GET_USERS` - Search and list GitLab users [Required]
1632. `GITLAB_GET_USER` - Get details for a specific user by ID [Optional]
1643. `GITLAB_GET_USERS_ID_STATUS` - Get user status message and availability [Optional]
1654. `GITLAB_LIST_ALL_PROJECT_MEMBERS` - List all project members (direct + inherited) [Required for member listing]
1665. `GITLAB_LIST_PROJECT_USERS` - List project users with search filter [Optional]
167 
168**Key parameters**:
169- `search`: Search by name, username, or public email
170- `username`: Get specific user by username
171- `active` / `blocked`: Filter by user state
172- `id`: Project ID for member listing
173- `query`: Filter members by name, email, or username
174- `state`: Filter members by `"awaiting"` or `"active"` (Premium/Ultimate)
175- `user_ids`: Filter by specific user IDs
176 
177**Pitfalls**:
178- Many user filters (admins, auditors, extern_uid, two_factor) are admin-only
179- `GITLAB_LIST_ALL_PROJECT_MEMBERS` includes direct, inherited, and invited members
180- User search is case-insensitive but may not match partial email domains
181- Premium/Ultimate features (state filter, seat info) are not available on free plans
182 
183## Common Patterns
184 
185### ID Resolution
186GitLab uses two identifier formats for projects:
187- **Numeric ID**: Integer project ID (e.g., `123`)
188- **URL-encoded path**: Namespace/project format (e.g., `"my-group%2Fmy-project"` or `"my-group/my-project"`)
189- **Issue IID vs ID**: `issue_iid` is the project-internal number (#42); the global `id` is different
190- **User ID**: Numeric; resolve via `GITLAB_GET_USERS` with `search` or `username`
191 
192### Pagination
193GitLab uses offset-based pagination:
194- Set `page` (starting at 1) and `per_page` (1-100, default 20)
195- Continue incrementing `page` until response returns fewer items than `per_page` or is empty
196- Total count may be available in response headers (`X-Total`, `X-Total-Pages`)
197- Always paginate to completion for accurate results
198 
199### URL-Encoded Paths
200When using project paths as identifiers:
201- Forward slashes must be URL-encoded: `my-group/my-project` becomes `my-group%2Fmy-project`
202- Some tools accept unencoded paths; check schema for each tool
203- Prefer numeric IDs when available for reliability
204 
205## Known Pitfalls
206 
207### ID Formats
208- Project `id` field accepts both integer and string (URL-encoded path)
209- Issue `issue_iid` is project-scoped; do not confuse with global issue ID
210- Pipeline IDs are project-scoped integers
211- User IDs are global integers across the GitLab instance
212 
213### Rate Limits
214- GitLab has per-user rate limits (typically 300-2000 requests/minute depending on plan)
215- Large pipeline/issue histories should use date and status filters to reduce result sets
216- Paginate responsibly with moderate `per_page` values
217 
218### Parameter Quirks
219- `labels` field replaces ALL labels; use `add_labels`/`remove_labels` for incremental changes
220- `assignee_ids: [0]` unassigns all; empty array does nothing
221- `scope` defaults vary: `"created_by_me"` for MRs, `"all"` for issues
222- `author_id` and `author_username` are mutually exclusive in MR filters
223- Date parameters use ISO 8601 format: `"2024-01-15T10:30:00Z"`
224 
225### Plan Restrictions
226- Some features require Premium/Ultimate: `epic_id`, `weight`, `iteration_id`, `approved_by_ids`, member `state` filter
227- Admin-only features: user management filters, `updated_at` override, custom attributes
228- The `mr_approved_filter` feature flag is disabled by default
229 
230## Quick Reference
231 
232| Task | Tool Slug | Key Params |
233|------|-----------|------------|
234| List projects | `GITLAB_GET_PROJECTS` | `search`, `membership`, `visibility` |
235| Get project details | `GITLAB_GET_PROJECT` | `id` |
236| User's projects | `GITLAB_LIST_USER_PROJECTS` | `id`, `search`, `owned` |
237| Create project | `GITLAB_CREATE_PROJECT` | `name`, `path`, `visibility` |
238| List issues | `GITLAB_LIST_PROJECT_ISSUES` | `id`, `state`, `labels`, `search` |
239| Create issue | `GITLAB_CREATE_PROJECT_ISSUE` | `id`, `title`, `description`, `labels` |
240| Update issue | `GITLAB_UPDATE_PROJECT_ISSUE` | `id`, `issue_iid`, `state_event` |
241| List merge requests | `GITLAB_GET_PROJECT_MERGE_REQUESTS` | `id`, `state`, `scope`, `labels` |
242| List branches | `GITLAB_GET_REPOSITORY_BRANCHES` | `project_id`, `search` |
243| Get branch | `GITLAB_GET_REPOSITORY_BRANCH` | `project_id`, `branch_name` |
244| Create branch | `GITLAB_CREATE_REPOSITORY_BRANCH` | `project_id`, `branch_name`, `ref` |
245| List commits | `GITLAB_LIST_REPOSITORY_COMMITS` | project ID, branch ref |
246| Project languages | `GITLAB_GET_PROJECT_LANGUAGES` | project ID |
247| List pipelines | `GITLAB_LIST_PROJECT_PIPELINES` | `id`, `status`, `ref` |
248| Get pipeline | `GITLAB_GET_SINGLE_PIPELINE` | `project_id`, `pipeline_id` |
249| List pipeline jobs | `GITLAB_LIST_PIPELINE_JOBS` | `id`, `pipeline_id`, `scope` |
250| Search users | `GITLAB_GET_USERS` | `search`, `username`, `active` |
251| Get user | `GITLAB_GET_USER` | user ID |
252| User status | `GITLAB_GET_USERS_ID_STATUS` | user ID |
253| List project members | `GITLAB_LIST_ALL_PROJECT_MEMBERS` | `id`, `query`, `state` |
254| List project users | `GITLAB_LIST_PROJECT_USERS` | `id`, `search` |
255