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

ci +logs

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

查看指定 CI 构建的详细日志输出。

命令

# 查看构建日志
gitlink-cli ci +logs --build 42

# 查看特定阶段的日志
gitlink-cli ci +logs --build 42 --stage 2

# 查看特定步骤的日志
gitlink-cli ci +logs --build 42 --stage 2 --step 3

# 指定仓库查看日志
gitlink-cli ci +logs --build 42 --owner myuser --repo myrepo

参数

参数	必填	说明
--build, -b	是	构建编号
--stage, -s	否	阶段编号（默认 1）
--step	否	步骤编号（默认 1）
--owner	否*	仓库所有者（自动从 git remote 解析）
--repo	否*	仓库名称（自动从 git remote 解析）
--format	否	输出格式: json/table/yaml
--debug	否	启用调试输出

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

API

GET /{owner}/{repo}/builds/{build}/logs/{stage}/{step}

响应示例：

{
  "ok": true,
  "data": {
    "build_number": 42,
    "stage_number": 2,
    "step_number": 1,
    "log_content": "Running tests...\nTest suite started...\n[OK] Test authentication\n[OK] Test database connection\n[FAILED] Test API endpoint\n\nTests completed: 2/3 passed",
    "stage_name": "test",
    "step_name": "run_tests",
    "timestamp": "2026-01-01T10:05:30Z"
  }
}

Workflow

1. Confirm the build number with the user (can use ci +builds to list).
2. Execute gitlink-cli ci +logs --build <number> [--stage <n>] [--step <n>].
3. Display the log content.

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

Use Cases

• 问题排查：查看构建失败的具体原因
• 性能分析：分析构建过程中的性能瓶颈
• 调试输出：查看代码运行时的调试信息
• 监控执行：实时跟踪构建执行状态

CI Pipeline Structure

典型的 CI/CD 流水线结构：

Stage 1: Build
  ├── Step 1: Install dependencies
  ├── Step 2: Build application
  └── Step 3: Run linters

Stage 2: Test
  ├── Step 1: Run unit tests
  ├── Step 2: Run integration tests
  └── Step 3: Generate coverage report

Stage 3: Deploy
  ├── Step 1: Build deployment package
  └── Step 2: Deploy to server

Log Analysis

日志分析技巧：

# 查看构建日志
gitlink-cli ci +logs --build 42 --stage 2 --step 1

# 结合 grep 过滤关键错误
gitlink-cli ci +logs --build 42 --format json | \
  jq '.data.log_content' | grep "ERROR"

# 查看完整日志流
gitlink-cli ci +logs --build 42 --format json | \
  jq -r '.data.log_content'

Stage and Step Navigation

查看不同阶段的日志：

# Stage 1: Build stage
gitlink-cli ci +logs --build 42 --stage 1 --step 1

# Stage 2: Test stage
gitlink-cli ci +logs --build 42 --stage 2 --step 1

# Stage 3: Deploy stage
gitlink-cli ci +logs --build 42 --stage 3 --step 1

Common Log Patterns

常见日志模式：

模式	含义
[ERROR]	错误信息
[FAILED]	测试或步骤失败
[WARN]	警告信息
[OK]	操作成功
Running...	正在执行
Completed	执行完成

Tips

• 先使用 ci +builds 确认构建编号
• 构建通常包含多个阶段，需要指定正确的阶段编号
• 日志内容可能很长，建议使用 --format json 便于解析
• 结合构建状态可以快速定位问题

Troubleshooting Workflow

典型的故障排查工作流：

# 1. 查看构建列表，找到失败的构建
gitlink-cli ci +builds | grep "failed"

# 2. 查看失败构建的详细状态
gitlink-cli ci +builds --build 42 --format json | \
  jq '.data.builds[] | .stages[]'

# 3. 查看失败阶段的日志
gitlink-cli ci +logs --build 42 --stage 2 --step 1

# 4. 根据日志信息修复问题

# 5. 重启构建
gitlink-cli ci +restart --build 42

Error Handling

常见错误及解决方案：

错误	原因	解决方案
404	构建不存在	检查构建编号是否正确
404	阶段或步骤不存在	确认阶段和步骤编号
403	权限不足	确认有查看该仓库构建的权限

Advanced Usage

高级用法示例：

# 导出构建日志到文件
gitlink-cli ci +logs --build 42 --format json | \
  jq -r '.data.log_content' > build_42_logs.txt

# 分析日志中的错误模式
gitlink-cli ci +logs --build 42 --format json | \
  jq -r '.data.log_content' | grep -c "ERROR"

# 查看所有阶段的日志（循环）
for stage in {1..3}; do
  echo "=== Stage $stage ==="
  gitlink-cli ci +logs --build 42 --stage $stage --step 1
done

References

• ci +builds — 查看构建列表
• ci +restart — 重启构建
• gitlink-ci — CI/CD 操作总览
• gitlink-shared — 认证和全局参数