gitlab-automation

通过 Rube MCP 自动化 GitLab

通过 Composio 的 GitLab 工具包自动执行 GitLab 操作，包括项目管理、议题跟踪、合并请求工作流、CI/CD 流水线监控、分支管理和用户管理。

工具包文档：composio.dev/toolkits/gitlab

前提条件

• 必须连接 Rube MCP（可使用 RUBE_SEARCH_TOOLS）
• 通过 RUBE_MANAGE_CONNECTIONS 建立有效的 GitLab 连接，并指定工具包 gitlab
• 始终先调用 RUBE_SEARCH_TOOLS，以获取最新的工具架构

设置

获取 Rube MCP：在客户端配置中将 https://rube.app/mcp 添加为 MCP 服务。无需 API 密钥——只需添加端点即可使用。

1. 确认 RUBE_SEARCH_TOOLS 能够响应，以验证 Rube MCP 是否可用
2. 调用 RUBE_MANAGE_CONNECTIONS，并指定工具包 gitlab
3. 如果连接状态不是 ACTIVE，请通过返回的授权链接完成 GitLab OAuth
4. 运行任何工作流前，确认连接状态显示为 ACTIVE

核心工作流

1. 管理议题

适用场景：用户希望在 GitLab 项目中创建、更新、列出或搜索议题

工具调用顺序：

1. GITLAB_GET_PROJECTS - 查找目标项目并获取其 ID [前置条件]
2. GITLAB_LIST_PROJECT_ISSUES - 列出项目议题并筛选 [必需]
3. GITLAB_CREATE_PROJECT_ISSUE - 创建新议题 [创建时必需]
4. GITLAB_UPDATE_PROJECT_ISSUE - 更新现有议题（标题、标签、状态、指派对象）[更新时必需]
5. GITLAB_LIST_PROJECT_USERS - 查找要指派的用户 ID [可选]

关键参数：

• id：项目 ID（整数）或 URL 编码的路径（例如 "my-group/my-project"）
• title：议题标题（创建时必填）
• description：议题正文文本（最多 1,048,576 个字符）
• labels：以逗号分隔的标签名称（例如 "bug,critical"）
• add_labels / remove_labels：添加或移除标签，而不替换所有标签
• state：按 "all"、"opened" 或 "closed" 筛选
• state_event：使用 "close" 或 "reopen" 更改议题状态
• assignee_ids：用户 ID 数组；使用 [0] 取消指派所有用户
• issue_iid：项目内的议题 ID（更新时必填）
• milestone：按里程碑标题筛选
• search：在标题和描述中搜索
• scope："created_by_me"、"assigned_to_me" 或 "all"
• page / per_page：分页（默认 per_page：20）

注意事项：

• id 接受整数项目 ID 或 URL 编码的路径；错误的 ID 会导致 4xx 错误
• issue_iid 是项目内部 ID（显示为 #42），不同于全局议题 ID
• labels 字段中的标签会替换所有现有标签；如需逐步修改，请使用 add_labels / remove_labels
• 将 assignee_ids 设为空数组不会取消指派；请改用 [0]
• updated_at 字段需要管理员或项目/群组所有者权限

2. 管理合并请求

使用场景：用户想要列出、筛选或审查项目中的合并请求

工具调用顺序：

1. GITLAB_GET_PROJECT - 获取项目信息并验证访问权限 [前置条件]
2. GITLAB_GET_PROJECT_MERGE_REQUESTS - 列出并筛选合并请求 [必需]
3. GITLAB_GET_REPOSITORY_BRANCHES - 验证源分支／目标分支 [可选]
4. GITLAB_LIST_ALL_PROJECT_MEMBERS - 查找审查者／指派对象 [可选]

关键参数：

• id：项目 ID 或 URL 编码的路径
• state："opened"、"closed"、"locked"、"merged" 或 "all"
• scope："created_by_me"（默认）、"assigned_to_me" 或 "all"
• source_branch / target_branch：按分支名称筛选
• author_id / author_username：按 MR 作者筛选
• assignee_id：按指派对象筛选（未指派时使用 None，已指派时使用 Any）
• reviewer_id / reviewer_username：按审查者筛选
• labels：逗号分隔的标签筛选条件
• search：搜索标题和描述
• wip：草稿 MR 使用 "yes"，非草稿使用 "no"
• order_by："created_at"（默认）、"title"、"merged_at"、"updated_at"
• view：使用 "simple" 获取最少字段
• iids[]：按特定 MR 内部 ID 筛选

注意事项：

• 默认 scope 为 "created_by_me"，会限制结果；如需完整列表，请使用 "all"
• author_id 和 author_username 不能同时使用
• reviewer_id 和 reviewer_username 不能同时使用
• approved 筛选需要 mr_approved_filter 功能标志（默认禁用）
• MR 历史记录过多时可能包含大量无关内容；请使用筛选条件和适中的 per_page 值

