GitLab 中文文档

快速开始

Note: 从8.0版本开始, GitLab Continuous Integration (CI) 已经完全集成到GitLab里面, 默认情况下所有项目都会[启用]CI功能。

GitLab提供可持续集成服务。只要在你的仓库根目录 [创建一个.gitlab-ci.yml 文件][yaml语法], 并为该项目指派一个Runner,当有合并请求或者 push的时候就会触发CI pipeline

If everything runs OK (no non-zero return values), you'll get a nice green checkmark associated with the commit. This makes it easy to see whether a commit caused any of the tests to fail before you even look at the code.

当build完成后(返回非零值),你会看到push的 commit或者合并请求前面出现一个绿色的对号。 这个功能很方便的让你检查出来合并请求是否会导致build失败, 免的你去检查代码。

大部分项目用GitLab's CI服务跑build测试, 开发者会很快得到反馈,知道自己是否写出了BUG。

所以简单的说,要让CI工作可总结为以下几点:

  1. 在仓库根目录创建一个名为.gitlab-ci.yml 的文件
  2. 为该项目配置一个Runner

完成上面的步骤后,每次push代码到Git仓库, Runner就会自动开始pipeline, pipeline的进度可以在该项目的 Pipelines 页面查看。


上面的手册都假定你符合下面的条件:

下面让我们分几个部分解开GitLab CI的疑惑。

Creating a .gitlab-ci.yaml file 创建构建配置文件

在创建 .gitlab-ci.yml文件前, 我们先简单的解释下关于这个文件的一些基础信息。

What is .gitlab-ci.yml 构建配置文件是什么

.gitlab-ci.yml 是配置CI用你的项目中做哪些操作, 这个文件位于仓库的根目录。

当有新内容push到仓库后,GitLab会查找是否有.gitlab-ci.yml文件,如果文件存在, Runners 将会根据该文件的内容开始build 本次commit。

由于.gitlab-ci.yml文件放在仓库里,所以这个文件是受版本控制的, 旧版本的.gitlab-ci.yml仍然能build成功。利用CI可以很方便的创建forks, branch(分支)可拥有不同的pipelines和jobs,并可以从CI获取你所期望得到的源码。 你可以查阅更多关于我们决定使用 .gitlab-ci.yml的原因。 点此查看.

Creating a simple .gitlab-ci.yml file

Note: .gitlab-ci.yml is a YAML file so you have to pay extra attention to indentation. Always use spaces, not tabs.

You need to create a file named .gitlab-ci.yml in the root directory of your repository. Below is an example for a Ruby on Rails project.

before_script:
  - apt-get update -qq && apt-get install -y -qq sqlite3 libsqlite3-dev nodejs
  - ruby -v
  - which ruby
  - gem install bundler --no-ri --no-rdoc
  - bundle install --jobs $(nproc)  "${FLAGS[@]}"

rspec:
  script:
    - bundle exec rspec

rubocop:
  script:
    - bundle exec rubocop

这是一个最简单的build配置, 大部分Ruby程序都可以套用这个例子:

  1. 定义两个任务,rspecrubocop(名字可以随便起,这两个其实都是ruby程序中的库),这两个任务会执行两段不同的命令。
  2. 在每个任务之前,定义为before_script里面的命令会优先执行。

.gitlab-ci.yml文件定义了任务应该在何时以哪种方式来运行。 任务的定义应以一个处在顶级的元素开始(如上面例子中的rspecrubocop), 通常都会包含script这个关键字。 任务用来构建你的应用,它会被指定的Runners来执行, Runners会以它自己的系统环境来构建你的应用。

需要特别注意的是,每个任务都是彼此独立运行的。

GitLab服务器上有一个Lint工具可以用来检查你的.gitlab-ci.yml是否有效, 你可用通过访问你的域名加ci/lint这个路径来打开Lint工具。 也可以点击 Pipelines ➔ JobsPipelines ➔ Pipelines 页面的"CI Lint"按钮打开Lint工具。

查看更多信息关于.gitlab-ci.yml语法的信息,请点击 .gitlab-ci.yml详解.

Push .gitlab-ci.yml to GitLab 推送构建配置文件

如果你已经创建好.gitlab-ci.yml, 现在应该把它push到GitLab上你的仓库里面了。

git add .gitlab-ci.yml
git commit -m "Add .gitlab-ci.yml"
git push origin master

现在在项目首页的 Pipelines 页面可以看到这个pipeline已经处于pending状态了。

你也可以在 Commits 页面留意到 commit SHA前面会有一个小时钟的小图标。

New commit pending

点击这个小图标就可以看到该commit相关的Build状态了。

Single commit jobs page

我们可以看到这里有两个任务处于挂起(pending)状态, 这两个任务就是我们之前写在.gitlab-ci.yml里面的。 红色的三角警告标志的意思是我们还没有给这些jobs配置Runner。

下面我们就来讲解下如何给挂起的jobs配置Runner。

Configuring a Runner 配置一个构建客户端

在GitLab中,Runners会按照你在.gitlab-ci.yml里面定义的任务进行jobs。 Runner可以运行在虚拟机、VPS、物理机、docker容器甚至容器集群上。 GitLab与Runners通过API进行通信, 所以只要Runners能访问网络就能与GitLab通信。

一个Runner可以指定给特定的项目或者多个项目, 如果一个Runner给所有的项目提供服务,我们叫它 Shared Runner

想了解更过专用Runner和共享Runner的区别,请查看 Runners 文档。

Settings ➔ Pipelines 页面可以查看被指派给该项目的Runners。 安装配置Runner非常简单, 官方的Runner是用Go语言开发的, 文档https://docs.gitlab.com.cn/runner/

按照下面的两个步骤就可以配置一个整装待发的Runner:

  1. 安装Runner
  2. 配置Runner

掌握上面的两点后,你可以安装一个属于你自己的Runner, 或者使用下面章节介绍的Shared Runner(共享Runner)。

Runner安装配置好后, Runner 配置完成后,你就可以在你的项目通过依次点击 Settings ➔ Pipelines Runner 页面看到它了。

Activated runners

Shared Runners 共享的构建客户端

如果你的代码托管在GitLab.com, 你可以使用GitLab Inc提供的 Shared Runners

基于GitLab.com 基础架构的虚拟器可以Build任何项目。

在项目的 Settings ➔ Pipelines 页面点击 Enable shared runners 可以启用 Shared Runners

关于Shared Runners.

Seeing the status of your pipeline and jobs 可视化的构建流程图

成功配置Runner后,你会发现最后一次提交的状态由 pengding 变成了 running,success 或者 failed.

你可以在 Pipelines 页面可以查看该项目所有的 pipelise.

Commit status

或者在 Pipelines ➔ Builds 页面查看所有的jobs.

Commit status

点击任务状态,可以看到该job的所有log。 这是诊断jobs失败原因 或者jobs的结果与你的期望值不一样的关键方法。

Build log

当然,你也能在GitLab的其他很多页面查看任何commit的build status,比如 CommitsMerge Requests 页面。

Enabling build emails 启用构建邮件通知

Examples