circleci-automation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

CircleCI Automation via Rube MCP

通过Rube MCP实现CircleCI自动化

Automate CircleCI CI/CD operations through Composio's CircleCI toolkit via Rube MCP.

通过Composio的CircleCI工具集，借助Rube MCP自动化CircleCI CI/CD操作。

Prerequisites

前提条件

Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
Active CircleCI connection via
```
RUBE_MANAGE_CONNECTIONS
```
with toolkit
```
circleci
```
Always call
```
RUBE_SEARCH_TOOLS
```
first to get current tool schemas

必须已连接Rube MCP（需提供RUBE_SEARCH_TOOLS）
通过
```
RUBE_MANAGE_CONNECTIONS
```
并使用工具集
```
circleci
```
建立有效的CircleCI连接
请始终先调用
```
RUBE_SEARCH_TOOLS
```
以获取最新的工具架构

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
```
circleci
```
If connection is not ACTIVE, follow the returned auth link to complete CircleCI authentication
Confirm connection status shows ACTIVE before running any workflows

获取Rube MCP：在客户端配置中添加

https://rube.app/mcp

作为MCP服务器。无需API密钥 — 只需添加端点即可使用。

通过确认
```
RUBE_SEARCH_TOOLS
```
能正常响应，验证Rube MCP是否可用
调用
```
RUBE_MANAGE_CONNECTIONS
```
并指定工具集
```
circleci
```
如果连接状态未处于ACTIVE，请按照返回的认证链接完成CircleCI认证
在运行任何工作流之前，确认连接状态显示为ACTIVE

Core Workflows

核心工作流

1. Trigger a Pipeline

1. 触发流水线

When to use: User wants to start a new CI/CD pipeline run

Tool sequence:

```
CIRCLECI_TRIGGER_PIPELINE
```
- Trigger a new pipeline on a project [Required]
```
CIRCLECI_LIST_WORKFLOWS_BY_PIPELINE_ID
```
- Monitor resulting workflows [Optional]

Key parameters:

```
project_slug
```
: Project identifier in format
```
gh/org/repo
```
or
```
bb/org/repo
```
```
branch
```
: Git branch to run the pipeline on
```
tag
```
: Git tag to run the pipeline on (mutually exclusive with branch)
```
parameters
```
: Pipeline parameter key-value pairs

Pitfalls:

project_slug

format is

{vcs}/{org}/{repo}

(e.g.,

gh/myorg/myrepo

)

```
branch
```
and
```
tag
```
are mutually exclusive; providing both causes an error
Pipeline parameters must match those defined in
```
.circleci/config.yml
```
Triggering returns a pipeline ID; workflows start asynchronously

适用场景：用户想要启动新的CI/CD流水线运行

工具序列:

```
CIRCLECI_TRIGGER_PIPELINE
```
- 触发项目的新流水线 [必填]
```
CIRCLECI_LIST_WORKFLOWS_BY_PIPELINE_ID
```
- 监控生成的工作流 [可选]

关键参数:

```
project_slug
```
: 项目标识符，格式为
```
gh/org/repo
```
或
```
bb/org/repo
```
```
branch
```
: 运行流水线的Git分支
```
tag
```
: 运行流水线的Git标签（与branch互斥）
```
parameters
```
: 流水线参数的键值对

注意事项:

project_slug

格式为

{vcs}/{org}/{repo}

（例如：

gh/myorg/myrepo

）

```
branch
```
和
```
tag
```
互斥；同时提供两者会导致错误
流水线参数必须与
```
.circleci/config.yml
```
中定义的参数匹配
触发操作会返回流水线ID；工作流为异步启动

2. Monitor Pipelines and Workflows

2. 监控流水线与工作流

When to use: User wants to check the status of pipelines or workflows

Tool sequence:

```
CIRCLECI_LIST_PIPELINES_FOR_PROJECT
```
- List recent pipelines for a project [Required]
```
CIRCLECI_LIST_WORKFLOWS_BY_PIPELINE_ID
```
- List workflows within a pipeline [Required]
```
CIRCLECI_GET_PIPELINE_CONFIG
```
- View the pipeline configuration used [Optional]

Key parameters:

```
project_slug
```
: Project identifier in
```
{vcs}/{org}/{repo}
```
format
```
pipeline_id
```
: UUID of a specific pipeline
```
branch
```
: Filter pipelines by branch name
```
page_token
```
: Pagination cursor for next page of results

Pitfalls:

Pipeline IDs are UUIDs, not numeric IDs
Workflows inherit the pipeline ID; a single pipeline can have multiple workflows
Workflow states include: success, running, not_run, failed, error, failing, on_hold, canceled, unauthorized
```
page_token
```
is returned in responses for pagination; continue until absent

