# ci +builds

> **前置条件：** 先阅读 [`../../gitlink-shared/SKILL.md`](../../../gitlink-shared/SKILL.md) 了解认证、全局参数和安全规则。

列出仓库的所有 CI/CD 构建记录，支持分页查询。

## 命令

```bash
# 查看当前仓库的构建列表
gitlink-cli ci +builds

# 指定仓库查看构建
gitlink-cli ci +builds --owner myuser --repo myrepo

# 分页查询
gitlink-cli ci +builds --page 2 --limit 10

# 输出为 JSON 格式
gitlink-cli ci +builds --format json
```

## 参数

| 参数 | 必填 | 说明 |
|------|------|------|
| `--owner` | 否* | 仓库所有者（自动从 git remote 解析） |
| `--repo` | 否* | 仓库名称（自动从 git remote 解析） |
| `--page, -p` | 否 | 页码（默认 `1`） |
| `--limit, -l` | 否 | 每页条数（默认 `20`） |
| `--format` | 否 | 输出格式: `json`/`table`/`yaml` |
| `--debug` | 否 | 启用调试输出 |

> *如果在 GitLink 仓库目录下执行，`--owner` 和 `--repo` 可自动推断。

## API

```
GET /{owner}/{repo}/builds?page=1&limit=20
```

**响应示例：**

```json
{
  "ok": true,
  "data": {
    "builds": [
      {
        "id": 42,
        "build_number": 42,
        "status": "success",
        "started_at": "2026-01-01T10:00:00Z",
        "duration": 125,
        "commit": {
          "sha": "abc123...",
          "message": "Fix bug in authentication",
          "author": "developer@example.com"
        },
        "branch": "feature/auth-fix",
        "stages": [
          {
            "stage_number": 1,
            "stage_name": "build",
            "status": "success"
          },
          {
            "stage_number": 2,
            "stage_name": "test",
            "status": "success"
          }
        ]
      },
      {
        "id": 41,
        "build_number": 41,
        "status": "failed",
        "started_at": "2026-01-01T09:30:00Z",
        "duration": 45,
        "commit": {
          "sha": "def456...",
          "message": "Add new feature",
          "author": "developer@example.com"
        },
        "branch": "develop",
        "stages": [
          {
            "stage_number": 1,
            "stage_name": "build",
            "status": "failed"
          }
        ]
      }
    ],
    "total_count": 156
  },
  "meta": {
    "page": 1,
    "limit": 20,
    "total_count": 156
  }
}
```

## Workflow

1. **Resolve** owner and repo (from git remote or flags).
2. **Execute** `gitlink-cli ci +builds`.
3. **Display** builds in the requested format.

> [!NOTE]
> This is a **Read Operation** — no confirmation needed.

## Use Cases

- **构建历史查看**：查看仓库的构建历史和状态
- **问题排查**：查找失败的构建进行分析
- **构建监控**：监控 CI/CD 系统的运行状态
- **自动化脚本**：结合 JSON 格式输出进行构建分析

## Build Status

构建状态类型：

| 状态 | 说明 |
|------|------|
| `pending` | 等待执行 |
| `running` | 正在执行 |
| `success` | 构建成功 |
| `failed` | 构建失败 |
| `cancelled` | 构建取消 |
| `skipped` | 构建跳过 |

## Data Analysis

使用 JSON 输出进行构建分析：

```bash
# 查看最近10次构建的成功率
gitlink-cli ci +builds --format json --limit 10 | \
  jq '[.data.builds[] | select(.status=="success")] | length / 10 * 100'

# 查看失败的构建
gitlink-cli ci +builds --format json | \
  jq '.data.builds[] | select(.status=="failed")'

# 查看平均构建时间
gitlink-cli ci +builds --format json | \
  jq '[.data.builds[].duration] | add / length'
```

## Tips

- 使用 `--format json` 可以更好地解析和分析构建数据
- 构建列表包含详细的提交信息和分支信息
- 支持分页，适合构建历史较多的仓库
- 结合 `ci +logs` 可以深入分析构建失败原因

## CI/CD Integration

结合其他 CI 命令的典型工作流：

```bash
# 1. 查看构建列表
gitlink-cli ci +builds

# 2. 查看失败构建的日志
gitlink-cli ci +logs --build 42

# 3. 重启失败的构建
gitlink-cli ci +restart --build 42
```

## References

- [ci +logs](ci-logs.md) — 查看构建日志
- [ci +restart](ci-restart.md) — 重启构建
- [ci +stop](ci-stop.md) — 停止构建
- [gitlink-ci](../SKILL.md) — CI/CD 操作总览
- [gitlink-shared](../../gitlink-shared/SKILL.md) — 认证和全局参数
