BOVETECH Forgejo 开发协作操作说明

本文面向 LXK、嵌入式团队和生产软件团队，说明如何在 Forgejo 创建公司仓库、分配团队权限，以及通过 Git 分支和 PR 协作。公司项目统一放在 BOVETECH 组织下并设为私有；开发者在功能分支提交，通过 PR 审查后合并到主分支。

Forgejo 地址：https://g1t.bovetech.cn

一、组织、团队和仓库分别是什么

BOVETECH 组织：公司代码仓库的归属位置。
embedded：嵌入式开发团队，拥有分配给它的仓库读写权限。
embedded-leads：嵌入式仓库负责人权限组，目前由 LXK 使用。它只管理分配给该团队的仓库。
software：生产软件开发团队，拥有分配给它的仓库读写权限。
仓库：一个具体软件、固件或独立交付组件的代码及历史。仓库属于组织或个人，一个项目可以有一个或多个仓库。

组织团队不会自动获得组织所有仓库的权限。新建仓库后，必须明确把仓库分配给需要访问的团队。

二、在 BOVETECH 下创建私有仓库

登录 Forgejo，打开 BOVETECH 组织页面。
点击 新建仓库。如果从页面右上角“＋”菜单创建，务必将所有者选为 BOVETECH，不要放在个人账号下。
填写清楚的仓库名称，例如 device-firmware、production-client。需要时补充用途说明。
可见性选私有。
如果本地已经有项目代码，建议不要初始化 README、许可证或 .gitignore，避免首次推送时出现两段不同历史。若是新项目，可以勾选 README。
点击 创建仓库。

团队成员可以创建组织仓库。仓库创建者通常会有该仓库的管理权限；日常开发仍按团队权限进行。

三、将仓库分配给团队

仓库创建后，由创建者或有相应管理权限的人完成授权：

打开组织的团队页面，进入对应团队。
在团队的仓库页面，将新仓库添加到团队。
嵌入式仓库添加到 embedded，让开发人员可以读写；同时添加到 embedded-leads，让 LXK 可以管理仓库、配置分支保护和协作者。
生产软件仓库添加到 software。负责人若需要仓库管理员权限，应单独授权给负责人或建立负责人团队。
回到团队仓库列表，确认仓库和权限正确。

不要把普通开发者加入组织 Owners 团队；Owners 可管理整个组织。不要把团队设置为“包含全部组织仓库”，除非确实希望成员访问所有现有和未来的组织仓库。

四、首次设置本地 Git

每位开发者在自己的电脑安装 Git，并用个人账号登录 Forgejo。账号启用 2FA 后，HTTPS Git 的密码提示应使用个人访问令牌，而不是 Forgejo 登录密码。令牌在 头像 → 设置 → 应用 → 生成新令牌 创建，并保存到系统凭据管理器。不要共享令牌，也不要把它写入代码、命令行 URL 或聊天记录。

设置提交署名（每台电脑通常只做一次）：

git config --global user.name "你的姓名"
git config --global user.email "你的公司邮箱"

提交署名用于标记代码由谁编写，不负责登录认证。

五、克隆仓库并通过分支开发

从仓库网页的克隆按钮复制 HTTPS 地址，然后执行：

git clone https://g1t.bovetech.cn/BOVETECH/仓库名.git
cd 仓库名
git switch -c feat/简短功能名

例如：

git clone https://g1t.bovetech.cn/BOVETECH/device-firmware.git
cd device-firmware
git switch -c feat/uart-driver

修改代码并按项目要求运行构建和测试。提交前检查改动：

git status
git diff
git add 修改的文件
git commit -m "描述本次修改"
git push -u origin feat/uart-driver

不要提交密码、访问令牌、私钥、真实环境配置文件或构建缓存。提交之前用 git diff 确认没有不该上传的文件。

后续继续在同一分支工作：

git add 修改的文件
git commit -m "描述本次修改"
git push

六、发起 PR、审查和合并

推送分支后，在 Forgejo 仓库页面点击 新建合并请求（PR）。
确认目标仓库正确，目标分支选主分支（新仓库通常是 main；也可能是 master）。
写明修改目的、主要变更、测试方法和测试结果。需要时附截图或日志，但不要附密钥。
指定另一位熟悉该代码的同事审查。嵌入式代码可请 LXK 或指定开发者审查；生产软件由对应负责人安排。
审查者检查变更和测试，在 PR 中选择批准或要求修改。作者根据反馈继续提交并推送到同一分支。
规则满足后，由有合并权限的人点击合并。合并后可删除已完成的功能分支。

作者应避免自行批准自己的 PR。合并前确认目标分支、变更内容和测试结果。

七、LXK 配置仓库保护

每个嵌入式仓库创建后，由 LXK 在 仓库 → 设置 → 分支 中为实际主分支添加保护规则。建议：

禁止普通开发者直接推送到主分支。
禁止强制推送和删除主分支。
要求 PR 至少获得一位其他开发者批准后才能合并。
暂时不要要求自动测试状态通过，除非该仓库已经接入并验证了相应检查。

分支保护是逐仓库配置的；新建仓库不会自动继承其他仓库的保护规则。团队写入权限允许开发者向功能分支推送，主分支保护则约束正式代码的合并。

八、常见问题

看不到仓库？ 确认登录的是自己的账号、仓库属于 BOVETECH，并且仓库已添加到自己所属的团队。私有仓库不会因为账号已创建就自动开放。

推送提示无权限？ 确认仓库 HTTPS 地址、个人账号、访问令牌和团队授权。启用 2FA 后不要用账户密码作为 Git 密码。

推送被拒绝到主分支？ 这是分支保护生效。创建功能分支、推送该分支并通过 PR 合并。

本地已有项目怎么推送？ 先检查目录是否已有 Git 历史和远程地址。不要在有现有提交的项目目录里直接重新 git init，也不要对服务器使用强制推送；遇到远程已有 README 等提交时先拉取并合并历史。