Gitlab .gitlab-ci.yml详解

job内定义作业流程的参数列表

关键字	必要性	描述
script	是	定义在runner中执行的命令
after_script	否	作业后执行的命令
allow_failure	否	允许作业失败，失败不会导致管道失败
artifacts	否	定义job产生的附件，可用于下载和保存以及传递，没有该项设置产生的过程文件都会被删除
extends	否	此作业继承的配置条目
before_script	否	在作业之前执行的一组命令
cache	否	定义缓存的文件或文件夹，如果是在job外定义则为全局变量
coverage	否	给定作业的代码覆盖率设置
dependencies	否	定义该job依赖于哪项job的结果，用于把之前job的附件传进来
environment	否	作业部署到的环境名称
except	否	定义哪些分支或tag的修改不触发该流程
image	否	使用docker镜像
include	否	包括外部yaml文件
inherit	否	选择所有作业继承的全局默认值
interruptible	否	定义当新的运行变得多余时，是否可以取消作业
needs	否	在阶段排序之前的作业
only	否	定义哪些分支或tag的修改触发该流程
pages	否	使用gitlab pages 上传作业的结果
parallel	否	定义并行的任务数量，限于2~50
release	否	指示runner生成一个release版本
resource_group	否	限制并发
retry	否	失败时可以重试多少次
rules	否	是否决定创建一个作业的条件列表
secrects	否	作业需要CI/CD secret
services	否	使用docker服务镜像
stage	否	定义作业的阶段，默认test阶段
tags	否	用来决定哪个runner来执行作业
timeout	否	作业超时时间
trigger	否	定义下游管道触发器
variables	否	作业级别定义的变量
when	否	何时执行任务

1.before_script 和 after_script：用来定义作业前后的操作，可以定义全局作业的前后操作，也可以是job内作业前后操作，需要的是数组类型；script为job内唯一一个必须的关键字，配置runner执行的shell命令，可单行，可以多行。

before_script: 
 - echo "global before script"
after_script: 
 - echo "global after script"

job 1:
    before_script: 
      - echo "job1 before script"
    script: 
      - echo 'job1 script'
    
job 2:
    script: 
      - echo 'job2 script'
    after_script: 
      - echo "job2 after script"    

运行结果可以看到

job1中打印

job2中打印

2. stages ：定义pipeline的全部阶段（stage），阶段内的全部任务并行执行，全部任务成功开始下一阶段任务，任何阶段内的任意job失败都会导致pipeline失败，所有stage，job执行成功后pipeline会显示pass。如果未定义stages，则默认有build、test、deploy三个阶段，如果job中未定义stage，则默认为test

stages:
  - build
  - test
  - deploy

job 1:
  stage: build
  script: echo "job1 build"

job 2:
  stage: build
  script: echo "job2 build"

job 3:
  stage: test
  script: echo "job3 test"

job 4:
  stage: deploy
  script: echo "job4 deploy"

job 5:
  script: echo "job5 scpript"

可以看到Pipeline中的执行顺序为build阶段，job1、job2并行执行，之后执行test阶段，job3，job5（没有定义stage，默认为test），最后执行deploy阶段，job4执行。

注意执行的顺序与编写先后顺序无关。

3. only：定义在哪个分支或者tag上的修改触发执行；except：定义哪个分支或者tag修改不触发任务的执行。

可以使用正则表达式指定，也可以指定关键字。

only和except可同时使用。如果only和except在一个job配置中同时存在，则以only为准，跳过except(从下面示例中得出)。

四个关键字可以和only、except一起使用

refs、variables、changes、kubernetes

使用only:refs和except:refs关键字来控制何时根据分支名称或管道类型向管道添加作业。

如下关键字：

关键字	描述
branches	git分支
tags	tag标签
api	当管道被第二个管道API触发时(不是触发器API)。
external	当使用除GitLab之外的CI服务时。
pipelines	对于多项目触发器，使用CI_JOB_TOKEN的API创建。
pushes	管道是由用户推送git触发的。
schedules	计划的pipelines
triggers	用于使用触发器令牌创建的管道
web	在GitLab UI中运行管道按钮
merge_requests	合并请求

例如：

如下， job会为所有的分支执行job，除master分支外

job 1:
    script:
     - echo "job script"
    only:
     - branches@gitlab-org/gitlab-ce
    except:
    - master@gitlab-org/gitlab-ce

如下，job指挥执行有tags的refs，或者通过API触发器明确地请求构建

job: 
  only:
    - tags
    - triggers

4. tags：tags可以从允许运行此项目的所有Runners中选择特定的Runners来执行jobs。这里的tags是在注册Runner过程中，设置Runner的标签，只有Runner中的有这个标签，这个job才能运行。

如下：当Runner定义了ruby和postgres这两个标签，才能运行这个job

job 1:
  tags:
    - ruby
    - postgres