3. 管理项目和仓库

使用场景：用户想要列出项目、创建新项目或管理分支

工具调用顺序：

1. GITLAB_GET_PROJECTS - 按筛选条件列出所有可访问的项目 [必需]
2. GITLAB_GET_PROJECT - 获取特定项目的详细信息 [可选]
3. GITLAB_LIST_USER_PROJECTS - 列出特定用户拥有的项目 [可选]
4. GITLAB_CREATE_PROJECT - 创建新项目 [创建时必需]
5. GITLAB_GET_REPOSITORY_BRANCHES - 列出项目中的分支 [分支操作时必需]
6. GITLAB_CREATE_REPOSITORY_BRANCH - 创建新分支 [可选]
7. GITLAB_GET_REPOSITORY_BRANCH - 获取特定分支的详细信息 [可选]
8. GITLAB_LIST_REPOSITORY_COMMITS - 查看提交历史 [可选]
9. GITLAB_GET_PROJECT_LANGUAGES - 获取语言分布情况 [可选]

关键参数：

• name / path：项目名称和适合 URL 的路径（创建项目时均必需）
• visibility："private"、"internal" 或 "public"
• namespace_id：用于指定项目位置的组 ID 或用户 ID
• search：不区分大小写的项目子字符串搜索
• membership：设为 true 可仅列出用户所属的项目
• owned：设为 true 可仅列出用户拥有的项目
• project_id：分支操作所用的项目 ID
• branch_name：新分支的名称
• ref：创建新分支所用的源分支或提交 SHA
• order_by："id"、"name"、"path"、"created_at"、"updated_at"、"star_count"、"last_activity_at"

注意事项：

• GITLAB_GET_PROJECTS 必须进行分页才能完整获取结果；只读取第一页会遗漏项目
• 某些响应会将项目放在 data.details 下；请解析实际返回的列表结构
• 大多数后续调用都依赖正确的 project_id；请先通过 GITLAB_GET_PROJECT 验证
• 无效的 branch_name／ref／sha 会导致客户端错误；请先通过 GITLAB_GET_REPOSITORY_BRANCHES 验证分支是否存在
• GITLAB_CREATE_PROJECT 必须同时提供 name 和 path

4. 监控 CI/CD 流水线

适用场景：用户想检查流水线状态、列出作业或监控 CI/CD 运行情况

工具调用顺序：

1. GITLAB_GET_PROJECT - 验证项目访问权限 [前置条件]
2. GITLAB_LIST_PROJECT_PIPELINES - 使用筛选条件列出流水线 [必需]
3. GITLAB_GET_SINGLE_PIPELINE - 获取特定流水线的详细信息 [可选]
4. GITLAB_LIST_PIPELINE_JOBS - 列出流水线中的作业 [可选]

关键参数：

• id：项目 ID 或 URL 编码路径
• status：按 "created"、"waiting_for_resource"、"preparing"、"pending"、"running"、"success"、"failed"、"canceled"、"skipped"、"manual"、"scheduled" 筛选
• scope："running"、"pending"、"finished"、"branches"、"tags"
• ref：分支或标签名称
• sha：特定提交 SHA
• source：流水线来源（子流水线使用 "parent_pipeline"）
• order_by："id"（默认值）、"status"、"ref"、"updated_at"、"user_id"
• created_after / created_before：ISO 8601 日期筛选条件
• pipeline_id：用于列出作业的特定流水线 ID
• include_retried：设为 true 可包含重试过的作业（默认值为 false）

注意事项：

• 流水线历史记录过多时可能会产生大量无关信息；使用 status、ref 和日期筛选条件缩小结果范围
• 使用适中的 per_page 值，使输出保持易于查看
• 流水线作业的 scope 接受单个状态字符串或状态数组
• yaml_errors: true 仅返回配置无效的流水线

5. 管理用户和成员

适用场景：用户想查找用户、列出项目成员或检查用户状态

工具调用顺序：

1. GITLAB_GET_USERS - 搜索并列出 GitLab 用户 [必需]
2. GITLAB_GET_USER - 按 ID 获取特定用户的详细信息 [可选]
3. GITLAB_GET_USERS_ID_STATUS - 获取用户状态消息和可用情况 [可选]
4. GITLAB_LIST_ALL_PROJECT_MEMBERS - 列出所有项目成员（直接成员 + 继承成员）[列出成员时必需]
5. GITLAB_LIST_PROJECT_USERS - 使用搜索筛选条件列出项目用户 [可选]

关键参数：

• search：按姓名、用户名或公开邮箱搜索
• username：按用户名获取特定用户
• active / blocked：按用户状态筛选
• id：用于列出成员的项目 ID
• query：按姓名、邮箱或用户名筛选成员
• state：按 "awaiting" 或 "active" 筛选（Premium/Ultimate）
• user_ids：按特定用户 ID 筛选

