GitLab 是什么：如何配合 Git 使用，clone、push、merge request、CI/CD

GitLab 是什么

GitLab 是一个平台，用来存放 Git 仓库，并围绕它组织团队协作：代码浏览、merge request（合并请求）、任务、wiki、容器镜像仓库以及内置的 CI/CD。简单地说，GitLab 就是「带有自己构建流水线、并且可以部署到自己服务器上的 GitHub」。许多公司，尤其是在中国，把代码保存在部署于内网的 GitLab 中。

该项目于 2011 年作为开源代码托管应用启动，之后围绕它发展出了 GitLab 公司。这个平台有两个版本：Community Edition 是开源版，可以免费安装在自己的服务器上；Enterprise Edition 则包含付费功能。在 gitlab.com 云端，套餐分为 Free、Premium 和 Ultimate。

要注意区分这些概念。Git 是版本控制系统，是运行在你电脑上的程序。GitLab 是一项服务，负责保存远程仓库的副本，并为团队提供界面和工具。没有 Git 就无法使用 GitLab，而 Git 完全可以脱离 GitLab 独立工作。

Git 与 GitLab 有什么区别

人们搜索「git 和 gitlab 是什么」，通常是因为在招聘信息或第一天上班时，同时遇到了这两个词。两者的区别就像文档与云盘：Git 跟踪文件的修改，在本地保存提交历史和分支；GitLab 则通过网络接收这份历史，并在浏览器中展示出来。

所有与代码相关的操作，例如 commit、branch、merge，你仍然在 Git 中完成。GitLab 只是通过 git push 接收结果，并让你与同事讨论它。

GitLab 与 GitHub 有什么不同

两个服务都存放 Git 仓库，并支持代码评审，因此基本技能可以直接迁移。区别主要在侧重点和部署方式上。

在实际工作中，开发者经常两者都用：个人项目和作品集放在 GitHub，工作代码放在企业的 GitLab 中。Git 命令完全相同，只是远程仓库的地址不同。

gitlab.com 还是自建服务器（self-hosted）

云端的 gitlab.com 适合个人项目和小团队：注册后立即就能创建仓库。更新、备份和可用性都由 GitLab 负责。免费套餐的限制（成员数量、CI 分钟数、存储空间）会不时调整，请以套餐页面的最新信息为准。

自建 GitLab 由公司部署在自己的服务器上，可以使用 Linux 安装包、Docker 或 Kubernetes。代码不会离开内网，可以接入企业的 LDAP 登录，也可以配置自己的 runner 来执行构建。代价是管理员需要自己负责更新和备份。对于开发者来说，两者的差别几乎感觉不到：地址不再是 gitlab.com，而是比如 gitlab.company.ru 之类。

配置 Git 以使用 GitLab

在第一次提交之前，先设置用户名和邮箱。它们会写入历史记录，GitLab 会根据邮箱把提交关联到你的个人资料：

git config --global user.name "张伟"
git config --global user.email "zhang@example.com"

在 Windows 上，建议使用 Git Bash：它随 Git for Windows 一起安装，并包含 ssh-keygen，因此本文中的所有命令都可以直接在其中运行。接下来需要选择登录方式：使用令牌的 HTTPS，还是 SSH 密钥。

通过 HTTPS 登录：personal access token

通过 HTTPS 进行 Git 操作时不应使用账号密码，而且开启双因素认证后密码也无法通过。请在 GitLab 个人设置中的 Access tokens 部分创建 personal access token。处理代码只需要 read_repository 和 write_repository 权限；设置有效期，并立即保存令牌，因为它不会再次显示。

第一次 push 或 clone 时，Git 会要求输入用户名和密码：用户名填 GitLab 用户名，密码处填令牌。凭据管理器（Git for Windows 中已内置）会记住它，之后就不必再次输入。

通过 SSH 密钥登录

SSH 更适合日常使用：添加一次密钥，之后就不再需要输入任何内容。

ssh-keygen -t ed25519 -C "zhang@example.com"
cat ~/.ssh/id_ed25519.pub

将 .pub 公钥文件的内容粘贴到 GitLab 个人设置的 SSH Keys 部分。连接测试：

ssh -T git@gitlab.com
Welcome to GitLab, @zhang.wei!

使用 git clone 克隆 GitLab 仓库

项目页面上有一个 Code 按钮，其中包含两个地址：SSH 和 HTTPS。复制需要的那个，然后执行 git clone：

# 通过 HTTPS
git clone https://gitlab.com/my-group/my-project.git

# 通过 SSH
git clone git@gitlab.com:my-group/my-project.git

在 GitLab 中，项目路径可以包含子群组，例如 gitlab.com/company/backend/api.git，这是正常的，请完整复制地址。

使用令牌执行 GitLab 的 git clone

在脚本中或服务器上，没有人可以输入密码，这时可以把令牌直接写进地址。用户名可以是你的用户名，也可以是通用的 oauth2：

git clone https://oauth2:你的令牌@gitlab.com/my-group/my-project.git