5. allow_failure：设置一个job失败之后并不影响其他CI组件，失败的job不会影响到commit状态。

如下：job1是有一个错误的，但是设置了allow_failure，所以pipeline最终状态不是failed

job1:
  stage: test
  script:
  - a = 1/0
  - echo "test stage"
  allow_failure: true
job2:
  stage: build
  script:
  - echo "build stage"
job3:
  stage: deploy
  script:
  - echo "deploy stage"

最后的结果是一个黄色的，但是还是passed的状态

6. when：用于执行失败时或者失败后的任务

可以设置为

on_success:只有当前面的stages的所有工作成功时才执行。

on_failure:当前面stages中任意一个job失败后执行。

always:无论前面的job状态如何都执行。

manual:手动执行，Gitlab8.10开始引入，手动操作指令是不自动执行的特殊类型的job；它们必须要人为启动。手动操作指令可以从pipeline，build，environment和deployment视图中启动。

如：

stages:
- build
- cleanup_build
- test
- deploy
- cleanup
build_job:
  stage: build
  script:
  - a = 1/0
  - echo "build job"
cleanup_build_job:
  stage: cleanup_build
  script:
  - echo "clean build job"
  when: on_failure
test_job:
  stage: test
  script:
  - echo "test job"
deploy_job:
  stage: deploy
  script:
  - echo "deplpy job"
cleanup_job:
  stage: cleanup
  script:
  - echo "clean up job"
  when: always

结果如下，失败之后执行失败后可以执行的job，不管成功或者失败，都会执行cleanup的job，其他job不执行，最后结果是failed。

7.variables ：job中可以使用关键字variables来定义job变量。当设置了job级别的关键字variables，他会覆盖全局YAML和预定义的job变量，想要关闭全局变量可以在job中设置一个空数组。

job_name:
  variables: []

variables:
  DEPLOY_SITE: "baidu.com"

job 1:
  stage: deploy
  script:
    - echo $DEPLOY_SITE

job 2:
  stage: deploy
  variables:
    DEPLOY_SITE: "qq.com"
  script:
    - echo $DEPLOY_SITE 

job1 打印baidu.com

job2 打印qq.com，因为job2中覆盖了全局的变量

8.environment

review_app:
  stage: deploy
  script: echo 'revie app'
  environment:
    name: origin
    url: http://qq.com
    on_stop: stop_review_app
    
stop_review_app:
  stage: deploy
  script: echo 'review app stop'
  environment:
    name: origin
    action: stop   

可以在这里查看到自己写的environment，点击这里的，如果没有写on_stop，则会在Available中显示。

这里会有两个按钮，一个按钮可以跳到自己写的url地址，一个是重新运行这个job的。

注意该job on_stop对应的job的environment的name要一致，不然报错。

9.artifacts：被用于在job作业成功后将制定列表里的文件或文件夹附加到job上，传递给下一个job.

stages:
 - test
 - build
 - deploy

job1:
  stage: test   
  script: echo "job1"
  artifacts:
      paths:
      - .config
  
job2:
  stage: build
  script: echo "job2"
  artifacts:
    paths:
      - .config

job3:
  stage: deploy
  script: echo "job3"
  artifacts:
    paths:
      - .config

这是job3的打印，可以看到，他会先下载job2的artifacts，然后下载job1的artifacts，最后上传自己的artifacts。

如果不想要前面job的artifacts，可以使用一个空的dependencies

job:
  stage: build
  script: make build
  dependencies: []

job完成后artifacts可以在项目页面中下载

其他的一些配置

stages:
 - test
 - build
 - deploy

job1:
  stage: test   
  script: echo "job1"
  artifacts:
      name: job1
      paths:
      - .config
      #job失败上传
      when: on_failure
job2:
  stage: build
  script: echo "job2"
  artifacts:
    #发送所有没有被git跟踪的文件
    untracked: true
    paths:
      - .config
    #job成功上传
    when: on_success

job3:
  stage: deploy
  script: echo "job3"
  #不用前面job的artifacts
  dependencies: []

job4:
  stage: deploy
  script: echo "job3"
  #不用前面job的artifacts
  artifacts:
    paths:
      - .config
    #不论job成功失败都上传
    when: always
    #设置artifacts多久会被删除
    expire_in: '3 mins'

10.dependencies：这个功能与artifacts一起使用，并允许定义在不同的jobs之间传递artifacts。

build:osx:
  stage: build
  script: echo 'job1'
  artifacts:
    name: job1
    paths:
    - .config

build:linux:
  stage: build
  script: echo 'job2'
  artifacts:
    paths:
    - .config

test:osx:
  stage: test
  script: echo 'job3'
  dependencies:
  - build:osx

test:linux:
  stage: test
  script: echo 'job4'
  dependencies:
  - build:linux

test:osx依赖的build:osx的artifacts，并且从中可以得到dependencies中写的job的名，而不是artifacts的名。

test:linux依赖build:linux的artifacts

