gitlab-automation

通过 Rube MCP 自动化 GitLab

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

前提条件

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

设置

获取 Rube MCP：在客户端配置中添加 https://rube.app/mcp 作为 MCP 服务。仅有此端点并不能授权访问 GitLab。请对 MCP 客户端进行身份验证，并通过返回的受支持授权流程连接目标 GitLab 账户。

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

操作前请确认 GitLab 实例、账户和项目。列出内容并不代表已获准创建议题、项目或分支、修改用户或执行合并操作；请使用用户批准的目标和操作。保留保护设置，预览破坏性更改，并在重试前核实结果不确定的写入操作。切勿将令牌或私有仓库内容发送给无关服务。

核心工作流

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 功能标志默认处于禁用状态

快速参考

任务	工具 Slug	关键参数
列出项目	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

何时使用

本技能适用于执行概述中描述的工作流或操作。

示例

用户请求：

通过 Rube MCP（Composio）自动化 GitLab 项目管理、issue、合并请求、pipeline、分支和用户操作。

限制

• 仅当任务明确符合上述范围时才使用本技能。
• 不要将输出视为特定环境验证、测试或专家评审的替代品。
• 如果缺少必需的输入、权限、安全边界或成功标准，请停止并请求澄清。