playbook/skills/gitea-fix-ci/SKILL.md

name, description

name	description
gitea-fix-ci	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。全局选项必须放在子命令前：

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	用 workflow、事件、状态和时间遍历直接 run 或 workflow_run 链
脚本不可用但 tea actions 可用	workflows/fallback.md	使用 tea 定位 run/job/log
Actions API 返回 404，旧实例仍有 Actions web UI	workflows/fallback.md	从 run 页面选择失败 job index
只有用户粘贴的日志	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，不修改源码