官方参考地址

从版本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内定义作业流程的参数列表

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的修改不触发任务的执行
允许使用正则表达式指定
允许指定的一些关键字：

下面这个例子只执行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