# ci +restart

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

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

## 命令

```bash
# 重启构建
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
```

**响应示例：**

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

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

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

重启后的后续操作：

```bash
# 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-list.md) — 查看构建列表
- [ci +logs](ci-logs.md) — 查看构建日志
- [ci +stop](ci-stop.md) — 停止构建
- [gitlink-ci](../SKILL.md) — CI/CD 操作总览
- [gitlink-shared](../../gitlink-shared/SKILL.md) — 认证和全局参数
