# ci +stop

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

停止正在运行的 CI 构建。

## 命令

```bash
# 停止构建
gitlink-cli ci +stop --build 42

# 指定仓库停止构建
gitlink-cli ci +stop --build 42 --owner myuser --repo myrepo

# 停止构建（JSON 输出）
gitlink-cli ci +stop --build 42 --format json
```

## 参数

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

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

## API

```
DELETE /{owner}/{repo}/builds/{build}/stop
```

**响应示例：**

```json
{
  "ok": true,
  "data": {
    "build_number": 42,
    "status": "cancelled",
    "message": "Build stopped successfully",
    "stopped_at": "2026-01-01T11:30:00Z",
    "duration": 180
  }
}
```

## Workflow

1. **Confirm** the build number to stop with the user.
2. **Check** the current build status (ensure it's running).
3. **Execute** `gitlink-cli ci +stop --build <number>`.
4. **Report** the stop result.

> [!CAUTION]
> This is a **Write Operation** — confirm user intent before executing. This will terminate a running build.

## Use Cases

- **错误停止**：构建出现错误需要立即停止
- **资源释放**：释放 CI 资源给其他构建
- **配置错误**：构建配置错误需要停止
- **测试中止**：测试过程中发现问题需要中止
- **时间限制**：构建时间过长需要停止

## When to Stop

**适合停止的情况：**
- ✅ 构建明显出现错误，继续执行无意义
- ✅ 发现严重bug，需要立即停止
- ✅ 构建配置错误，需要修改后重新执行
- ✅ 误触发构建，需要立即取消
- ✅ 构建时间过长，超出预期

**不适合停止的情况：**
- ❌ 构建接近完成
- ❌ 仅为节省时间而停止正常构建
- ❌ 不确定构建是否有问题

## Stop Behavior

停止构建的行为特点：

| 方面 | 说明 |
|------|------|
| **立即停止** | 通常会立即中断构建执行 |
| **状态变更** | 构建状态变为 `cancelled` |
| **资源释放** | 释放 CI 计算资源 |
| **日志保留** | 已执行的日志会保留 |
| **不可恢复** | 停止的构建无法恢复执行 |

## Safety Considerations

停止构建前考虑：

- ⚠️ **进度损失**：已执行的进度会丢失
- ⚠️ **资源浪费**：已消耗的资源无法回收
- ⚠️ **团队影响**：可能影响其他依赖此构建的任务
- ⚠️ **重新执行**：需要重新启动完整的构建

## Best Practices

1. **确认状态**：停止前确认构建确实在运行
2. **评估影响**：考虑停止对其他流程的影响
3. **记录原因**：记录停止构建的原因
4. **后续处理**：计划停止后的后续操作

## Stop Workflow

典型的停止构建工作流：

```bash
# 1. 查看运行中的构建
gitlink-cli ci +builds --format json | \
  jq '.data.builds[] | select(.status=="running")'

# 2. 确认要停止的构建编号
gitlink-cli ci +builds | grep "running"

# 3. 停止构建
gitlink-cli ci +stop --build 42

# 4. 验证停止状态
gitlink-cli ci +builds --format json | \
  jq '.data.builds[] | select(.build_number==42) | .status'
```

## Error Handling

常见错误及解决方案：

| 错误 | 原因 | 解决方案 |
|------|------|----------|
| `404` | 构建不存在 | 检查构建编号是否正确 |
| `400` | 构建已完成 | 构建已经完成或停止，无法再停止 |
| `403` | 权限不足 | 确认有操作该仓库构建的权限 |
| `409` | 构建已完成 | 构建已经自然结束 |

## Pre-Stop Checklist

停止前检查清单：

- [ ] 确认构建编号正确
- [ ] 确认构建正在运行
- [ ] 评估停止的影响范围
- [ ] 确认停止原因合理
- [ ] 考虑后续处理方案
- [ ] 通知相关团队成员

## Post-Stop Actions

停止后的后续操作：

```bash
# 1. 停止构建
gitlink-cli ci +stop --build 42

# 2. 查看停止状态
gitlink-cli ci +builds --format json | \
  jq '.data.builds[] | select(.build_number==42)'

# 3. 查看已执行的日志
gitlink-cli ci +logs --build 42 --stage 1 --step 1

# 4. 根据需要重启构建
gitlink-cli ci +restart --build 42
```

## Common Scenarios

常见使用场景：

### 场景1：发现严重错误
```bash
# 查看运行中的构建
gitlink-cli ci +builds | grep "running"

# 查看日志发现严重错误
gitlink-cli ci +logs --build 42 --stage 2 --step 1

# 立即停止构建
gitlink-cli ci +stop --build 42
```

### 场景2：误触发构建
```bash
# 发现误触发了构建
gitlink-cli ci +builds | grep "running"

# 立即停止误触发的构建
gitlink-cli ci +stop --build 42
```

### 场景3：配置错误
```bash
# 发现构建配置错误
gitlink-cli ci +logs --build 42 --stage 1 --step 1

# 停止当前构建
gitlink-cli ci +stop --build 42

# 修复配置后重新构建
# (修复配置)
gitlink-cli ci +restart --build 42
```

## Team Collaboration

团队协作时的建议：

1. **及时通知**：停止构建前通知相关团队成员
2. **说明原因**：向团队解释为什么需要停止构建
3. **状态同步**：更新项目管理系统中的构建状态
4. **后续计划**：告知团队停止后的处理计划

## Tips

- 停止前建议先确认构建状态，避免重复操作
- 查看构建日志可以帮助判断是否值得停止
- 停止后可以考虑是否需要重启或修复后重新构建
- 对于长时间运行的构建，定期检查状态可能更合适

## Alternatives

替代方案考虑：

| 情况 | 停止 | 等待完成 | 其他方案 |
|------|------|----------|----------|
| 严重错误 | ✅ 推荐 | ❌ 不推荐 | 修复后重启 |
| 临时问题 | ⚠️ 可选 | ✅ 推荐 | 等待自动恢复 |
| 配置错误 | ✅ 推荐 | ❌ 不推荐 | 修复配置后重启 |
| 时间过长 | ⚠️ 可选 | ✅ 推荐 | 优化构建流程 |

## References

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