注意事项：

• 许多用户筛选条件（admins、auditors、extern_uid、two_factor）仅限管理员使用
• GITLAB_LIST_ALL_PROJECT_MEMBERS 包含直接成员、继承成员和受邀成员
• 用户搜索不区分大小写，但可能无法匹配不完整的邮箱域名
• 免费计划不提供 Premium/Ultimate 功能（状态筛选、席位信息）

常见模式

ID 解析

GitLab 使用两种项目标识符格式：

• 数字 ID：整数项目 ID（例如，123）
• URL 编码路径：命名空间/项目格式（例如，"my-group%2Fmy-project" 或 "my-group/my-project"）
• 问题 IID 与 ID：issue_iid 是项目内部编号（#42）；全局 id 则不同
• 用户 ID：数字；通过 GITLAB_GET_USERS 配合 search 或 username 解析

分页

GitLab 使用基于偏移量的分页：

• 设置 page（从 1 开始）和 per_page（1-100，默认值为 20）
• 持续递增 page，直到响应返回的条目少于 per_page 或为空
• 响应标头中可能包含总数（X-Total、X-Total-Pages）
• 为确保结果准确，始终翻完所有分页

URL 编码路径

使用项目路径作为标识符时：

• 正斜杠必须进行 URL 编码：my-group/my-project 变为 my-group%2Fmy-project
• 某些工具接受未编码路径；请查看每个工具的架构
• 如有可用的数字 ID，优先使用，以提高可靠性

已知注意事项

ID 格式

• 项目 id 字段接受整数和字符串（URL 编码的路径）
• Issue 的 issue_iid 仅在项目范围内有效；不要与全局 Issue ID 混淆
• Pipeline ID 是项目范围内的整数
• 用户 ID 是 GitLab 实例范围内的全局整数

速率限制

• GitLab 有按用户设置的速率限制（通常根据计划不同，为每分钟 300-2000 个请求）
• 对于较长的 Pipeline/Issue 历史记录，应使用日期和状态过滤器来缩小结果集
• 请合理分页，并使用适中的 per_page 值

参数注意事项

• labels 字段会替换所有标签；增量修改请使用 add_labels/remove_labels
• assignee_ids: [0] 会取消分配所有人员；空数组不起作用
• scope 的默认值各不相同：MR 为 "created_by_me"，Issue 为 "all"
• MR 过滤器中的 author_id 和 author_username 不能同时使用
• 日期参数使用 ISO 8601 格式："2024-01-15T10:30:00Z"

计划限制

• 某些功能需要 Premium/Ultimate：epic_id、weight、iteration_id、approved_by_ids、成员 state 过滤器
• 仅限管理员使用的功能：用户管理过滤器、updated_at 覆盖、自定义属性
• mr_approved_filter 功能标志默认处于禁用状态

快速参考

任务	工具标识	关键参数
列出项目	GITLAB_GET_PROJECTS	search、membership、visibility
获取项目详情	GITLAB_GET_PROJECT	id
用户的项目	GITLAB_LIST_USER_PROJECTS	id、search、owned
创建项目	GITLAB_CREATE_PROJECT	name、path、visibility
列出 Issue	GITLAB_LIST_PROJECT_ISSUES	id、state、labels、search
创建 Issue	GITLAB_CREATE_PROJECT_ISSUE	id、title、description、labels
更新 Issue	GITLAB_UPDATE_PROJECT_ISSUE	id、issue_iid、state_event
列出合并请求	GITLAB_GET_PROJECT_MERGE_REQUESTS	id、state、scope、labels
列出分支	GITLAB_GET_REPOSITORY_BRANCHES	project_id、search
获取分支	GITLAB_GET_REPOSITORY_BRANCH	project_id、branch_name
创建分支	GITLAB_CREATE_REPOSITORY_BRANCH	project_id、branch_name、ref
列出提交	GITLAB_LIST_REPOSITORY_COMMITS	项目 ID、分支 ref
项目语言	GITLAB_GET_PROJECT_LANGUAGES	项目 ID
列出 Pipeline	GITLAB_LIST_PROJECT_PIPELINES	id、status、ref
获取 Pipeline	GITLAB_GET_SINGLE_PIPELINE	project_id、pipeline_id
列出 Pipeline 作业	GITLAB_LIST_PIPELINE_JOBS	id、pipeline_id、scope
搜索用户	GITLAB_GET_USERS	search、username、active
获取用户	GITLAB_GET_USER	用户 ID
用户状态	GITLAB_GET_USERS_ID_STATUS	用户 ID
列出项目成员	GITLAB_LIST_ALL_PROJECT_MEMBERS	id、query、state
列出项目用户	GITLAB_LIST_PROJECT_USERS	id、search

---

由 Composio 提供支持