forked from Gitlink/gitlink-cli
246 lines
6.4 KiB
Markdown
246 lines
6.4 KiB
Markdown
# 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) — 认证和全局参数
|