logo

鱼肚的博客

Don't Repeat Yourself

Gitlab CI的机制及配置文件写法

gitlab-ci-infograph

图片来自https://www.onyxpoint.com/account-level-ci-access-management-with-gitlab-setuid-runners/

Gitlab CI的基本原理

机制

对于Gitlab仓库中的每一次Push(注意不是每一次Commit),Gitlab系统都会尝试去执行CI。

它会做如下的判断:

  1. 当前分支中有无 .gitlab-ci.yml 配置文件?有则继续,无则退出
  2. .gitlab-ci.yml中有无命名当前分支的job,或者提交信息中有无 skip-ci?有则继续,无则退出
  3. 创建pipeline,通知Gitlab Runner
  4. .gitlab-ci.yml中有无语法错误?有则显示 invalid-yaml并退出,无则继续
  5. 根据job中配置的runner tag,可否找到匹配的Runner?有则继续,无则显示 stuck
  6. 通知Runner执行任务,并获取结果

流程图

image-20201231143017218

Runner机制

不同于Travis CI等公网的CI服务,自建的Gitlab CI更类似于Jenkins,需要自己提供CI/CD服务运行环境。

它可以是一个Linux服务器,也可以是一个PC机,或者一个笔记本电脑,甚至一个树莓派。只要能运行gitlab提供的Runner程序,即可注册到Gitlab项目中,成为一个Runner。

Runner的注册机制

每个Gitlab项目,都会有一个自己的Gitlab CI设置Token。在你运行起gitlab-runner之后,可使用它的register命令将自身注册到Gitlab中,需要提供的参数有gitlab host地址,项目token,runner名称,tag列表等。

每个Runner注册之后,都会出现在Gitlab CI的Runner列表中,并带有如下的属性:

image-20201231135403848

这些属性中比较重要的就是Tags了,它规定了这个Runner能执行哪些任务。

Runner的Tags

每个Gitlab Runner,都可以配置一系列的tags,当然也可以只配置一个。

它与.gitlab-ci.yml文件中,job的tag相对应。一个job指定了其tag之后,Gitlab就会尝试为其寻找一含有可用tag的空闲Runner,如果有可用Runner且符合一定的其它条件,就会使用指定的Runner运行这个CI任务。

这个对应关系是Job维度的,而不是Pipeline维度。所以一个Pipeline很可能会利用到多个不同的runner。

.gitlab-ci.yml文件的写法

讲完了Gitlab CI的大概运行机制,下面再来说下它的配置文件写法。

这个文件是Gitlab CI的核心配置文件,存储在代码仓库中,文件采用YAML文件格式,可参考YAML 语言教程

先看下它的基本写法:

1stages:
2  - build
3  - test
4
5windows job:
6  stage:
7    - build
8  tags:
9    - windows
10  script:
11    - echo Hello, %USERNAME%!
12
13osx job:
14  stage:
15    - build
16  tags:
17    - osx
18  script:
19    - echo "Hello, $USER!"
20
21test job:
22  stage:
23    - test
24  tags:
25    - test
26  script:
27    - echo "Test"

从示例中可以看出,它的最基本写法是先有stages,划定有哪些执行阶段。

Pipeline graph

每个stage,对应于图中的一个列。

然后下面是job列表,windows job,osx job以及test job等都是可随意起的名字,绕开保留关键字,以及不要重名即可。

每个job中都可以配置stagetagsscript参数,分别用于指定其执行阶段,需要使用的Runner选择器、需要执行的命令等。

script需要与runner配套,比如说要运行Shell脚本,那多半要选择Linux环境,要使用nodejs,则最好选一个预置好Node.js的运行时。

Gitlab官方也有关于.gitlab-ci.yml的入门教程:Get started with GitLab CI/CD

另外也有官方提供的完全手册GitLab CI/CD pipeline configuration reference,注意里面的各项配置有区分版本,部分配置只在新版本中可用。