GitLab 中文文档

Getting started with GitLab CI/CD

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会以它自己的系统环境来构建你的应用。

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

If you want to check whether your .gitlab-ci.yml file is valid, there is a Lint tool under the page /ci/lint of your GitLab instance. You can also find a "CI Lint" button to go to this page under CI/CD ➔ Pipelines and Pipelines ➔ Jobs in your project.

查看更多信息关于.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 文档。

You can find whether any Runners are assigned to your project by going to Settings ➔ CI/CD. Setting up a Runner is easy and straightforward. The official Runner supported by GitLab is written in Go and its documentation can be found at https://docs.gitlab.com/runner/.

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

  1. 安装Runner
  2. 配置Runner

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

Once the Runner has been set up, you should see it on the Runners page of your project, following Settings ➔ CI/CD.

Activated runners

Shared Runners 共享的构建客户端

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

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

To enable the Shared Runners you have to go to your project's Settings ➔ CI/CD and click Enable 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