diff --git a/.gitea/workflows/ci.yml b/.gitea/workflows/ci.yml index 28fb166..6b81822 100644 --- a/.gitea/workflows/ci.yml +++ b/.gitea/workflows/ci.yml @@ -3,7 +3,13 @@ name: CI on: push: branches: [main] + # 纯文档提交不消耗 2 核 runner;需要状态时用 workflow_dispatch 手动触发。 + paths-ignore: + - "**.md" + # PR 不设置 paths-ignore:branch protection 的 required checks 必须始终上报, + # 否则纯文档 PR 会永远等不到状态检查而无法合并。 pull_request: + workflow_dispatch: concurrency: group: ci-${{ github.ref }} diff --git a/docs/ci.md b/docs/ci.md index 7727209..9f966aa 100644 --- a/docs/ci.md +++ b/docs/ci.md @@ -4,6 +4,8 @@ ## Runner +安装与运维步骤见 `docs/runner-setup.md`(`deploy/runner/install-runner.sh` 可复现整套配置)。 + - 程序:`gitea-runner` v5.2.0(linux/arm64),位于 `/home/ubuntu/gitea-runner` - 服务:systemd user unit `gitea-runner.service` - 标签:`ubuntu-latest`、`oracle-arm` @@ -67,7 +69,7 @@ Runner 日志级别保持 `debug`:`info` 级别不会记录各 step 的 `Succe 该轮次全部告警均来自缓存后端不可达(`ETIMEDOUT`),已按上一节修复。 -修复后的对照数据(run `22`,commit `261a33a`): +修复后的对照数据(run `22`,commit `261a33a`;run `23` 的 static 为 5.7 分钟): | job | 修复前耗时 | 修复后耗时 | | ---------------- | ---------- | --------------------------------------------------------- | @@ -76,3 +78,31 @@ Runner 日志级别保持 `debug`:`info` 级别不会记录各 step 的 `Succe | API integration | 9.7 min | 3.8 min | 缓存内容为 pnpm store,首次落盘约 268 MB,位于 `/home/ubuntu/gitea-runner/cache-data`。 + +## 触发范围 + +- `push` 到 `main` 时忽略纯文档改动(`**.md`),避免 2 核主机为文档提交跑完整 CI。 +- `pull_request` 不设置 `paths-ignore`。branch protection 要求的 status check 必须每次都上报,否则纯文档 PR 会一直停在「等待检查」而无法合并。 +- 需要给纯文档提交补一次状态时,用 `workflow_dispatch` 手动触发。 + +模板完成证据的源码哈希已同步收敛,文档、CI 配置和部署脚本改动不再使证据失效;模板、renderer、Admin 模板编辑器、品牌内容 API 等会影响交付的源码改动仍会更新哈希。`pre-commit` 会按 Git index 重算并暂存证据,不再需要单独的 `chore: 更新模板完成证据源码哈希` 提交。注意:`pre-commit` 只在该仓库执行过 `pnpm install`(触发 `prepare` 设置 `core.hooksPath`)后生效。 + +## 分支保护 + +`main` 由 Gitea branch protection 保护,规则为: + +- 禁止直接 push 和 force push,所有改动走分支 + Pull Request。 +- 必须通过 `CI / *` 状态检查(覆盖 `Static checks`、`Production build`、`API integration` 及其后续新增 job)。 +- `required_approvals = 0`:当前是单人维护,不强制他人审批,但 CI 必须全绿。 + +仓库管理员如需紧急放行,应临时调整保护规则并在事后恢复,不要长期用管理员权限绕过检查。规则可通过 `PATCH /api/v1/repos/que01/persionalBrand/branch_protections/main` 复现: + +```json +{ + "enable_push": false, + "enable_force_push": false, + "enable_status_check": true, + "status_check_contexts": ["CI / *"], + "required_approvals": 0 +} +```