适合 3-5 人小组从零搭建极狐 GitLab 代码仓库、配置成员权限、规范分支协作并处理常见问题。1. 推荐总体方案小组协作优先采用群组 Group └── 项目 Project / 仓库 Repository ├── main稳定主干受保护 ├── feature/xxx功能分支 └── fix/xxx修复分支核心规则所有项目放在同一个小组群组下统一管理。普通成员给 Developer组长或技术负责人给 MaintainerOwner 尽量只保留 1 人。main必须设为受保护分支不允许直接 push。所有人通过个人分支提交代码再发起 MR由 Maintainer 审核合并。敏感信息、私钥、密码、数据库连接串不能提交到仓库。2. 前置准备所有成员先完成以下准备。2.1 注册极狐 GitLab访问https://jihulab.com。使用邮箱注册或按团队要求登录。完成邮箱验证。把自己的极狐用户名或注册邮箱发给管理员方便邀请进群组。2.2 安装 Git下载地址https://git-scm.com/downloads安装后验证git --version2.3 配置 Git 用户信息git config --global user.name 你的名字或极狐用户名 git config --global user.email 你的注册邮箱 git config --global --list建议邮箱和极狐账号邮箱一致方便提交记录关联到个人账号。2.4 配置 SSH 密钥生成密钥ssh-keygen -t ed25519 -C 你的邮箱查看公钥cat ~/.ssh/id_ed25519.pubWindows 也可以直接打开C:\Users\你的用户名\.ssh\id_ed25519.pub把.pub文件里的全部内容复制到极狐 GitLab头像 - 编辑个人资料/设置 - SSH 密钥 - 添加新密钥验证ssh -T gitjihulab.com看到欢迎信息即表示 SSH 可用。注意每个人、每台电脑都应该生成自己的 SSH 密钥。同一个账号可以添加多个公钥不要共用别人的私钥。3. 管理员创建群组入口顶部导航 - 群组 - 新建群组 - 创建群组建议配置配置项建议群组名称小组名或项目名如team-demo群组 URL英文小写、短横线不用中文和空格可见级别私有 Private群组是团队权限和项目的容器。后续新建多个项目时群组成员可以自动继承权限。4. 创建项目仓库入口进入群组 - 新建项目 - 创建空白项目建议配置配置项建议项目名称单项目可与群组同名多项目用模块名项目 URL默认即可可见级别私有 Private默认分支mainREADME 初始化见下方选择README 是否勾选要分情况场景推荐远程新仓库本地还没有任何代码可以勾选 README本地已经有完整代码要推到极狐不要勾选 README避免第一次 push 时历史冲突从 GitHub/Gitee/其他仓库迁移优先用“导入项目”5. 邀请成员和权限分配5.1 群组层邀请推荐用于内部成员入口顶部导航 - 群组 - 进入小组群组 - 左侧 成员/管理成员 - 邀请成员效果加入群组后成员自动拥有群组下所有项目的对应权限。以后新增项目也会继承权限。适用小组内部成员、长期参与项目的人。5.2 项目层邀请适合临时协作入口进入具体项目 - 左侧 项目信息/管理 - 成员 - 邀请成员效果只对当前这个项目生效不会获得群组下其他项目权限。适用外包、跨部门协作、只看单个模块的人。5.3 角色建议角色权限建议人群Owner删除群组/项目、管理所有权限仅组长或项目负责人 1 人Maintainer合并 MR、保护分支、管理项目设置组长、技术负责人Developer创建分支、推送个人分支、发起 MR普通组员Reporter拉取代码、查看 Issue、评论测试、产品、只读成员Guest通常不能看代码只能看部分协作内容极少使用权限叠加规则如果一个人同时在群组和项目里被邀请实际权限通常取更高角色。例如群组是 Developer某项目单独给 Maintainer则该项目里按 Maintainer 处理。6. 本地代码接入方式6.1 方式 A全新项目从远程克隆适合管理员已在极狐建好空仓库或 README 仓库组员拉取到本地开发。cd ~/Projects git clone gitjihulab.com:群组名/项目名.git cd 项目名 git status6.2 方式 B本地全新代码推送到空仓库适合本地刚开始写代码极狐项目是空的。cd 你的项目目录 git init --initial-branchmain git remote add origin gitjihulab.com:群组名/项目名.git git add . git commit -m feat: 初始化项目结构 git push -u origin main6.3 方式 C本地已有代码上传到极狐先确认是否已有旧 Git 历史git status git remote -v如果本地本来就是一个 Git 仓库且历史需要保留不要直接删除.git。优先改远程地址git remote remove origin git remote add origin gitjihulab.com:群组名/项目名.git git push -u origin main只有在明确不需要旧历史、只是想把当前文件作为新项目上传时才考虑重新初始化git init --initial-branchmain git remote add origin gitjihulab.com:群组名/项目名.git git add . git commit -m init: 上传现有项目代码 git push -u origin main7. 标准开发流程小组推荐简化分支模型main稳定主干受保护feature/任务号-功能名新功能fix/任务号-问题名修复 bughotfix/问题名紧急修复7.1 每次开发前同步主干git checkout main git pull origin main7.2 创建个人分支git checkout -b feature/001-login-page7.3 开发并提交git status git add . git commit -m feat: 完成登录页面表单逻辑提交信息建议前缀含义feat:新功能fix:修复 bugdocs:文档变更style:格式调整不影响逻辑refactor:重构test:测试相关chore:构建、依赖、杂项维护7.4 推送分支第一次推送git push -u origin feature/001-login-page后续推送git push7.5 创建 MR入口项目 - 合并请求 - 新建合并请求配置项选择源分支自己的feature/xxx或fix/xxx目标分支main标题简洁说明做了什么描述写明改动内容、影响范围、测试方式Reviewer/Assignee指派 Maintainer 或约定审核人7.6 审核和合并Maintainer 负责查看 Diff。检查是否有无关文件、敏感信息、大文件。确认代码能运行必要时要求 CI 通过。评论问题或要求修改。无问题后合并。合并后删除源分支。7.7 合并后本地清理git checkout main git pull origin main git branch -d feature/001-login-page如果有权限也可以删除远程分支git push origin --delete feature/001-login-page8. 管理员必做保护配置8.1 保护 main 分支入口项目 - 设置 - 仓库 - 受保护分支/保护分支建议配置建议分支main允许推送No one / 无任何人允许合并Maintainer 或 Owner允许强制推送关闭允许删除关闭这样普通成员不能直接 push 到main必须走 MR 审核。8.2 合并请求规则建议开启至少 1 人审核通过后才能合并。有 CI 时流水线通过后才能合并。合并后自动删除源分支。可选合并前压缩提交。8.3 推送规则入口项目 - 设置 - 仓库 - 推送规则建议拦截passwordsecretapi-key.env私钥、证书、数据库连接串推送规则不能替代人工检查但可以挡住一部分低级事故。8.4 CODEOWNERS可选项目根目录新建CODEOWNERS# 所有改动默认由组长审核 * 组长极狐账号 # 前端文件由前端负责人审核 *.vue 前端负责人账号 *.js 前端负责人账号适合多人维护不同模块的项目。9. 可选 CI/CD 配置项目根目录创建.gitlab-ci.yml。Node 项目示例stages: - lint - test - build lint: stage: lint image: node:20 script: - npm ci - npm run lint only: - merge_requests test: stage: test image: node:20 script: - npm ci - npm test only: - merge_requests - main build: stage: build image: node:20 script: - npm ci - npm run build artifacts: paths: - dist/ only: - main自托管极狐 GitLab 可能需要管理员另外配置 GitLab Runner。10. 常见问题和修正建议10.1Permission denied (publickey)排查ssh -T gitjihulab.com git remote -v检查本地是否有id_ed25519和id_ed25519.pub。公钥是否完整粘贴到当前极狐账号。克隆地址是否是 SSHgitjihulab.com:群组名/项目名.git。当前电脑是否使用了正确密钥。说明SSH 密钥后面的邮箱只是备注不是认证核心。认证失败通常是公钥未添加、地址用错、密钥未被 SSH 客户端使用。10.2 HTTPS 每次都要输密码推荐改用 SSH。如果必须用 HTTPS优先使用 Git Credential Manager 或访问令牌不建议长期使用明文保存git config --global credential.helper managercredential.helper store会明文保存凭据只有在明确接受风险时再用。10.3 push 被拒绝Updates were rejected说明远程有本地没有的提交。git pull origin main git push如果当前在功能分支git checkout feature/xxx git fetch origin git merge origin/main git push也可以用 rebase但新手团队先统一用 merge 更稳。10.4 合并冲突git checkout feature/xxx git fetch origin git merge origin/main打开冲突文件处理 HEAD 你的代码 别人的代码 origin/main保留正确内容删除冲突标记然后git add . git commit git push10.5 撤销已经 push 的提交共享分支上优先用revertgit revert HEAD git push注意git revert不是“保留改动到工作区”而是新建一个反向提交来撤销历史提交。它适合已经推送到远程、多人协作的场景。如果提交还没 push只是想撤回最近一次 commit 并保留文件改动git reset --soft HEAD~1共享分支不要随便reset --hard或push -f。10.6 误提交敏感信息第一时间处理立刻让相关密钥、密码、Token 失效并重新生成。如果只是当前 MR删除敏感内容并追加修复提交。如果敏感信息已经进入主干历史需要使用专门工具清理历史并通知所有成员重新同步。不要只删除文件就以为安全因为 Git 历史里仍可能保留旧内容。10.7 组员看不到仓库或克隆 403管理员检查是否邀请到了正确账号。是否在群组层或项目层给了权限。角色是否至少 Developer。项目是否在对应群组下。项目可见级别是否为私有但成员未加入。10.8 不要滥用删除.git删除.git会丢失本地 Git 历史、分支、提交记录和远程配置。只有在确认旧历史完全不需要时才删除。一般情况下先用git remote -v git remote set-url origin gitjihulab.com:群组名/项目名.git11. 小组硬性规范权限规范普通成员统一 Developer。组长或技术负责人 Maintainer。Owner 尽量只保留项目负责人。离职或退出项目的成员从群组成员里移除。临时外部人员只在项目层邀请并设置到期时间。分支规范禁止直接在main开发。禁止直接 push 到main。分支名用英文、数字、短横线。推荐格式feature/任务号-功能名、fix/任务号-问题名。合并前同步main提前解决冲突。MR 规范一个 MR 只做一件事。MR 描述写明改了什么、为什么改、如何测试。不要一次提交几十个无关文件。MR 必须审核后合并。合并后删除源分支。安全规范不提交.env。不提交私钥、证书、密码、Token、数据库连接串。大文件、安装包、视频等不要直接进 Git 仓库。仓库默认保持私有。重要项目定期导出备份。12. 常用命令速查# 查看状态 git status # 拉取 main 最新代码 git checkout main git pull origin main # 新建并切换分支 git checkout -b feature/xxx # 切换分支 git checkout main # 查看本地分支 git branch # 查看远程分支 git branch -r # 添加修改 git add . # 提交 git commit -m feat: 描述本次改动 # 第一次推送新分支 git push -u origin feature/xxx # 后续推送 git push # 获取远程分支信息 git fetch origin # 切换到别人远程分支 git checkout -b feature/other-person-work origin/feature/other-person-work # 合并 main 到当前分支 git merge origin/main # 删除本地已合并分支 git branch -d feature/xxx # 删除远程分支 git push origin --delete feature/xxx # 撤销共享分支上的最近提交 git revert HEAD # 撤销本地未提交改动慎用 git checkout -- .13. 给组员的最短执行版每天开发只记住这套流程git checkout main git pull origin main git checkout -b feature/任务号-功能名 # 写代码 git add . git commit -m feat: 说明本次功能 git push -u origin feature/任务号-功能名然后到极狐 GitLab 页面创建 MR源分支自己的 feature/fix 分支目标分支main指派审核人组长或 Maintainer审核通过合并后git checkout main git pull origin main git branch -d feature/任务号-功能名