75 lines
3.2 KiB
Markdown
75 lines
3.2 KiB
Markdown
# Gitea（Docker）落地：分支保护 + Actions/Runner + OpenAPI 全量门禁（操作手册）
|
||
|
||
本文档用于在**新环境/新机器**上从零落地本仓库的“规范驱动 + 接口先行”门禁体系，确保换环境后无需重新摸索。
|
||
|
||
---
|
||
|
||
## 0. 目标与产物
|
||
|
||
落地后应满足：
|
||
- [ ] `main` 禁止直接 push，仅允许 PR 合并
|
||
- [ ] PR 合并到 `main` 时自动运行 Actions（全量门禁）
|
||
- [ ] 环境无法访问 GitHub 时也能正常运行校验
|
||
|
||
仓库内相关文件（必须存在于 `main`）：
|
||
- `agents.md`：AI 编码总纲
|
||
- `spec/contracting.md`：契约标准
|
||
- `scripts/*.sh`：核心校验脚本（Level/Traceability/Diff）
|
||
- `.gitea/workflows/pr-check.yaml`：全量门禁工作流
|
||
|
||
---
|
||
|
||
## 1. Gitea Actions 基础建设
|
||
|
||
按照 `docs/setup-gitea-actions-gate.md` 中的步骤完成：
|
||
1. **Gitea 配置**：在 `app.ini` 中启用 `[ACTIONS] ENABLED = true`。
|
||
2. **Runner 部署**：启动 `gitea/act_runner:latest` 容器并成功注册到 Gitea。
|
||
3. **内网连接**：使用宿主机内网 IP 作为 `GITEA_INSTANCE_URL`。
|
||
|
||
---
|
||
|
||
## 2. 启用全量自动化门禁
|
||
|
||
### 2.1 门禁项列表
|
||
|
||
当前的 `.gitea/workflows/pr-check.yaml` (Job ID: `sdd-full-gate`) 包含以下检查：
|
||
|
||
| 门禁项 | 脚本位置 | 检查逻辑 | 失败处理 |
|
||
| :--- | :--- | :--- | :--- |
|
||
| **1. 契约成熟度** | `check-openapi-level.sh` | 校验 `info.x-contract-level`。合并 main 必须 ≥ L2。 | AI 需更新 OpenAPI 文件等级。 |
|
||
| **2. 需求追踪** | `check-traceability.sh` | 校验代码中的 `[AC-ID]` 是否在 `requirements.md` 中定义过。 | AI 需补充需求文档或修正代码注释。 |
|
||
| **3. Breaking Change** | `check-openapi-diff.sh` | 对比 `main` 分支，拦截被删除的 Endpoint 或 Method。 | AI 需还原破坏性变更或与人类确认。 |
|
||
| **4. 最小自测** | 内置命令 | 执行 `mvn test`（Java）。若 Runner 环境无 mvn 则跳过并提示。 | AI 需修复单测或编译错误。 |
|
||
|
||
### 2.2 在 Gitea 中开启硬约束
|
||
|
||
1. **触发第一次运行**：新建一个 PR 到 `main`（修改 `src/` 或 `spec/` 下的文件）。
|
||
2. **配置分支保护**：
|
||
* 进入 `仓库设置 -> 分支 -> 保护分支(main)`。
|
||
* 勾选 **“启用状态检查”**。
|
||
* 在输入框中填入：`sdd-full-gate`。
|
||
* 保存。
|
||
|
||
---
|
||
|
||
## 3. 常见排障与优化
|
||
|
||
### 3.1 离线环境报错
|
||
如果报错 `GITEA_SERVER_URL is required`，请确认已合并最新的 `.gitea/workflows/pr-check.yaml`。当前版本已支持自动探测 `GITHUB_` 与 `GITEA_` 系列变量。
|
||
|
||
### 3.2 Maven (mvn) 找不到
|
||
如果日志提示 `Warning: mvn not found`，说明你的 Runner 镜像（ubuntu-latest）没有预装 Maven。
|
||
* **短期**：脚本会自动跳过，不阻断合并。
|
||
* **长期建议**：定制 Docker 镜像或在宿主机安装 Maven 并卷入容器。
|
||
|
||
### 3.3 Python yaml 模块缺失
|
||
脚本会自动尝试 `pip install pyyaml`。如果依然失败，YAML 语法解析步骤将自动跳过，不影响核心契约校验。
|
||
|
||
---
|
||
|
||
## 4. 关联文档入口
|
||
|
||
- `agents.md`：AI 实时遵循的提交与编码节奏。
|
||
- `docs/contracting-guide.md`：契约治理与 Gitea 避坑指南。
|
||
- `docs/session-handoff-protocol.md`：复杂任务接续协议。
|