gitlink-cli/skills/gitlink-ci/references/ci-list.md

ci +builds

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

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

命令

# 查看当前仓库的构建列表
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

响应示例：

{
  "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 输出进行构建分析：

# 查看最近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 命令的典型工作流：

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

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

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

References

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