1. 项目概述与核心价值
最近在团队内部做了一次关于代码仓库管理的分享，发现很多新同事，甚至一些有经验的开发者，对于GitLab这个强大的DevOps平台的使用，还停留在最基础的git clone和git push阶段。这让我意识到，一个清晰、规范的GitLab使用起点，远比我们想象的要重要。很多人上手就急着提交代码，却忽略了项目仓库和群组的设计，这就像盖楼不打地基，后期随着团队扩张、项目增多，权限混乱、仓库命名五花八门、代码归属不清等问题会接踵而至，再想调整就伤筋动骨了。
所以，这篇笔记我想从一个更根本的层面开始聊：如何从零开始，在GitLab上建立一个清晰、可扩展、易于管理的项目结构。这不仅仅是创建一个仓库那么简单，它涉及到团队协作的顶层设计。一个设计良好的群组和项目仓库结构，能极大地提升代码复用率、简化权限管理、并让CI/CD流水线的配置变得清晰明了。无论你是个人开发者管理自己的多个小项目，还是团队负责人需要规划整个部门的代码资产，这套思路都值得你花时间思考。接下来，我会结合我踩过的坑和总结的最佳实践，带你一步步完成这个“打地基”的过程。
2. 核心思路：为什么群组设计要先行于创建仓库？
在动手点击“New project”按钮之前，我强烈建议你先停下来，思考一下群组（Group）的结构。这是很多新手，甚至一些中小团队最容易忽视的一步。大家习惯于直接创建项目，结果就是所有项目都堆在个人或公司命名空间下，看起来一片混乱。
2.1 群组的核心价值：隔离与授权
你可以把GitLab的群组理解为一个“文件夹”或者“部门”。它的核心价值在于两点：资源隔离和权限批量管理。
首先说资源隔离。假设你们公司同时在进行“电商平台”和“内部OA系统”两个大项目。如果把所有前端、后端、移动端的仓库都混在一起，找起来非常困难。更合理的做法是创建两个顶级群组，比如ecommerce和internal-oa。这样，所有相关的子项目、子模块都能归属到对应的群组下，结构一目了然。
其次是权限批量管理，这是群组最大的优势。你可以在群组级别设置成员角色（Owner, Maintainer, Developer, Reporter, Guest），那么这个权限会自动继承给该群组下的所有项目。例如，你把新同事张三添加到ecommerce群组并赋予Developer角色，那么他立即就拥有了该群组下所有仓库的推送权限。后续这个群组新增任何项目，张三的权限也会自动同步，无需逐个仓库去添加。这极大地减少了权限维护的复杂度。
注意：权限继承是GitLab群组的一大特色，但也需要谨慎规划。如果一个成员只需要访问某个特定项目，就不应该把他放在上级群组，而应直接添加到项目成员中，遵循“最小权限原则”。
2.2 常见的群组结构模式
根据团队规模和项目复杂度，我实践过几种不同的群组结构模式：
- 按业务线/产品划分：这是最常见也最推荐的方式。例如：
group-web-app,group-mobile-app,group-backend-services。每个业务线群组下，再按项目或微服务创建子群组或直接创建项目。 - 按团队/部门划分：例如：
team-frontend,team-backend,team-data-science。这种模式适合横向技术团队，方便技术栈相同的成员共享代码和工具库。 - 混合模式：大型组织通常会混合使用。先按业务线创建顶级群组，在业务线内部，再为不同的功能模块或微服务创建子群组。
我的经验是，对于初创团队或中小型项目，直接采用“按业务线划分”就足够了，结构简单明了。随着项目微服务化，可以在业务线群组下创建子群组来对应不同的服务。
2.3 项目仓库的命名规范
确定了群组结构，接下来就要考虑仓库命名了。一个糟糕的仓库名，如test,project-new,backend_v2_final，会带来长期的维护成本。我遵循的命名规范是：简短、达意、使用小写和连字符。
- 简短达意：名字应该能清晰表达项目内容。例如，一个用户服务，叫
user-service就比service1好得多。 - 统一风格：全团队使用一种命名风格。我推荐全小写，单词间用连字符（
-）分隔，例如payment-gateway,frontend-admin。这符合大多数URL和文件系统的惯例。 - 避免冗余：既然项目已经归属于某个群组，仓库名就无需再包含群组信息。例如，在
ecommerce群组下，仓库直接叫order-service即可，而不是ecommerce-order-service。
3. 实操：从零开始建立群组与项目仓库
理论说完了，我们进入实战环节。这里我会以创建一个名为“在线商城”（ecommerce）的业务线为例，演示完整流程。
3.1 第一步：创建顶级业务群组
登录GitLab后，点击导航栏左上角的“菜单”图标，找到“群组” -> “查看所有群组”，然后点击“新建群组”。
- 群组路径：这是最重要的字段，会体现在URL中。我们填写
ecommerce。GitLab会自动生成对应的群组URL。 - 群组名称：填写一个更易读的名称，如
E-Commerce Platform。 - 群组描述：简要描述这个群组的用途，例如“所有与在线商城业务相关的项目与代码仓库”。良好的描述有助于新成员快速理解。
- 可见性级别：这是关键安全设置。
- 私有：只有被明确授予权限的成员才能看到。对于绝大多数公司项目，请务必选择“私有”。
- 内部：所有登录用户可见（如果GitLab实例是企业内网部署，这个选项很有用）。
- 公开：互联网上任何人都可以查看（仅适用于开源项目）。
- 权限配置：在创建时，你可以直接添加成员并分配角色。这里我们可以先跳过，创建完成后再进行精细配置。
点击“创建群组”，我们的第一个容器就建好了。
3.2 第二步：在群组内创建第一个项目仓库
进入刚创建的ecommerce群组页面，你会看到一个大大的“新建项目”按钮。
这里有三种创建方式，我逐一分析：
- 创建空白项目：最常用的方式，从一个空的Git仓库开始。
- 从模板创建：GitLab提供了一些项目模板（如Spring Boot, NodeJS Express等），可以快速生成基础代码结构。对于需要快速原型验证的场景很方便。
- 导入项目：可以从GitHub、Bitbucket等其他平台导入，或者通过URL导入。
我们选择“创建空白项目”。
- 项目名称：我们创建一个订单服务，命名为
order-service。注意，项目创建路径会自动补全为ecommerce/order-service，这清晰地表明了归属关系。 - 项目描述：（可选但推荐）填写“商城订单处理核心微服务”。
- 可见性级别：同样，选择“私有”。项目会继承群组的可见性设置，但也可以单独覆盖。通常保持与群组一致即可。
- 初始化仓库：务必勾选“使用自述文件初始化仓库”。这个操作会自动生成一个
README.md文件并创建main（或master）分支。一个带有README的空仓库，比一个完全空的仓库更规范，也方便你立刻开始编写文档。
点击“创建项目”，你的第一个结构清晰的项目仓库就诞生了。它的完整路径是gitlab.yourcompany.com/ecommerce/order-service。
3.3 第三步：配置项目基础信息与保护分支
项目创建后，先别急着写代码。有几个关键设置需要立刻配置，它们关乎协作规范。
3.3.1 设置默认分支
进入项目，点击左侧边栏“设置” -> “仓库”，展开“默认分支”选项。 现在主流都已从master迁移到main。确保你的默认分支名是main。如果显示为master，你可以在这里修改。统一的默认分支名有利于脚本和自动化工具的编写。
3.3.2 配置保护分支规则
这是保证代码质量的关键防线。点击“设置” -> “仓库”，再展开“保护分支”选项。 你需要保护main分支（以及可能存在的production,release/*等分支）。
- 允许推送：设置为“维护者”。这意味着只有Maintainer及以上角色的人可以直接推送到
main分支。 - 允许合并：设置为“开发者和维护者”。这是最常见的设置，允许Developer角色的人创建合并请求（Merge Request）。
- 允许强制推送：永远不要勾选。强制推送会重写历史，是团队协作的灾难。
- 允许解除保护：仅限管理员。
这样配置后，所有对main分支的修改都必须通过合并请求（MR）来完成，从而天然引入了代码评审环节。
3.3.3 完善README.md文件
一个优秀的README是项目的门面。点击项目根目录的README.md文件，然后点击编辑。至少应该包含以下章节：
- 项目简介：这个项目是做什么的？
- 技术栈：使用了哪些语言、框架和主要库？
- 快速开始：如何下载、配置、运行本项目？（提供命令示例）
- 构建与部署：如何构建、测试、部署？
- 贡献指南：如何为该项目贡献代码？（可以链接到更详细的CONTRIBUTING.md）
4. 高级群组设计与权限管理实战
当你的项目规模增长，简单的单层群组可能不够用了。这时就需要引入子群组（Subgroup）和更精细的权限模型。
4.1 创建与使用子群组
假设我们的ecommerce商城非常复杂，分为前台用户端和后台管理端，并且每个端都有独立的移动App。我们可以在ecommerce下创建子群组来管理。
在ecommerce群组页面，点击“子群组”标签页，然后点击“新建子群组”。创建过程与创建顶级群组类似。
- 我们可以创建
ecommerce/frontend来管理所有Web前端项目。 - 创建
ecommerce/backend来管理所有后端微服务。 - 在
backend下，甚至可以再创建backend/user-service,backend/order-service等子群组，每个子群组只包含一个服务的相关仓库（如服务代码、配置库、部署脚本等）。
这种嵌套结构的好处是权限可以层层继承。给一个开发者backend子群组的Developer权限，他就能访问其下所有服务和子群组。
4.2 理解与配置成员角色
GitLab提供了五个预定义角色，权限从高到低：Owner > Maintainer > Developer > Reporter > Guest。理解每个角色的权限边界至关重要。
| 角色 | 在群组中的典型权限 | 在项目中的典型权限 | 适用人员 |
|---|---|---|---|
| Guest | 查看群组和项目 | 查看项目、议题、留言 | 客户、外部顾问 |
| Reporter | Guest权限 + 查看分析 | 查看 + 创建议题、留言 | 测试人员、产品经理 |
| Developer | Reporter权限 | 核心协作角色：可推送分支、创建MR、接受MR（若被授权）、运行CI/CD | 开发工程师 |
| Maintainer | Developer权限 + 管理项目、添加成员 | 项目管理角色：可推送保护分支、管理MR、管理CI/CD变量、管理部署密钥 | 技术负责人、核心开发者 |
| Owner | Maintainer权限 + 管理群组、删除群组 | 项目最高权限，可删除项目 | 部门负责人、系统管理员 |
实操心得：不要随意分配高权限。一个常见的反模式是给所有资深开发Maintainer角色。实际上，大多数日常开发工作，Developer角色完全足够。Maintainer应该只给那些需要管理项目设置（如保护分支、CI/CD变量）或负责发布的人。Owner权限更要严格控制。
4.3 使用“项目访问令牌”替代个人账号进行自动化
这是很多团队会踩的坑。当你的CI/CD流水线（如GitLab Runner）需要拉取代码、推送标签，或者外部系统（如部署平台）需要集成GitLab API时，不应该使用某个真实开发者的个人访问令牌。
正确做法是使用“项目访问令牌”或“群组访问令牌”。
以创建项目访问令牌为例：
- 进入项目，点击“设置” -> “访问令牌”。
- 点击“添加新令牌”。
- 输入令牌名称，如
gitlab-ci-deploy-token。 - 选择过期日期（建议设置一个合理的有效期，如一年）。
- 谨慎选择作用域：根据最小权限原则勾选。如果只是用于CI/CD拉取代码，勾选
read_repository即可；如果需要推送标签，则需勾选write_repository。 - 点击“创建”，务必立即复制并安全保存生成的令牌，因为它只显示一次。
这个令牌可以像密码一样被配置到CI/CD的环境变量（Settings -> CI/CD -> Variables）中，供流水线脚本安全使用。
5. 本地开发环境初始化与首次推送
群组和仓库在云端建好了，现在我们要在本地电脑上建立连接，开始真正的开发工作。
5.1 配置SSH密钥（推荐方式）
使用SSH协议比HTTPS更安全、更方便（无需每次输入密码）。
生成密钥对（如果你还没有）：
ssh-keygen -t ed25519 -C "your.email@example.com"按提示回车，使用默认路径（
~/.ssh/id_ed25519）。建议为密钥设置一个强密码（passphrase）以增加安全性。将公钥添加到GitLab：
- 复制公钥内容：
cat ~/.ssh/id_ed25519.pub - 登录GitLab，点击右上角头像 -> “编辑个人资料” -> “SSH密钥”。
- 将复制的公钥粘贴进去，标题会自动生成，点击“添加密钥”。
- 复制公钥内容：
测试连接：
ssh -T git@gitlab.yourcompany.com如果看到“Welcome to GitLab, @your-username!”，说明配置成功。
5.2 克隆项目到本地并完成首次提交
回到我们刚创建的ecommerce/order-service项目页面，找到“克隆”按钮，选择“使用SSH克隆”的地址，它长这样：git@gitlab.yourcompany.com:ecommerce/order-service.git。
在本地终端执行：
git clone git@gitlab.yourcompany.com:ecommerce/order-service.git cd order-service现在，你可以开始开发了。假设我们添加了一个简单的服务类：
# 创建文件 echo 'package com.ecommerce.order; public class OrderService { public String createOrder() { return "Order created!"; } }' > src/main/java/com/ecommerce/order/OrderService.java # 将文件添加到暂存区 git add src/main/java/com/ecommerce/order/OrderService.java # 提交到本地仓库 git commit -m "feat: add initial OrderService class" # 推送到远程仓库 git push origin main如果你的main分支是受保护的，并且你的角色是Developer，这步git push origin main会失败。这正是我们想要的效果——强制通过合并请求来协作。
5.3 创建第一个合并请求（Merge Request）
由于不能直接推送，我们需要遵循GitLab Flow的标准协作流程：
创建并切换到一个新功能分支：
git checkout -b feature/add-order-service在新分支上开发并提交（假设我们修改了README）：
git add README.md git commit -m "docs: update README with setup instructions" git push origin feature/add-order-service这条命令会在远程仓库创建一个同名分支。
在GitLab上创建合并请求：
- 推送后，GitLab页面通常会弹出一个提示，让你“创建合并请求”，点击它。
- 或者，在项目页面点击“合并请求” -> “新建合并请求”。
- 选择源分支
feature/add-order-service和目标分支main。 - 填写一个有意义的标题和描述。描述里尽可能写清楚改动内容、原因以及测试方法，方便评审人理解。
- 指派评审人（通常是团队的主维护者或相关同事）。
- 点击“创建合并请求”。
代码评审与合并：
- 被指派的评审人会在MR页面查看代码变更，提出评论或建议。
- 开发者根据反馈在本地分支修改，然后再次推送，MR会自动更新。
- 所有讨论解决后，评审人点击“合并”按钮。
- 合并后，可以勾选“删除源分支”，以保持仓库分支的整洁。
至此，你已经完成了一个从群组设计、项目创建、权限配置到本地开发、代码提交、合并请求的完整闭环。这套流程是GitLab协作的基石，熟练掌握后，团队的开发效率会得到质的提升。记住，好的开始是成功的一半，在项目初期花时间设计好仓库结构，未来你会感谢自己。
