151 lines
7.8 KiB
Markdown
151 lines
7.8 KiB
Markdown
---
|
|
name: gitea-fix-ci
|
|
description: "Diagnose failing, skipped, or missing Gitea/Forgejo Actions and PR checks, including prepare→workflow_run trigger chains, then produce an evidence-backed repair plan before changing code. Use for CI 挂了/流水线红了/构建失败/工作流失败 on Gitea-hosted repositories. Do not use for GitHub/GitLab or external CI, local-only test/lint requests, or cases with neither remote access nor supplied logs."
|
|
---
|
|
|
|
# Gitea Fix CI
|
|
|
|
## 核心约束
|
|
|
|
- 把 run、job 和日志当证据；未取证前不猜根因、不改代码。
|
|
- 先制定最小修复计划，在显式检查点等待授权。
|
|
- 区分本地修改、push、重跑 workflow、runner/secret 操作；一种授权不包含另一种。
|
|
- 取证脚本只读取 Gitea Actions，不分类、不修复、不改变远端状态。
|
|
|
|
随附脚本位于 `scripts/fetch_ci_logs.py`。全局选项必须放在子命令前：
|
|
|
|
```bash
|
|
python <skill-dir>/scripts/fetch_ci_logs.py version
|
|
python <skill-dir>/scripts/fetch_ci_logs.py --json runs --limit 20
|
|
python <skill-dir>/scripts/fetch_ci_logs.py --json jobs <run-id>
|
|
python <skill-dir>/scripts/fetch_ci_logs.py --json logs <job-id> --tail 80
|
|
```
|
|
|
|
认证优先级为 `GITEA_TOKEN` → 显式 `--use-git-credential` → 匿名访问。只在 HTTPS
|
|
同源请求中发送认证 header；拒绝跨源请求与跨源重定向。不得把 token、用户名、密码
|
|
放进 argv、日志或对话。
|
|
|
|
## 输入
|
|
|
|
- 当前仓库路径和 remote，默认使用当前工作区与 `origin`
|
|
- PR 编号、分支、完整 commit SHA、workflow run ID 或 job ID
|
|
- Gitea base URL 与 owner/repo；优先从 remote 推导
|
|
- `GITEA_TOKEN`、已配置的 `tea` profile，或显式 Git HTTP 凭据授权
|
|
- 无法访问远端时，由用户提供的最小 CI 日志
|
|
|
|
## 适用边界
|
|
|
|
适用于 Gitea/Forgejo 托管的 Actions、PR checks 和 workflow_run 触发链；入口可以是
|
|
PR、run、job、commit SHA 或用户提供的 CI 日志。
|
|
|
|
不适用于 GitHub/GitLab、仅从 Gitea 链出的外部 CI、只想本地跑测试/lint，或既无远端
|
|
访问也无用户日志的请求。
|
|
|
|
## 取证路径
|
|
|
|
先选择一条路径，再读取对应文件；不要把互斥路径的细节全部载入：
|
|
|
|
| 触发条件 | 必须读取 | 下一步 |
|
|
| ----------------------------------------------- | ------------------------------------------------------ | -------------------------------------------------------------- |
|
|
| 脚本可运行且 Actions API 可用 | [`workflows/actions-api.md`](workflows/actions-api.md) | 用 workflow、事件、状态和时间遍历直接 run 或 `workflow_run` 链 |
|
|
| 脚本不可用但 `tea actions` 可用 | [`workflows/fallback.md`](workflows/fallback.md) | 使用 tea 定位 run/job/log |
|
|
| Actions API 返回 404，旧实例仍有 Actions web UI | [`workflows/fallback.md`](workflows/fallback.md) | 从 run 页面选择失败 job index |
|
|
| 只有用户粘贴的日志 | [`workflows/fallback.md`](workflows/fallback.md) | 标记远端 run/job 未核验 |
|
|
|
|
## 流程
|
|
|
|
1. **记录基线**
|
|
|
|
运行 `git status --short`，记录当前分支、HEAD 和 `git remote -v`。通过已知实例或
|
|
`/api/v1/version` 确认 remote 属于 Gitea/Forgejo。取证期间不修改文件。
|
|
|
|
2. **选择路径并定位 run**
|
|
|
|
按上表读取一个 workflow 文件并执行。入口是 PR 时，先读取仓库 workflow 的 `on:`
|
|
段，判断失败检查是直接触发，还是由 Prepare 等上游 workflow 经 `workflow_run`
|
|
触发。不得默认所有 run 都保存 PR 分支或 PR head SHA。
|
|
|
|
区分 `failure`、`cancelled`、`skipped` 和缺失：
|
|
|
|
- 有明确 run ID 时直接查该 run。
|
|
- 直接触发的 PR workflow 优先按完整 PR head SHA 过滤；只有实例已验证
|
|
`head_branch` 语义时才把 PR 分支作为辅助过滤条件。
|
|
- `workflow_run` 链先定位上游 run，再判断是否应存在下游 run。
|
|
- 上游失败或取消时，证据优先在上游日志；下游通常为 `skipped`，也可能缺失。
|
|
|
|
3. **获取最小日志证据**
|
|
|
|
先列 jobs，再下载失败 job 日志；取消或基础设施场景读取最后执行或被取消的相关
|
|
job。保存完整日志到受跟踪源码路径之外，只回显首个可操作错误块及必要上下文。
|
|
记录 workflow、job、run URL、事件、状态、分支和 SHA。日志缺失时明确报告，不编造
|
|
原因。
|
|
|
|
4. **分类失败**
|
|
|
|
- **代码/测试失败**：断言、编译、lint 或类型错误
|
|
- **环境失败**：secret、镜像、依赖、网络、缓存、权限或服务启动
|
|
- **工作流失败**：YAML、触发条件、路径、ref 或事件假设错误
|
|
- **基础设施失败**：runner 离线、队列、取消、超时
|
|
- **上游门禁未通过**：Prepare 等上游 `failure`/`cancelled`，导致下游 `skipped` 或缺失
|
|
|
|
把日志直接显示的事实与根因假设分开。断言、编译错误或心跳中断只证明直接症状；
|
|
读取相关源码、配置或运行环境前，不把默认值、版本或资源假设写成已确认根因。
|
|
|
|
5. **制定修复计划**
|
|
|
|
用确切 run/job 标识总结证据，提出与证据匹配的最小修改。优先复用失败 job 的原命令
|
|
做本地验证；只能运行不同命令时标为“近似验证”，说明差异并保留远端复检路径。
|
|
|
|
6. **🔴 CHECKPOINT · 🛑 STOP：等待修复授权**
|
|
|
|
展示计划后停止。批准修改本地文件不等于批准 push 或重跑；批准重跑不等于批准
|
|
重启/重新注册 runner、修改 secret 或其它基础设施状态。授权不明确时保持只读取证。
|
|
|
|
7. **批准后实施**
|
|
|
|
只应用已批准的修复，运行最接近 CI 的本地命令。工作流改动需验证语法、触发条件、
|
|
引用路径和事件字段。
|
|
|
|
8. **复检**
|
|
|
|
区分本地验证与远端状态。说明需要 push 或重跑什么；只有获得相应授权后才执行或
|
|
查询重跑。
|
|
|
|
## 输出约定
|
|
|
|
- `Target:` 仓库、PR、分支/SHA 或 run ID
|
|
- `Failed CI:` workflow、job、状态与 run URL/API 路径
|
|
- `Evidence:` 最小日志片段、分类、已确认事实与待验证假设
|
|
- `Plan:` 最小修复、本地验证方式与远端复检
|
|
- `Changes:` 批准后修改的文件
|
|
- `Result:` 已运行检查与剩余远端状态
|
|
|
|
## 成功标准
|
|
|
|
- 分析基于 Gitea run/job/log 或明确标注的粘贴日志
|
|
- 计划指向确切 workflow run/job 或确切的上游门禁
|
|
- 计划批准前不修改本地文件或远端状态
|
|
- 不泄露凭据或整段私有日志
|
|
- 最终结果区分本地验证、推断关联与远端已核验状态
|
|
|
|
## 危险信号
|
|
|
|
- 未下载日志就断言原因或修改代码
|
|
- 把 `status=completed` 当成功，而不看 `conclusion`
|
|
- 按 PR 分支或 PR SHA 过滤 `workflow_run` 下游 run
|
|
- Prepare 失败后继续寻找不存在的“下游失败日志”，忽略 `skipped`/缺失
|
|
- 在 web 回退中盲取 job index `0`
|
|
- 把 `version` 成功当成 Actions API 一定可用
|
|
- 把 `cancelled`、runner 或队列问题当代码 bug
|
|
- 静默读取凭据、使用 HTTP、跨源发送认证 header
|
|
- 越权 push、重跑、改 secret 或操作 runner
|
|
|
|
## 失败处理
|
|
|
|
- 401：提供 `GITEA_TOKEN` 或显式使用 `--use-git-credential`；已认证仍 401 时检查凭据
|
|
- 403：补足仓库和 Actions 读取权限，不降级为匿名
|
|
- 404：核对 owner/repo、endpoint 和版本；旧版 Actions API 转 web 回退
|
|
- 下游候选无法与上游可靠关联：报告“关联未证实”，使用日志中的 ref/SHA 或用户提供的 run URL
|
|
- 外部 CI：报告外部 URL 后停止本 skill
|
|
- 只有基础设施问题：计划重跑或排查 runner，不修改源码
|