# ci +logs

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

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

## 命令

```bash
# 查看构建日志
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}
```

**响应示例：**

```json
{
  "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

日志分析技巧：

```bash
# 查看构建日志
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

查看不同阶段的日志：

```bash
# 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

典型的故障排查工作流：

```bash
# 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

高级用法示例：

```bash
# 导出构建日志到文件
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-list.md) — 查看构建列表
- [ci +restart](ci-restart.md) — 重启构建
- [gitlink-ci](../SKILL.md) — CI/CD 操作总览
- [gitlink-shared](../../gitlink-shared/SKILL.md) — 认证和全局参数