适用场景：用户想要检查流水线或工作流的状态

工具序列:

```
CIRCLECI_LIST_PIPELINES_FOR_PROJECT
```
- 列出项目的近期流水线 [必填]
```
CIRCLECI_LIST_WORKFLOWS_BY_PIPELINE_ID
```
- 列出流水线内的工作流 [必填]
```
CIRCLECI_GET_PIPELINE_CONFIG
```
- 查看所使用的流水线配置 [可选]

关键参数:

```
project_slug
```
: 项目标识符，格式为
```
{vcs}/{org}/{repo}
```
```
pipeline_id
```
: 特定流水线的UUID
```
branch
```
: 按分支名称过滤流水线
```
page_token
```
: 用于获取下一页结果的分页游标

注意事项:

流水线ID为UUID，而非数字ID
工作流继承流水线ID；单个流水线可包含多个工作流
工作流状态包括：success、running、not_run、failed、error、failing、on_hold、canceled、unauthorized
```
page_token
```
会在响应中返回以支持分页；直到该字段不存在时停止请求

3. Inspect Job Details

3. 查看任务详情

When to use: User wants to drill into a specific job's execution details

Tool sequence:

```
CIRCLECI_LIST_WORKFLOWS_BY_PIPELINE_ID
```
- Find workflow containing the job [Prerequisite]
```
CIRCLECI_GET_JOB_DETAILS
```
- Get detailed job information [Required]

Key parameters:

```
project_slug
```
: Project identifier
```
job_number
```
: Numeric job number (not UUID)

Pitfalls:

Job numbers are integers, not UUIDs (unlike pipeline and workflow IDs)
Job details include executor type, parallelism, start/stop times, and status
Job statuses: success, running, not_run, failed, retried, timedout, infrastructure_fail, canceled

适用场景：用户想要深入了解特定任务的执行细节

工具序列:

```
CIRCLECI_LIST_WORKFLOWS_BY_PIPELINE_ID
```
- 找到包含该任务的工作流 [前提步骤]
```
CIRCLECI_GET_JOB_DETAILS
```
- 获取任务的详细信息 [必填]

关键参数:

```
project_slug
```
: 项目标识符
```
job_number
```
: 数字形式的任务编号（非UUID）

注意事项:

任务编号为整数，而非UUID（与流水线和工作流ID不同）
任务详情包括执行器类型、并行度、开始/结束时间和状态
任务状态：success、running、not_run、failed、retried、timedout、infrastructure_fail、canceled

4. Retrieve Build Artifacts

4. 检索构建产物

When to use: User wants to download or list artifacts produced by a job

Tool sequence:

```
CIRCLECI_GET_JOB_DETAILS
```
- Confirm job completed successfully [Prerequisite]
```
CIRCLECI_GET_JOB_ARTIFACTS
```
- List all artifacts from the job [Required]

Key parameters:

```
project_slug
```
: Project identifier
```
job_number
```
: Numeric job number

Pitfalls:

Artifacts are only available after job completion
Each artifact has a
```
path
```
and
```
url
```
for download
Artifact URLs may require authentication headers to download
Large artifacts may have download size limits

适用场景：用户想要下载或列出任务生成的构建产物

工具序列:

```
CIRCLECI_GET_JOB_DETAILS
```
- 确认任务已成功完成 [前提步骤]
```
CIRCLECI_GET_JOB_ARTIFACTS
```
- 列出该任务的所有构建产物 [必填]

关键参数:

```
project_slug
```
: 项目标识符
```
job_number
```
: 数字形式的任务编号

注意事项:

构建产物仅在任务完成后可用
每个构建产物都包含
```
path
```
和用于下载的
```
url
```
构建产物的URL可能需要认证头才能下载
大型构建产物可能有下载大小限制

5. Review Test Results

5. 查看测试结果

When to use: User wants to check test outcomes for a specific job

Tool sequence:

```
CIRCLECI_GET_JOB_DETAILS
```
- Verify job ran tests [Prerequisite]
```
CIRCLECI_GET_TEST_METADATA
```
- Retrieve test results and metadata [Required]

Key parameters:

```
project_slug
```
: Project identifier
```
job_number
```
: Numeric job number

Pitfalls:

Test metadata requires the job to have uploaded test results (JUnit XML format)
If no test results were uploaded, the response will be empty
Test metadata includes classname, name, result, message, and run_time fields
Failed tests include failure messages in the
```
message
```
field

适用场景：用户想要检查特定任务的测试结果

工具序列:

```
CIRCLECI_GET_JOB_DETAILS
```
- 验证任务已运行测试 [前提步骤]
```
CIRCLECI_GET_TEST_METADATA
```
- 检索测试结果和元数据 [必填]

关键参数:

