MerCry
/
ai-robot-channel
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
ai-robot-channel/docs/setup-gitea-actions-gate.md

3.2 KiB
Raw Blame History

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：复杂任务接续协议。