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

ci +stop

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

停止正在运行的 CI 构建。

命令

# 停止构建
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

响应示例：

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

典型的停止构建工作流：

# 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

停止后的后续操作：

# 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：发现严重错误

# 查看运行中的构建
gitlink-cli ci +builds | grep "running"

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

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

场景2：误触发构建

# 发现误触发了构建
gitlink-cli ci +builds | grep "running"

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

场景3：配置错误

# 发现构建配置错误
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 +logs — 查看构建日志
• ci +restart — 重启构建
• gitlink-ci — CI/CD 操作总览
• gitlink-shared — 认证和全局参数