1. 开篇拆解一个 GitLab 新项目到底要“传”什么平时总能遇到这样的场景本地代码已经写了一千多行功能结构也都调通了可下一步“把项目传到 GitLab”这关却卡了整整一个下午。页面能找到按钮却找不到命令行一跑全是报错好不容易推上去了同事又说拉不下来。问题的根源在于大家把“上传”理解得太简单了以为把文件从本地搬到远端就结束。可 GitLab 新项目上传流程真正的价值是让本地代码变成一个有版本历史的仓库让团队协作有一个唯一的起点。这篇内容我会从 GitLab 的创建入口开始把初始化、身份配置、权限分配、分支保护、合并请求一路讲到错推分支、误删代码等常见事故的恢复思路帮你把这些环节一次串起来。我先说一个最常见的误区很多人以为“新项目上传”就是到网页端点几下“上传文件”的按钮。这种方式处理临时文件、文档还行但对真正的代码仓库来说完全不够。代码仓库必须有完整的提交历史有明确的分支概念有谁能读、谁能写的权限边界还要有代码评审的入口。只是把文件拖进网页等于把版本管理、协作能力全部丢掉了后患无穷。与其说是“上传”不如说是“让本地代码和 GitLab 仓库建立一套可协作的关系”。这套关系包含三件事代码本身进去了并且保留了提交历史团队成员拿到权限后能各自拉取、提交、评审保护策略、分支策略能让主干保持稳定避免互相踩踏。1.1 项目、仓库、组之间的关系在 GitLab 里“项目”不是简单的文件夹它是一个包含代码仓库、问题列表、合并请求、CI/CD 配置、文档 Wiki 的容器。代码仓库只是其中一部分但通常也是最重要的一部分。项目要挂在某个命名空间下面。命名空间分两种用户命名空间和组命名空间。你自己新建的项目会放在个人名下的命名空间里团队项目则一般放在“组”下面。组的作用非常大。组可以统一管理成员、统一配置权限组下面还能再分子组比如“前端组”“后端组”每个组下挂对应项目。用组的思路来组织项目团队加人、调权限会省非常多事而不是一个个项目单独去配成员。我见过一些团队操作项目一开始建在个人名下等某位同事离职代码访问权限就变得很被动。最稳妥的做法是凡是多人协作的项目一律在组下创建用组来承载成员关系项目本身不绑定个人。1.2 三种常见初始化方式的选择GitLab 新建项目的入口提供几个不同路径很多人没仔细区分导致选错。常见的是这三种第一种是“创建空白项目”。适合本地代码已经写好的情况。你只需要在网页上先把空白项目建好然后本地推代码过去。这个方式最推荐因为流程干净你可以在本地控制初始提交内容和分支名。第二种是“从模板创建”。GitLab 自带一些项目模板比如 Spring Boot、Ruby on Rails、Vue 等。如果你是从零开始、又不想手动搭架子模板确实能节省时间。但要注意模板里的依赖版本更新未必及时生成之后还是需要自己调整。第三种是“导入项目”。这适合把旧仓库迁移过来可以填写旧仓库的 URL 直接拉取也可以从其他平台迁移。这里有个细节如果原仓库非常大导入很耗时而且路径变更后依赖关系可能断裂。迁移前最好在团队内部确认好原仓库的下载权限和依赖。选哪条路取决于你此刻手里有没有代码。手里有代码就选第一种手里什么也没有模板才值得考虑已有旧仓库才选导入。别反过来。1.3 开工前的环境自查清单真正动手之前先花几分钟做一个环境自查。很多上传失败的现场问题根本不在于操作错而在于环境里缺少组件。首先确认 Git 有没有安装。在终端执行git version如果提示找不到命令说明 Git 客户端还没装好。Windows 用户可以直接安装官方 Git for WindowsmacOS 用户如果装了 Homebrew执行brew install git也很方便Linux 用户用发行版自带的包管理器安装即可。其次确认网络。浏览器能打开 GitLab 网页并不代表命令行一定能连上。用ping只能测基本连通性对 GitLab 实例来说更值得测试的是 HTTPS 端口因为很多公司内网或云服务器会限制出站端口。如果命令行推送超时优先检查端口开放情况。最后确认认证材料。GitLab 新版默认已经不推荐用账号密码直接走 HTTPS 提交而是要求使用个人访问令牌或者配置 SSH 密钥。这两样东西如果还没准备后面推送时一定会卡住。我建议动手前就准备好“用哪种认证方式”避免推送到一半临时换方案。2. 服务端准备创建项目与团队成员配置2.1 创建空白项目时的五个关键选项进入 GitLab 首页点击“新建项目”然后选择“创建空白项目”会看到几个关键配置项。每一项都有讲究不要一路默认点下去。第一是项目名称。建议用能表达业务含义的短名称比如user-service、web-frontend尽量避免中文、空格和大小写混乱。项目名会成为仓库路径的一部分改起来很麻烦命名时想清楚。第二是项目 URL 和命名空间。这一步实际上决定项目挂在哪个组下。如果你还没有组可以顺手新建一个。组名建议与团队名一致比如backend、platform。第三是可见性设置。私有项目只有被授权的成员能看到内部项目表示登录用户能看到但没权限不能推送公开项目任何人都能看。团队内部项目默认选“私有”最稳妥。对外开源项目才需要选“公开”。内部项目这个选项在云端 GitLab 某些套餐里已经逐步弱化私有和公开基本够用。第四是“使用 README 初始化仓库”。这个选项需要特别留意。如果你本地已经有代码千万不要勾选。一旦勾选GitLab 就会在远程生成一个带有 README 提交的默认分支。本地推代码时两边都有各自的历史就会产生两个不相关的仓库需要处理合并冲突非常麻烦。2.2 可见性等级到底在保护什么可见性很多人理解成“能不能看代码”其实还有更深一层影响。公开项目意味着代码、问题列表、合并请求全部对外可见甚至包括某些 CI 配置。CI 配置里如果有敏感环境变量名字哪怕值被隐藏也可能被有心人利用。我建议团队内部对外项目一律按“内部或私有”处理。如果实在需要公开也要默认把问题和 Wiki 关掉再检查一下代码里是否含有密码、密钥、内网地址。这个动作必须形成习惯养成“上传之前先扫一遍敏感信息”的条件反射。2.3 GitLab 权限角色速查创建好项目之后下一步就是把团队成员加进来。GitLab 的权限体系分成几个等级每个等级能做的事情差别很大。从低到高大概是访客、报告者、开发者、维护者、所有者。访客只能看问题列表、评论看不到代码仓库内容报告者可以拉代码、看代码但不能推送适合需要读代码做审计或测试的角色开发者是最常见的日常角色能推送分支、创建合并请求但在受保护分支上不能直接推维护者可以管理合并请求、修改受保护分支也能调整项目设置但删除项目、转移项目这类操作仍然只有所有者能做所有者是最高权限掌握项目的生死。表格看起来很简单但实际分配时经常出问题。比如给实习生开了维护者权限他就能直接往主干分支推代码这会让代码评审形同虚设。提示默认情况下新建项目的默认分支是受保护的。开发者角色不能直接推送到该分支只能通过合并请求合入。这个保护机制是 GitLab 给你兜底的一道安全网不建议为了图方便而关闭。给成员分配角色时遵循“最小权限”原则。日常开发给开发者角色就够需要管合并、管分支才给维护者所有者权限尽量控制在项目负责人手里。3. 本地推送从 Git 初始化到第一行远程代码3.1 本地 Git 身份与常用配置服务端准备好了本地的工作才是重头戏。打开终端进入项目根目录先确认两件事身份信息和默认分支名。身份信息用两个配置项控制user.name和user.email。它们会写进每次提交的记录里。很多人推送成功之后却发现 GitLab 上贡献者列表是空的或者头像对不上就是因为本地user.email和 GitLab 账号对不上。建议设置提交邮箱与 GitLab 注册邮箱保持一致这样提交记录才能正确关联到账号。还有一点要提醒邮箱配置有全局和局部两个层级。git config --global是全局配置影响这台机器上所有仓库git config --local只影响当前仓库。如果你同时维护多个账号建议在当前仓库里单独配置局部邮箱避免把个人邮箱提交进公司项目。3.2 初始化分支与首次提交确认身份后开始初始化仓库。Git 从早期版本开始默认分支名一直在从master向main迁移。GitLab 新建的空白项目默认分支也是main。为了让本地和远程保持一致建议先在本地把默认分支设为main。如果你用的是旧版 Git默认分支可能还是master。不用慌在项目目录下执行git init -b main可以指定初始分支名为main。如果已经初始化了也可以用git branch -M main把主分支重命名。然后是提交。很多人第一次提交时习惯git add .把全部文件塞进去这并不可取。先看一眼项目里有没有不该提交的文件比如 IDE 配置、依赖包目录、本地环境变量、日志文件。提前准备好.gitignore再执行git add .这样提交进去的才是干净内容。提交信息也值得规范。常见团队约定是类型(模块): 描述这种格式。比如feat(user): 新增登录接口、fix(cart): 修复数量计算错误。好处是后续看提交历史能快速定位变更意图也能和 GitLab 的问题编号关联。3.3 绑定远程仓库并推送本地提交完成之后就要把远程仓库和本地仓库关联起来。回到 GitLab 项目页面右侧会有克隆地址通常是 HTTPS 或 SSH 两种形式。复制下来在本地执行git remote add origin https://gitlab.example.com/group/project.git添加远程之后可以执行git remote -v检查远程地址是否正确。项目创建时如果误勾选了初始化 README本地会多出一个需要处理的步骤后面排错部分单独说。推送的命令是git push -u origin main-u参数的作用是设置上游分支。设置之后后面再执行git push或者git pull时Git 会自动知道和哪个远程分支对应不需要每次重复写origin main。3.4 HTTPS 与 SSH 两种认证方式怎么选推送时最常遇到的坎就是认证。GitLab 支持两种主流认证方式各有适用场景。HTTPS 方式使用地址栏里的 https 链接。早期需要填账号密码但 GitLab 全面推行个人访问令牌后密码字段需要填令牌而不再是登录密码。令牌在 GitLab 的“偏好设置 - 访问令牌”里创建创建时给read_repository和write_repository权限即可。令牌相当于一把有期限、有范围的钥匙比密码安全得多。SSH 方式则需要生成密钥对。本地执行ssh-keygen -t ed25519 -C your_emailexample.com生成的公钥通常是~/.ssh/id_ed25519.pub把公钥内容复制到 GitLab 的“SSH 密钥”设置页面。之后项目的远程地址也用 SSH 形式也就是以git开头的那个。我个人的习惯是长期维护的仓库用 SSH临时提交或一次性脚本用 HTTPS 令牌。SSH 配置好之后一劳永逸但换电脑、换密钥时要重新配置HTTPS 令牌则适合轻量使用场景过期了重新生成一个就好。注意如果你开启了 GitLab 的两步验证HTTPS 提交时账号密码里的“密码”几乎可以肯定是走不通的必须使用访问令牌。很多人卡在这一步好几天最后发现只是没分清“登录密码”和“访问令牌”。4. 从单人推送到团队协作4.1 用分支策略约束“谁能往哪推”代码推到远端只是协作的第一步。多人协作真正要做的是把主干分支保护起来让日常开发在功能分支上进行。比较流行的做法是主干分支只保留可发布的稳定版本开发人员基于主干拉取功能分支。比如某同事要开发一个登录功能他会先git pull origin main更新本地再执行git checkout -b feature/user-login功能开发完推送到远程git push -u origin feature/user-login然后到 GitLab 上发起合并请求代码评审通过后合入主干。这个流程把写代码和合入主干分开评审过不了就不允许改动主干这样可以避免很多低级错误。4.2 Merge Request 到底在管什么合并请求GitLab 里叫 Merge Request简称 MR。它不只是一种代码合并工具更是团队沟通的载体。MR 里可以设置源分支和目标分支。源分支是功能分支目标分支通常是 main。创建 MR 时GitLab 会自动计算两个分支之间的差异显示变更文件、提交记录还能自动检测是否有冲突。多人协作时MR 还有几个重要功能值得利用代码评审人员可以在 MR 里逐行评论可以直接点赞、提出修改意见MR 可以关联问题列表里的议题比如输入Closes #123合入时自动关闭对应的 issue合并时可以选“压缩提交”把功能分支上零碎的提交整理成一个干净提交保持主干历史的整洁。我建议团队给 MR 设置一个硬性门槛必须至少有一人评审过才能合并且只有维护者能最终合入。这能确保代码不仅可运行还有人认真看过。4.3 组与项目的关系团队管理的最终形态当团队人数多起来几种规范就变得非常必要统一的组结构、统一的项目前缀、统一的分支命名规范。比如后端组下面是user-service、order-service等多个项目新同事入职时管理员只需要把新同事加入backend这个组并赋予开发者角色他就能访问组下所有项目了。离职时也一样从组里移除成员即可不需要逐个项目手动处理。分支命名也可以做统一约定比如功能分支用feature/开头修复分支用fix/开头版本发布用release/开头。这样在合并请求列表里只看分支名就能知道变更目的。5. 高频踩坑与排查手册5.1 认证类故障我遇到过最多的一类问题就是“Authentication failed”或者“Permission denied”。如果是 HTTPS 方式请检查是不是用了登录密码而不是访问令牌。GitLab 开启两步验证后只要是新版行为登录密码是不可能直接用于 Git 操作的。还需要检查令牌权限是否漏勾了write_repository。只有读权限没有写权限推送也会被拒。如果是 SSH 方式执行ssh -T gitgitlab.example.com测试连接。如果提示权限不足先确认公钥是否粘贴完整公钥文件的结尾换行有没有丢再确认本地是否使用了正确的私钥有时候系统里配置了多个密钥Git 会选择错误的那个。可以在~/.ssh/config里为 GitLab 主机指定IdentityFile这样能强制使用指定私钥。还有一类是代理问题有些环境变量里配置了 HTTP 代理。命令行操作时如果 Git 走了不存在的代理就会连接超时或报 SSL 错误。排查时检查环境变量http_proxy、https_proxy确认不需要代理就直接清掉。5.2 push 被拒绝类故障第二种高频问题是执行git push时被拒绝提示Updates were rejected。这种报错通常有不同深层原因要看具体日志。最常见的情况是远程分支上有本地没有的提交。比如本地创建项目时勾选了 README远程仓库已经有一次提交本地仓库则是从空仓库开始的另一条历史线两条历史没有共同祖先。解决办法是先把远程历史拉下来并合并git pull origin main --allow-unrelated-histories git push -u origin main这个命令要谨慎--allow-unrelated-histories会强制把两段不相干的历史合并在一起。如果两边都有同名文件会冒出很多冲突。所以我还是坚持建议本地已有代码时创建项目不要勾选 README。另一种被拒绝原因是受保护分支直接推送。团队里如果开启了主干保护任何直接 push 到 main 的尝试都会被拒绝。正确做法是新建分支、发起 MR。5.3 仓库体积与误提交大文件问题仓库越来越大是后面必然遇到的问题。Git 对单个文件的大小有限制某些托管源会限制单次提交大小。比如把 100MB 以上的数据集直接提交往往会被拒绝。遇到这种情况要看文件是不是应该进入版本管理。如果只是临时产物应该从提交中删掉并加入.gitignore。如果是必须保留的大文件比如设计稿、模型文件建议用 Git LFS 来管理。GitLab 对 LFS 有原生支持会把大文件替换成指针存储仓库体积不会膨胀。更麻烦的是把大文件提交后想从历史里删除。可以用git filter-repo或 BFG 这类工具清理提交历史。但这类操作会重写历史如果分支已经分享给多人会让其他人本地仓库全部失配操作前必须和团队确认时间窗口。5.4 我最想提醒的三个小习惯最后分享三个我踩过坑之后沉淀下来的习惯不复杂但确实帮我避开过很多问题。第一个习惯是提交前必看git status。有时候你以为只改了一个文件结果发现还混入了临时文件和密钥文件全靠这一步检查兜住。第二个习惯是坚持给提交信息分类前缀并且和问题编号关联。一个团队如果提交信息乱七八糟后面做版本回溯、写发布说明时就是灾难。提交信息不是写给 Git 看的是写给三个月后的自己看的。第三个习惯是每次换电脑或换工作目录后先做一次拉取确认再开始写代码。很多时候所谓“代码在我电脑上是好的”其实是因为本地代码已经落后远程好几个版本。确保本地基于远程最新代码操作能规避大量合并冲突。对我来说GitLab 新项目上传这件事本质上是把一个人的工作习惯扩展成一群人的协作纪律。第一次可能会慌会踩坑但只要把创建、推送、权限、分支、评审这几环理顺后面就会变得非常顺。希望这篇实录能帮你少花几个下午在那对着一堆英文报错发呆。