```
project_slug
```
: 项目标识符
```
job_number
```
: 数字形式的任务编号

注意事项:

测试元数据要求任务已上传测试结果（JUnit XML格式）
如果未上传测试结果，响应将为空
测试元数据包括classname、name、result、message和run_time字段
失败的测试会在
```
message
```
字段中包含失败信息

Common Patterns

常见模式

Project Slug Format

项目标识符格式

Format: {vcs_type}/{org_name}/{repo_name}
- GitHub:    gh/myorg/myrepo
- Bitbucket: bb/myorg/myrepo

格式: {vcs_type}/{org_name}/{repo_name}
- GitHub:    gh/myorg/myrepo
- Bitbucket: bb/myorg/myrepo

Pipeline -> Workflow -> Job Hierarchy

流水线 -> 工作流 -> 任务的层级关系

1. Call CIRCLECI_LIST_PIPELINES_FOR_PROJECT to get pipeline IDs
2. Call CIRCLECI_LIST_WORKFLOWS_BY_PIPELINE_ID with pipeline_id
3. Extract job numbers from workflow details
4. Call CIRCLECI_GET_JOB_DETAILS with job_number

1. 调用CIRCLECI_LIST_PIPELINES_FOR_PROJECT获取流水线ID
2. 使用pipeline_id调用CIRCLECI_LIST_WORKFLOWS_BY_PIPELINE_ID
3. 从工作流详情中提取任务编号
4. 使用job_number调用CIRCLECI_GET_JOB_DETAILS

Pagination

分页处理

Check response for
```
next_page_token
```
field
Pass token as
```
page_token
```
in next request
Continue until
```
next_page_token
```
is absent or null

检查响应中的
```
next_page_token
```
字段
在下次请求中将该令牌作为
```
page_token
```
传入
直到
```
next_page_token
```
不存在或为null时停止

Known Pitfalls

已知注意事项

ID Formats:

Pipeline IDs: UUIDs (e.g.,
```
5034460f-c7c4-4c43-9457-de07e2029e7b
```
)
Workflow IDs: UUIDs
Job numbers: Integers (e.g.,
```
123
```
)
Do NOT mix up UUIDs and integers between different endpoints

Project Slugs:

Must include VCS prefix:
```
gh/
```
for GitHub,
```
bb/
```
for Bitbucket
Organization and repo names are case-sensitive
Incorrect slug format causes 404 errors

Rate Limits:

CircleCI API has per-endpoint rate limits
Implement exponential backoff on 429 responses
Avoid rapid polling; use reasonable intervals (5-10 seconds)

ID格式:

流水线ID: UUID（例如：
```
5034460f-c7c4-4c43-9457-de07e2029e7b
```
）
工作流ID: UUID
任务编号: 整数（例如：
```
123
```
）
请勿在不同端点之间混用UUID和整数

项目标识符:

必须包含版本控制系统前缀：GitHub使用
```
gh/
```
，Bitbucket使用
```
bb/
```
组织和仓库名称区分大小写
错误的标识符格式会导致404错误

速率限制:

CircleCI API对每个端点都有速率限制
在收到429响应时实现指数退避策略
避免频繁轮询；使用合理的间隔（5-10秒）

Quick Reference

快速参考

Task	Tool Slug	Key Params
Trigger pipeline	CIRCLECI_TRIGGER_PIPELINE	project_slug, branch, parameters
List pipelines	CIRCLECI_LIST_PIPELINES_FOR_PROJECT	project_slug, branch
List workflows	CIRCLECI_LIST_WORKFLOWS_BY_PIPELINE_ID	pipeline_id
Get pipeline config	CIRCLECI_GET_PIPELINE_CONFIG	pipeline_id
Get job details	CIRCLECI_GET_JOB_DETAILS	project_slug, job_number
Get job artifacts	CIRCLECI_GET_JOB_ARTIFACTS	project_slug, job_number
Get test metadata	CIRCLECI_GET_TEST_METADATA	project_slug, job_number

任务	工具标识	关键参数
触发流水线	CIRCLECI_TRIGGER_PIPELINE	project_slug, branch, parameters
列出流水线	CIRCLECI_LIST_PIPELINES_FOR_PROJECT	project_slug, branch
列出工作流	CIRCLECI_LIST_WORKFLOWS_BY_PIPELINE_ID	pipeline_id
获取流水线配置	CIRCLECI_GET_PIPELINE_CONFIG	pipeline_id
获取任务详情	CIRCLECI_GET_JOB_DETAILS	project_slug, job_number
获取任务构建产物	CIRCLECI_GET_JOB_ARTIFACTS	project_slug, job_number
获取测试元数据	CIRCLECI_GET_TEST_METADATA	project_slug, job_number