---
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，不修改源码