ci-fix

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

CI fix (GitHub Actions)

CI修复（GitHub Actions）

Goal

目标

Get CI green quickly with minimal, reviewable diffs.
Use
```
gh
```
to locate failing runs, inspect logs/artifacts, rerun jobs, and confirm the fix.

以最小、可评审的差异快速让CI运行通过（变绿）。
使用
```
gh
```
定位失败的运行、检查日志/构建产物、重跑任务、确认修复生效。

Inputs to ask for (if missing)

需要询问的输入（如果缺失）

Repo (
```
OWNER/REPO
```
) and whether this is a PR or branch build.
Failing run URL/ID (or PR number / branch name).
What "green" means (required workflows? allowed flaky reruns?).
Any constraints (no workflow edits, no permission changes, no force-push, etc.).

仓库（
```
OWNER/REPO
```
）以及本次是PR构建还是分支构建。
失败的运行链接/ID（或PR编号/分支名）。
“运行通过”的定义（要求哪些工作流必须通过？允许多少次不稳定任务重跑？）。
任何限制条件（不能修改工作流、不能修改权限、不能强制推送等）。

Workflow (checklist)

工作流（检查清单）

Confirm
```
gh
```
context
- Auth:
```
gh auth status
```
- Repo:
```
gh repo view --json nameWithOwner -q .nameWithOwner
```
- If needed, add
```
-R OWNER/REPO
```
  to all commands.
- If
```
gh
```
  is not installed or not authenticated, tell the user and ask whether to install/authenticate or proceed by pasting logs/run URLs manually.

Find the failing run

If you have a run URL, extract the run ID:
```
.../actions/runs/<id>
```
.

Otherwise:

Recent failures:
```
gh run list --limit 20 --status failure
```

Branch failures:

gh run list --branch <branch> --limit 20 --status failure

Workflow failures:

gh run list -w <workflow> --limit 20 --status failure

Open in browser:
```
gh run view <id> --web
```

Pull the signal from logs

Job/step overview:
```
gh run view <id> --verbose
```
Failed steps only:
```
gh run view <id> --log-failed
```
Full log for a job:
```
gh run view <id> --log --job <job-id>
```
Download artifacts:
```
gh run download <id> -D .artifacts/<id>
```

Identify root cause (prefer the smallest fix)
- Use
```
references/ci-failure-playbook.md
```
  for common patterns and safe fixes.
- Prefer: deterministic code/config fix > workflow plumbing fix > rerun flake.
Implement the fix (minimal diff)
- Update code/tests/config and/or
```
.github/workflows/*.yml
```
  .
- Keep changes scoped to the failing job/step.
- If changing triggers/permissions/secrets, call out risk and get explicit confirmation.

Verify in GitHub Actions

Rerun only failures:
```
gh run rerun <id> --failed
```

Rerun a specific job (note: job databaseId):

gh run view <id> --json jobs --jq '.jobs[] | {name,databaseId,conclusion}'

Watch until done:

gh run watch <id> --compact --exit-status

Manually trigger:

gh workflow run <workflow> --ref <branch>

确认
```
gh
```
上下文
- 鉴权状态：
```
gh auth status
```
- 当前仓库：
```
gh repo view --json nameWithOwner -q .nameWithOwner
```
- 如需指定仓库，给所有命令添加
```
-R OWNER/REPO
```
  参数。
- 如果
```
gh
```
  未安装或未完成鉴权，告知用户，询问是要安装/完成鉴权，还是手动粘贴日志/运行链接继续操作。

查找失败的运行记录

如果有运行链接，提取运行ID：
```
.../actions/runs/<id>
```
。

否则：

最近的失败运行：
```
gh run list --limit 20 --status failure
```

指定分支的失败运行：

gh run list --branch <branch> --limit 20 --status failure

指定工作流的失败运行：

gh run list -w <workflow> --limit 20 --status failure

在浏览器中打开：
```
gh run view <id> --web
```

从日志中提取有效信息
- 任务/步骤概览：
```
gh run view <id> --verbose
```
- 仅查看失败步骤：
```
gh run view <id> --log-failed
```
- 查看单个任务的完整日志：
```
gh run view <id> --log --job <job-id>
```
- 下载构建产物：
```
gh run download <id> -D .artifacts/<id>
```
定位根本原因（优先选择最小修复方案）
- 参考
```
references/ci-failure-playbook.md
```
  查看常见故障模式和安全修复方案。
- 优先级：确定性的代码/配置修复 > 工作流流程修复 > 重跑不稳定任务。
实施修复（最小差异）
- 更新代码/测试/配置和/或
```
.github/workflows/*.yml
```
  文件。
- 确保修改仅作用于失败的任务/步骤。
- 如果修改触发规则/权限/密钥，需明确告知风险并获得用户明确确认。

在GitHub Actions中验证修复

仅重跑失败的任务：
```
gh run rerun <id> --failed
```

重跑指定任务（注意：任务的databaseId）：

gh run view <id> --json jobs --jq '.jobs[] | {name,databaseId,conclusion}'

监控运行直到结束：

gh run watch <id> --compact --exit-status

手动触发运行：

gh workflow run <workflow> --ref <branch>

Safety notes

安全注意事项

Avoid
```
pull_request_target
```
(and any change that runs untrusted fork code with secrets) unless the user explicitly requests it and understands the security tradeoffs.
Keep workflow
```
permissions:
```
least-privilege; don’t broaden token access “just to make it pass”.

避免使用
```
pull_request_target
```
（以及任何会使用密钥运行不受信任的Fork代码的修改），除非用户明确要求且了解安全权衡。
保持工作流
```
permissions:
```
权限最小化，不要“为了让运行通过”随便扩大Token的访问权限。

Deliverable (paste in chat / PR)

交付物（粘贴到聊天/PR中）

Summary: ...
Failing run: <link/id> (job/step)
Root cause: ...
Fix: ...
Verification: commands + new run link/id
Notes/risks: ...

总结： ...
失败运行： <链接/ID>（任务/步骤）
根本原因： ...
修复方案： ...
验证： 执行的命令 + 新运行链接/ID
备注/风险： ...