11.coverage：配置代码覆盖率将会从job中提取输出

job1:
  script: rspec
  coverage: '/Code coverage: \d+\.\d+/'

12.retry：允许用户设置重试次数。

test:
  script: rspec
  retry: 2

13.Git Strategy:通过在全局变量设置或者job局部变量设置git策略来获取代码，如果没有指定，则默认的项目设置将会被使用。

可选值有：

clone：clone是最慢的选项，如果设置该值，每个job将会都克隆一遍仓库，确保项目工作空间总是原始的正确的。

fetch：fetch是更快的操作选项，因为他重用了项目的工作空间（如果没有的话，会去clone）, git clean用于撤销上一个job的任何操作，git fetch是用来重新获取上一个job运行到当前job产生的commit。

none：none也同样重用了项目空间（但是他会跳过所有git操作，包括如果存在的gitlab runner的预克隆脚本）。其主要用于只是为了操作artifacts的job上（例如depoly部署行为）。此时Git仓库的数据可能是存在的，但它一定不是最新的。所以在设置了none的job里你应该依赖从cache或者artifacts来的数据，而不是仓库数据。

job 1:
 variables:
   GIT_STRATEGY: clone
 script:
  - echo 'job1'
job 2:
 variables:
   GIT_STRATEGY: fetch
 script:
  - echo 'job2'
job 3:
 variables:
   GIT_STRATEGY: none
 script:
  - echo 'job3'
job 4:
 script:
  - echo 'job4'

job1克隆仓库

job2拉取改变的代码

job3跳过git操作

14.隐藏keys：Key 是以.开始的，GitLab CI 将不会处理它。你可以使用这个功能来忽略jobs。

job2将会被隐藏，不会执行。

job 1:
  stage: test
  script:
   - echo 'job1'
.job 2:
  stage: build
  script:
   - echo 'job2'
job 3:
  stage: deploy
  script:
   - echo 'job3'

15.Anchors: yaml有个方便的功能称为“锚”，他可以轻松的在文档中复制内容，Anchors可用于复制或者继承属性，并且是使用隐藏keys来提供模板的完美示例。

&在anchor的名称(job_definition)前设置，<<表示将anchor的内容复制到此处，*包括命名的anchor(job_definition)。但是如果job内有相同的属性，将会覆盖掉anchor的内容。

.job_template: &job_definition 
   script:
    - echo "job template"

test1:
   <<: *job_definition          

test2:
   <<: *job_definition       
   script:
     - echo "test2"

这里定义了一个job_template，执行一段脚本输出job template，但是job2中包含了script，将打印test2，而不是job template。

test1打印

test2 打印

定义更精细的锚点可以在指令后写，如下，定义了一个script指令锚点，使用时只需要在script指令后使用 *锚点名。

.job_template: 
   script: &script_definition 
     - echo "script template"

test1:
   script: *script_definition 

test2:    
   script:
     - echo "test2"
     - *script_definition

这样，test2就会执行两个script脚本指令，打印输出test2和script template

16.pages：是一个特殊的job，用于将静态的内容上传到GitLab，可用于为您的网站提供服务。

必须满足以下两个要求：

1>任何静态内容必须放在public/目录下

2>artifacts必须定义在publid/目录下

pages:
  stage: deploy
  script:
  - mkdir .public
  - cp -r * .public
  - mv .public public
  artifacts:
    paths:
    - public
  only:
  - master

17.GIT_DEPTH：用来指定抓取或者克隆的深度。 它可浅层的克隆仓库，这可以显著加速具有大量提交和旧的大型二进制文件的仓库的克隆。这个设置的值会传递给git fetch和git clone。

注意：如果depth=1，并且有一个jobs队列，或者是重试jobs，则jobs可能会失败。

variables:
  GIT_DEPTH: "3"

18.Job stages attempts：job尝试次数

变量	描述
GET_SOURCES_ATTEMPTS	获取job源尝试次数
ARTIFACT_DOWNLOAD_ATTEMPTS	下载artifacts的尝试次数
RESTORE_CACHE_ATTEMPTS	重建缓存的尝试次数

variables:
  GET_SOURCES_ATTEMPTS: 3

19.Cache: 用来指定需要在job之间缓存的文件或目录。只能使用该项目工作空间内的路径。

cache定义在jobs作用域之外，那么就是全局缓存，所有jobs可以使用该缓存。

cache:
  paths:
  - foo/a.txt

rspec:
  script: test
  cache:
    key: rspec
    paths:
    - .config

打印如下，可以看到只创建了job的cache，全局cache没有创建。

注意：缓存是在jobs之间进行共享的。如果你不同的jobs缓存不同的文件路径，必须设置不同的cache:key，否则缓存内容将被重写。

好了，.gitlab-ci.yml关键字，就这些了，不懂的可以看下官方文档。

https://docs.gitlab.com/ee/ci/yaml/index.html