crm-backend-matt/docs/agents/gitea-setup.md

Gitea 仓库管理员设置

本文件是仓库级配置的人工执行清单。以下设置必须由拥有 Gitea 管理权限的人在 Web 界面完成，不能由普通开发分支或 CI 代替。

一次性迁移

1. 在组织空间中确认至少两名仓库管理员；关闭单一个人账号持有唯一管理员权限的状态。
2. 在所有未提交改动清理、提交或隔离后，将默认分支从 master 重命名为 main；更新默认分支设置与本地 clone 的跟踪分支。
3. 以该干净、可构建提交创建 annotated baseline tag，例如 baseline-2026-09。tag 记录的是可复现代码，不是脏工作区状态。
4. 确认 Actions runner 已注册 ubuntu-latest 标签，且能从允许的 actions 来源拉取 actions/checkout 与 actions/setup-java。

main 分支保护

在仓库 Settings → Branches 中为 main 创建保护规则：

• 禁止直接 push 与 force push；
• 仅允许 Pull Request 合并；
• 至少一名非作者审批；
• 所有讨论必须解决；
• 合并前分支必须更新到目标分支；
• Build and Test / Maven verify (JDK 17) 必须成功；
• 默认允许 squash merge，合并后自动删除 head branch；
• 不给 Agent、CI 机器人或普通开发者 bypass 分支保护权限。

在迁移完成前，对 master 启用同一规则。迁移后再删除 master 的保护规则。

成员与所有权

1. 创建最小权限团队：维护者、开发者、只读协作者；生产或组织管理权限不授予开发者和 Agent。
2. 以 CODEOWNERS.example 为基础，填入真实 Gitea 用户或团队，再另存为根目录 CODEOWNERS。
3. 仅在确认 Gitea 版本会识别 CODEOWNERS 后，将公共模块、高冲突区和部署目录设为必须由 owner 审核。
4. 每个开发者使用个人 SSH key；禁止共享账号、共享 token 或在仓库、PR、日志中保存密钥。

0–1 阶段的质量策略

当前 required check 仅包括 CI 中的 Maven verify 和 Java BOM 检查。没有独立验收环境时，PR 模板中的人工验证记录是必要证据，但不等同于自动化验收。具备稳定集成环境后，先新增可重复的集成测试，再把相应检查设为 required；不要在尚未稳定前设置会长期红灯的门禁。