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

ci +restart

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

重新启动失败的或取消的 CI 构建。

命令

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

# 指定仓库重启构建
gitlink-cli ci +restart --build 42 --owner myuser --repo myrepo

# 重启失败的构建（JSON 输出）
gitlink-cli ci +restart --build 42 --format json

参数

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

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

API

POST /{owner}/{repo}/builds/{build}/restart

响应示例：

{
  "ok": true,
  "data": {
    "old_build_number": 42,
    "new_build_number": 43,
    "status": "pending",
    "message": "Build restarted successfully",
    "triggered_at": "2026-01-01T11:00:00Z"
  }
}

Workflow

1. Confirm the build number to restart with the user.
2. Check the current build status (optional, using ci +builds).
3. Execute gitlink-cli ci +restart --build <number>.
4. Report the restart result and new build number.

[!CAUTION] This is a Write Operation — confirm user intent before executing.

Use Cases

• 失败重试：构建因临时问题失败后重试
• 取消后重新执行：构建被取消后需要重新执行
• 代码修复后验证：修复代码后重新验证构建
• 环境问题恢复：CI 环境问题恢复后重新构建

When to Restart

适合重启的情况：

• ✅ 构建因临时网络问题失败
• ✅ 依赖服务暂时不可用
• ✅ 代码修复后需要重新验证
• ✅ CI 环境问题已解决

不适合重启的情况：

• ❌ 代码存在严重错误
• ❌ 测试用例本身有问题
• ❌ 构建配置需要修改
• ❌ 依赖库版本不兼容

Restart Behavior

重启构建的行为特点：

方面	说明
新构建编号	重启会创建新的构建编号
相同代码	使用相同的提交代码
相同环境	使用相同的构建环境
独立日志	新构建有独立的日志记录
状态继承	不会继承原构建的状态

Best Practices

1. 查看日志：重启前先查看失败原因
2. 修复问题：如果是代码问题，先修复再重启
3. 监控新构建：重启后监控新构建的执行状态
4. 资源考虑：频繁重启会消耗 CI 资源

Troubleshooting Workflow

典型的故障排查和重启流程：

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

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

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

# 4. 分析日志，确定失败原因

# 5. 如果是临时问题，重启构建
gitlink-cli ci +restart --build 42

# 6. 如果是代码问题，修复后重启
# (先修复代码，然后)
gitlink-cli ci +restart --build 42

Error Handling

常见错误及解决方案：

错误	原因	解决方案
404	构建不存在	检查构建编号是否正确
400	构建正在运行	正在运行的构建无法重启
403	权限不足	确认有操作该仓库构建的权限
429	重启次数过多	短时间内重启次数过多，等待后重试

Pre-Restart Checklist

重启前检查清单：

• 确认构建编号正确
• 查看失败日志，了解失败原因
• 确认问题已解决（如果是代码问题）
• 检查 CI 系统状态
• 确认有足够的 CI 资源
• 考虑是否需要修改构建配置

Post-Restart Actions

重启后的后续操作：

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

# 2. 获取新构建编号
gitlink-cli ci +restart --build 42 --format json | \
  jq '.data.new_build_number'

# 3. 监控新构建状态
gitlink-cli ci +builds --format json | \
  jq '.data.builds[0]'

# 4. 查看新构建的日志（如需要）
gitlink-cli ci +logs --build 43 --stage 1 --step 1

Team Collaboration

团队协作时的建议：

1. 沟通确认：重启构建前通知相关团队成员
2. 记录原因：记录重启的原因和时间
3. 状态更新：及时更新构建状态给团队
4. 结果分享：重启完成后分享结果

Tips

• 重启会创建新的构建编号，原构建历史仍保留
• 重启前建议先查看日志，确认问题性质
• 对于重复失败的情况，建议先修复根本原因
• 可以通过 ci +builds 查看重启后的新构建状态

Cost Considerations

使用注意事项：

• ⚠️ 资源消耗：每次重启都会消耗 CI 资源
• ⚠️ 时间成本：重新执行完整的构建流程
• ⚠️ 排队时间：新构建可能需要排队等待
• ⚠️ 频繁重启：避免无意义的频繁重启

References

• ci +builds — 查看构建列表
• ci +logs — 查看构建日志
• ci +stop — 停止构建
• gitlink-ci — CI/CD 操作总览
• gitlink-shared — 认证和全局参数