官方参考地址

从版本7.12开始，GitLab CI使用YAML文件（.gitlab-ci.yml）进行项目配置，该文件位于代码仓库的根目录中，包含有关如何构建项目的pipeline,以及ppeline需要完成哪些工作。

pipeline

一次 Pipeline 其实相当于一次构建任务，里面可以包含多个流程，如build、test、deploy测试服务器、部署生产服务器等流程，任何成员的commit push到GitLab上时都可以触发 Pipeline。

接下来先来个小例子：

stages:
  - build
  - test
job1:
  stage: test
  script:
  - sh test.sh
  artifacts:
    paths:
    - data_test/
job2:
  stage: build
  script:
  - echo 'suceed test' >> txt1

上面的代码块定义两个阶段（stages），build和test两步，stages中的阶段按写的顺序进行，先build再test；接下来有两个工作要执行job1/job2，job1属于test阶段的工作，job2属于build阶段的工作，所以先执行job2再job1，job下面的关键字stage定义该job属于哪个阶段，关键字script下面定要执行的命令。
下面是在Gitlab-runner中的运行结果

build

Running with gitlab-ci-multi-runner 1.11.2 (0489844)
  on mac-runner (e7d87f13)
Using Shell executor...
Running on shuchaodeMacBook-Pro.local...
Fetching changes...
Removing data_test/190102_NS500203_0435_AHKHKWBGX9.Zscore.xls
Removing data_test/190102_NS500203_0435_AHKHKWBGX9.sum.txt.cv.csv
Removing data_test/190102_NS500203_0435_AHKHKWBGX9_mapChr.xls
HEAD is now at 7387b3c Delete 190102_NS500203_0435_AHKHKWBGX9.sum.txt.cv.csv
From http://192.168.4.168:10080/shujingchao/my_test
   7387b3c..07e1d96  master     -> origin/master
Checking out 07e1d961 as master...
Skipping Git submodules setup
$ echo 'suceed test' >> txt1
Job succeeded

test

Running with gitlab-ci-multi-runner 1.11.2 (0489844)
  on mac-runner (e7d87f13)
Using Shell executor...
Running on shuchaodeMacBook-Pro.local...
Fetching changes...
HEAD is now at 07e1d96 Delete 190102_NS500203_0435_AHKHKWBGX9.Zscore.xls
Checking out 07e1d961 as master...
Skipping Git submodules setup
$ sh test.sh
Uploading artifacts...
data_test/: found 6 matching files                 
Uploading artifacts to coordinator... ok            id=2841 responseStatus=201 Created token=V9Z53_t3
Job succeeded

关键字参数

该文件通过一系列的关键字参数来定义pipeline的每一个每一项任务的执行方式，接下来就是各项参数的函数以及用法。

Jobs

YAML文件定义了一组具有约束的作业，说明应该何时运行它们。可以指定无限数量的作业，这些作业被定义为任意名称的抬头，但是始终必须至少应包含script子句。

job1:
  script: "execute-script-for-job1"

job2:
  script: "execute-script-for-job2"

上述配置了两个单独的作业流程，每个job由单独的script执行命令，每项job都是独立运行，如果是相同stage的多项job会并行运行。作业必须具有唯一的名字，但不能以以下关键字来定义：
image
services
stages
types
before_script
after_script
variables
cache

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

Keyword	Required	Description
script	yes	定义在runner中执行的命令
extends	no	Defines a configuration entry that this job is going to inherit from
include	no	Defines a configuration entry that allows this job to include external YAML files
image	no	Use docker image, covered in Using Docker Images
services	no	Use docker services, covered in Using Docker Images
stage	no	定义job属于哪个阶段，默认test阶段
type	no	stage别名
variables	no	定义job层次的变量
only	no	定义哪些分支或tag的修改触发该流程
except	no	定义哪些分支或tag的修改不触发该流程
tags	no	定义哪个标签的runner来执行，该标签指runner配置时的名称，不是Git的tag分支
allow_failure	no	Allow job to fail. Failed job doesn’t contribute to commit status
when	no	Define when to run job. Can be on_success, on_failure, always or manual
dependencies	no	定义该job依赖于哪项job的结果，用于把之前job的附件传进来
artifacts	no	定义job产生的附件，可用于下载和保存以及传递，没有该项设置产生的过程文件都会被删除
cache	no	定义缓存的文件或文件夹，如果是在job外定义则为全局变量
before_script	no	定义job执行前的操作
after_script	no	定义job执行后的操作
environment	no	Defines a name of environment to which deployment is done by this job
coverage	no	Define code coverage settings for a given job
retry	no	定义任务失败后的重复执行次数或时间
parallel	no	定义并行的任务数量，限于2~50
trigger	no	Defines a downstream pipeline trigger

before_script and after_script

before_script and after_script定义作业前后的操作，可以定义全局作业前后的操作，也可以是job内作业前后的操作。

before_script:
  - global before script

job:
  before_script:
    - execute this instead of global before script
  script:
    - my command
  after_script:
    - execute this after my script

stages

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

stages:
  - build
  - test
  - deploy

stage

定义job属于哪个stage，默认test

stages:
  - build
  - test
  - deploy

job 1:
  stage: build
  script: make build dependencies

job 2:
  stage: build
  script: make build artifacts

job 3:
  stage: test
  script: make test

job 4:
  stage: deploy
  script: make deploy

script

job内唯一一项必须的关键字设置，配置runner执行的shell命令，可单行也可多行。

job1:
  script: "bundle exec rspec"
job2:
  script:
    - uname -a
    - bundle exec rspec

only and except