注意：这样的地址会保存在 .git/config 中，还可能进入 shell 的命令历史。自动化场景中，最好使用部署令牌（deploy token）或项目访问令牌，并赋予最少的权限和有限的有效期；在 CI 中则使用内置变量 CI_JOB_TOKEN。

Git push 到 GitLab：发送代码

如果项目已经在本地，先在 GitLab 中创建一个空项目（不要勾选 README，以免产生多余的提交），然后添加远程仓库：

git remote add origin git@gitlab.com:my-group/my-project.git
git branch -M main
git push -u origin main

-u 参数把本地分支与远程分支关联起来，之后只需使用 git push 和 git pull。日常的工作流程与其他任何服务都相同：

git switch -c feature/login
git add .
git commit -m "添加登录表单"
git push -u origin feature/login
git pull

标签需要单独推送：git push origin v1.2.0，或者用 git push --tags 一次推送全部标签。在 GitLab 中，标签显示在 Tags 部分，常常会触发发布流水线。

git push 到 GitLab 的常见错误

• HTTP Basic: Access denied：用户名错误，或者输入的是密码而不是令牌。请创建带有 write_repository 权限的令牌，并从凭据管理器中删除旧记录。
• Permission denied (publickey)：GitLab 无法识别你的 SSH 密钥。检查公钥是否已添加到个人资料中，并执行 ssh -T git@gitlab.com。
• You are not allowed to push code to protected branches：分支（通常是 main）受到保护。请把修改推送到你自己的分支，然后创建 merge request。
• rejected ... (fetch first)：服务器上有你本地没有的提交。执行 git pull --rebase 后再推送。
• remote: Project not found：地址拼写错误，或者你没有该项目的访问权限；请向项目所有者确认你的角色。

GitLab 中的 merge request

Merge request 相当于 GitHub 上的 pull request：请求把你的分支合并到主分支。协作者正是在 MR 中对代码行留下评论，运行 CI 检查，并做出是否合并的决定。推送新分支后，GitLab 会在终端中输出创建 MR 的链接，而网页界面中也会出现创建 MR 的提示。

也可以直接用命令行通过 push options 创建 MR：

git push -o merge_request.create -o merge_request.target=main origin feature/login

典型流程是：为任务创建分支 → 提交 → push → 创建 MR → 评审并让流水线变绿 → merge。合并时，GitLab 可以把提交压缩为一个（squash），并删除源分支。如果 MR 出现冲突，最简单的做法是在本地更新分支：git pull --rebase origin main 或 git merge main，解决冲突，然后再次推送。

尚未完成的工作请标记为 Draft：这样的 MR 不会被误合并，而同事仍然可以看到修改并参与讨论。

GitLab 中的 CI/CD：.gitlab-ci.yml

GitLab 最显著的特点是内置 CI/CD。只要在仓库根目录放置 .gitlab-ci.yml 文件，每次 push 时 GitLab 都会运行一条由阶段（stages）和任务（jobs）组成的流水线（pipeline）。任务由 runner 执行：gitlab.com 提供公共 runner，自建服务器则需要单独安装。

stages:
  - test
  - deploy

test:
  stage: test
  image: python:3.12
  script:
    - pip install -r requirements.txt
    - pytest

deploy:
  stage: deploy
  script:
    - ./deploy.sh
  rules:
    - if: $CI_COMMIT_TAG

这里的测试在每次 push 时运行，而 deploy 任务只在推送标签时运行：先执行 git tag v1.0.0，再执行 git push origin v1.0.0。流水线结果直接显示在 merge request 中，并且可以设置为在检查未通过时禁止合并。

如何删除 GitLab 中的仓库

Git 命令无法删除服务器上的项目：git push 只会修改分支和标签。项目需要在网页界面中删除：进入项目设置，打开 General 部分的 Advanced 区块，点击删除按钮并输入项目名称确认。需要 Owner 角色。本地副本不会受到影响，它只是一个包含 .git 的文件夹。

如果只想把本地仓库与 GitLab 断开，而不删除服务器上的任何内容，执行 git remote remove origin 即可。

什么时候选择 GitLab

• 代码不能放到外部云端，必须使用自己的服务器。
• 需要开箱即用的 CI/CD，而不依赖第三方服务。
• 大型组织，团队层级复杂，需要嵌套群组和灵活的角色。
• 你加入的公司已经在使用 GitLab：这种情况下没有选择余地，但 Git 技能可以完全迁移。

对于作品集和开源项目，人们通常选择 GitHub：那里的社区更大，项目的可见度更高。也完全可以把同一个项目同时保存在两个服务上，因为一个仓库可以有多个 remote。

总结

GitLab 是为 Git 仓库提供服务的平台，通过 merge request 进行评审，并内置任务和 CI/CD，既可以使用云端服务，也可以部署在自己的服务器上。使用它的关键是：配置好令牌或 SSH 密钥登录，然后使用熟悉的 clone、commit、push 和 merge request 即可。远程仓库和团队工作流程在本课程的 Git 实践中都有详细讲解。