only定义在哪个分支或tag上的修改触发执行
except定义哪个分支或tag的修改不触发任务的执行
允许使用正则表达式指定
允许指定的一些关键字：

Value	Description
branches	When a git reference of a pipeline is a branch.
tags	When a git reference of a pipeline is a tag.
api	When pipeline has been triggered by a second pipelines API (not triggers API).
external	When using CI services other than GitLab.
pipelines	For multi-project triggers, created using the API with CI_JOB_TOKEN.
pushes	Pipeline is triggered by a git push by the user.
schedules	For scheduled pipelines.
triggers	For pipelines created using a trigger token.
web	For pipelines created using Run pipeline button in GitLab UI (under your project’s Pipelines).
merge_requests	When a merge request is created or updated (See pipelines for merge requests).

下面这个例子只执行issue-开头的refs，所有branch跳过

job:
  # use regexp
  only:
    - /^issue-.*$/
  # use special keyword
  except:
    - branches

下面的例子执行gitlab-org/gitlab-ce上的所有分支，除了master

job:
  only:
    - branches@gitlab-org/gitlab-ce
  except:
    - master@gitlab-org/gitlab-ce

如果任务没有指定only参数，则默认['branches', 'tags']，未指定except，则默认为空。

tags

tags允许指定已经关联的runner来执行任务
下面的例子由定义为ruby和postgres的runner来执行

job:
  tags:
    - ruby
    - postgres

也可以为不同的job指定不同不同的runner，例如windos和mac上的任务由不同的runner执行

windows job:
  stage:
    - build
  tags:
    - windows
  script:
    - echo Hello, %USERNAME%!

osx job:
  stage:
    - build
  tags:
    - mac
  script:
    - echo "Hello, $USER!"

allow_failure

allow_failure关键字允许该项job失败后不影响其他任务的继续执行，如果其他任务全部执行成功也会显示pipeline pass，只是该任务提示橙色警告标示，该设置默认false不启动；下面的例子job1失败后不会影响后续任务job2/job3的执行

job1:
  stage: test
  script:
    - execute_script_that_will_fail
  allow_failure: true

job2:
  stage: test
  script:
    - execute_script_that_will_succeed

job3:
  stage: deploy
  script:
    - deploy_to_staging

when

when用于当前一阶段任务故障或者忽略故障的job任务，主要用于清理发生故障时的后续措施。
可选项：

1. on_success - 默认参数，前一阶段任务成功时才执行
2. on_failure - 前一阶段任务故障时才执行
3. always - 无论前一阶段任务是否成功都执行
4. manual - 手动设置，比较复杂，略过。

stages:
  - build
  - cleanup_build
  - test
  - deploy
  - cleanup

build_job:
  stage: build
  script:
    - make build

cleanup_build_job:
  stage: cleanup_build
  script:
    - cleanup build when failed
  when: on_failure

test_job:
  stage: test
  script:
    - make test

deploy_job:
  stage: deploy
  script:
    - make deploy
  when: manual

cleanup_job:
  stage: cleanup
  script:
    - cleanup after jobs
  when: always

上面的例子当build任务失败时才会执行cleanup_build任务；无论之前的任务是否成功，最后都会执行clean_up的任务；当执行到deploy任务时，会触发手动设置。

artifacts

artifacts指任务成功后可供下载的附件，可在pipeline-CI中下载

1. artifacts:paths - 该路径下的文件作为附件，只可指定仓库内的路径
2. artifacts:name - 下载附件时的名称，可利用内置变量作为附件的名字
3. artifacts:when - 指定当job成功或失败时才会上传附件
4. artifacts:expire_in - 指定附件上载后保存的时间，默认永久在Gitlab保存
5. artifacts:untracked - 指定上传Git未跟踪的文件

job:
  artifacts:
    name: "$CI_JOB_NAME-$CI_COMMIT_REF_NAME"
    paths:
      - binaries/
    when: on_failure
    expire_in: 1 week
    untracked: true

上面的例子会在任务失败时上载binaries/路径下未被跟踪的文件，附件以job-ref为名字，保留一周的时间。

parallel

同时允许运行的job个数

test:
  script: rspec
  parallel: 5

include

把其他文件中的内容包含进来，类似于Makefile中的include

include:
  - project: 'my-group/my-project'
    ref: master
    file: '/templates/.gitlab-ci-template.yml'

  - project: 'my-group/my-project'
    ref: v1.0.0
    file: '/templates/.gitlab-ci-template.yml'

  - project: 'my-group/my-project'
    ref: 787123b47f14b552955ca2786bc9542ae66fee5b # Git SHA
    file: '/templates/.gitlab-ci-template.yml'
include:
  - remote: 'https://gitlab.com/awesome-project/raw/master/.gitlab-ci-template.yml'

variables

用于定义全局或私有变量，同时内置了一些内置变量，如CI_COMMIT_REF_NAME表示构建任务的分支或tag，点此查看更多内置变量

variables:
  DATABASE_URL: "postgres://postgres@postgres/my_database"

Special YAML features

&定义调用的方式，.代表注释掉该job， aliases (*) 、map merging (<<),用于调用重复的内容

.deploy: &deploy_template
  stage: deploy
  tags:
    - bambnitest
  only:
    - tags
    - triggers
    - /^ci-deploy/
  allow_failure: true
  before_script:
    - ls -alh "bin"
  script:
    - rsync -luvr bin $HOST_IP:/work
job128:
  <<: *deploy_template
  variables:
    HOST_IP: "*****.128.2"
job129:
  <<: *deploy_template
  variables:
    HOST_IP: "******.129.2"

Skipping jobs

如果提交信息有[ci skip] 或者[skip ci]会执行提交，但是会跳过pipeline

git push -o ci.skip