在.gitlab-ci.yml中配置你的工作流

---

这篇文章描述了.gitlab-ci.yml的用法，.gitlab-ci.yml文件被Gitlab Runner用来管理你的jobs。
从7.12版本开始，Gitlab CI 用YAML文件（.gitlab-ci.yml）来配置项目。它被放置在你仓库的根目录并且应该包含YAML如何构建你项目的定义。如果你先要Gitlab CI的快速介绍，可以看下我们的快速快开始指导

注意：如果你有镜像仓库需要Gitlab去拉取，你可能需要开启pipeline triggering，在你的项目中设置Settings > Repository > Pull from a remote repository > Trigger pipelines for mirror updates.

Jobs

---

YAML文件定义了一些job,这些job限制了他们应该被运行的时间。你可以在文件的顶层中指定无限的job,他们可以随意命名，并且至少包含一个script条目

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

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

上面的例子是CI/CD配置可以的最简单的配置，有两个分离的job,每一个job执行不同的命令，当然命令可以直接在仓库中执行代码（./configure; make;make install）或者运行脚本（test.sh）.
Job被Runner挑选出来，并且在Runner环境中执行，最重要的是每个Job相对与其他Job是独立运行的。
每个Job必须包含唯一的名字，但是这里有一些保留的关键字不能被用作Job的名称：

• image
• services
• stages
• types
• before_script
• after_script
• variables
• cache

一个job通过以下一些定义job行为的参数定义而成。

关键字	是否必须	描述
script	yes	定义Runner执行的shell脚本
extends	no	定义当前job继承配置的入口
image	no	定义脚本镜像，涵盖在Docker镜像使用
services	no	使用docker services,涵盖在使用Docker镜像
stage	no	定义job的stage（默认：test）
type	no	stage的别名
variables	no	在job层定义变量
only	no	定义创建job的git refs的列表
except	no	定义不创建job的git refs的列表
tags	no	定义用来选择Runner的tag列表
allow_failure	no	允许job失败，失败的job无助于commit的状态
when	no	定义何时运行job可以是on_success,on_failure,always或者manual
dependencies	no	定义另外的job作为当前job的依赖，这样你就可以在他们之间传递工件
artifacts	no	定义job工件列表
cache	no	定义应该被缓存起来的东西，以便在下次run的时候使用
before_script	no	定义在job之前执行的命令列表
after_script	no	定义在job之后执行的命令列表
environment	no	定义由该job完成发布的环境的名称
converage	no	定义该job代码覆盖率的设置
retry	no	定义在失败的情况下可以自动重试多少次
parallel	no	定义多少job实例可以同时运行

extends

在Gitlab11.3中引入

extends定义继承的job的名称。他是使用YAML anchors的替代方案，它更加灵活，并且可读性更强:

.tests:
  script: rake test
  stage: test
  only:
    refs:
      - branches

rspec:
  extends: .tests
  script: rake rspec
  only:
    variables:
      - $RSPEC

在上面的例子中rspc这个job继承了.tests这个模版job。GitLab将会根据keys执行反向深度合并。Gitlab将会：

• 递归合并rspec的内容到.tests
• 不合并键的值

rspec job的结果如下：

rspec:
  script: rake rspec
  stage: test
  only:
    refs:
      - branches
    variables:
      - $RSPEC

注意：script: rake test已经被script:rake rspec合并了。

如果你想要包含rake test,看看before_script-and-after_script.
.tests在这个例子中是一个隐藏的key,但是它也可以继承自正常的job.
extends支持多层继承，但是不建议超过三层的继承。最多支持的嵌套层级是10层。下面的例子有两个层级的嵌套。

.tests:
  only:
    - pushes

.rspec:
  extends: .tests
  script: rake rspec

rspec 1:
  variables:
    RSPEC_SUITE: '1'
  extends: .rspec

rspec 2:
  variables:
    RSPEC_SUITE: '2'
  extends: .rspec

spinach:
  extends: .tests
  script: rake spinach

跨文件的extend结合include一起使用

pages

pages是一个特殊的job，它被用来上传一些服务网站的静态资源到GitLab.它有特殊的语法，必须满足以下两点：

1. 所有的静态资源必须在public/目录下
2. artifacts的path地址必须被定义成public/

下面的例子简单的将所有文件从根目录下移动到public/文件下。使用.public所以cp命令不会无限循环的拷贝public/到它自己目录下

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

详情阅读GitLab Pages user documentation.

image 和 services

该字段允许指定在job工作时间可用的自定义的Docker镜像和services列表。此功能的介绍在单独的文章中介绍。

before_script 和 after_script

注意：在GitLab8.7中引入，并且需要Runner V1.2

before_script被用来定义一些需要在所有job之前执行的命令，包括发布job,但是在artifacts恢复之后。它可以是数组或者多行字符串。after_script被用来定义一些在所有job运行之后执行的命令，包括失败的那些。它必须是数组或者多行字符串。
before_script和主 script在一个上下文/容器中运行。after_script是分离运行的，所以根据执行程序的不同，在工作树之外的改变可能不可见。比如：在before_script安装软件。
它可以覆盖掉你在全局设置的before_script和after_script:

before_script:
  - global before script

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

stages

stages被用来在全局定义可用的job.
指定的stages允许拥有灵活的多个stage的pipelines。节点定义的顺序就是job执行的顺序：

1. 在同一个stage中指定的job将会同时运行。
2. 下一个stage将会在上一个stage完全成功后运行。

让我们思考如下示例，它定义了三个stage:

stages:
  - build
  - test
  - deploy

1. 首先，在build中的所有job将会同时运行。
2. 如果build中的所有job运行成功，则test中的所有job将会同时运行
3. 如果build中的所有job运行成功，则deploy中的job将会同时运行。
4. 如果deploy中的所有job运行成功，则commit将会标记为passed.
5. 如果任何一个之前的job执行失败，则commit将会被标记为失败，并且之后stage中的所有job都不会执行。

这里还有两个值得一提的边缘例子：

1. 如果.gitlab-ci.yml中没有定义stages，这样的话默认情况下build, test,deploy 可以在job的stage中被使用。
2. 如果job没有指定stage,那么job将被分配teststage.

stage

stage定义每一个job依赖的在全局stages中定义的stage.它允许一组job定义在不同的stage中，同一个stage中的job同时执行。比如：

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

types

Deprecated: types已经被弃用了，并且可能会在未来的某个版本中移除，用stages代替

script

script是job中唯一一个必须要有的。这是一段Runner执行的shell脚本。比如：

job:
  script: "bundle exec rspec"

此参数还可以用数组包含一系列命令脚本：

job:
  script:
    - uname -a
    - bundle exec rspec

有些时候，script脚本可能需要用单引号或者双引号来包裹。比如：命令包含冒号（:）需要用引号包裹这样的化YAML解析器在解析的时候知道这是一个字符串而不是"key:value"这样的键值对。使用这些特殊字符串的时候要小心: :, {, }, [, ], , &, *, #, ?, |, -, <, >, =, !, %, @, , `.

only 和 except (simplified)

only和except是用来设置job策略限时何时创建job的两个参数：

1. only定义job运行的分支的名字，或者定义为tags（译者注：打tag的时候会运行）
2. except定义不运行job的分支名称或者tags
   这里有一些规则适用于工作策略的使用：

• only和except都包括。如果only和except在一个job中都被定义，ref将会被only和except过滤。
• only和except允许使用常规表达式（使用Ruby regexp syntax).
• only和except允许指定仓库地址去过滤fork的仓库。
  另外，only和except允许使用特殊的关键字：

Value	Description
branched	当git refrence在pipeline中是一个分支的时候
tag	git refrence在pipeline中是一个tag的时候
api	当pipeline被第二个pipeline触发的api(不是触发API)
external	当使用的CI服务不是gitLab
pipelines	对于多项目触发，创建使用有CI_JOB_TOKEN的API
pushes	当用户使用git push的时候Pipeline触发
schedules	看（ scheduled pipelines）[https://docs.gitlab.com/ee/user/project/pipelines/schedules.html]

triggers: 使用trigger token创建pipelines
web|使用Gitlab UI上的Run pipeline创建pipeline（在你项目的Pipelines中）
merge_requests|当merge request被创建或者更新的时候（看pipelines for merge requests）

在下面的例子中，job只会在以issue-开头的refs中运行，然而所有的分支将会被跳过

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

在下面的例子中，job只会在被打过tag或者明确指定通过触发API请求构建或者Pipeline Schedule被的refs中被引用:

job:
  # use special keywords
  only:
    - tags
    - triggers
    - schedules

仓库地址能够被用来指定只有父仓库能够执行job而fork的不行：

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

上面的例子将会在gitlab-org/gitlab-ce的所有分支上运行job,而排除master分支
如果job既没有only也没有except规则，默认设置为：only: ['branches', 'tags']
比如：

job:
  script: echo 'test'

被翻译成：

job:
  script: echo 'test'
  only: ['branches', 'tags']

only 和 except (complex)

refs和kubernetes策略在Gitlab10.0中被引入
variables策略在10.7中被引用
changes策略在11.4中被引入

Warning:这是一个alpha的功能，它在任何时候都有可能在没有提前通知的情况下改变。

从Gitlab10.0开始only/except job策略可以被定义的更加细致。
Gitlab现在支持simple和complex两种策略，所以可以使用数组和哈希配置方案。
四个键现在是有效的refs,kubernetes,variables,changes.

refs 和 kubernetes

Refs策略和简单模式下的only/except配置一样，而kubernetes策略和只接受active关键字。

only:variables

variables关键字被用来定义变量表达式。换句话说可以被用来与定义变量/项目/组或者环境范围变量去定义一个表达式Gitlab将会去评估，决定job是否需要被创建。
看下面的例子。job只会在pipeline有scheduled或者运行的master分支，并且kubernetes在项目中是active的时候会被创建。

job:
  only:
    refs:
      - master
      - schedules
    kubernetes: active

变量表达式的例子：

deploy:
  script: cap staging deploy
  only:
    refs:
      - branches
    variables:
      - $RELEASE == "staging"
      - $STAGING

执行job依赖commit message的用例（在11.0中增加）：

end-to-end:
  script: rake test:end-to-end
  except:
    variables:
      - $CI_COMMIT_MESSAGE =~ /skip-end-to-end-tests/

学习更多的变量表达式在另一个单独的页面

only:changes

在only 或者except关键字使得根据git push的文件是否修改来判断job是否应该被创建成为可能。
比如：

docker build:
  script: docker build -t my-image:$CI_COMMIT_REF_SLUG .
  only:
    changes:
      - Dockerfile
      - docker/scripts/*
      - dockerfiles/**/*
      - more_scripts/*.{rb,py,sh}

在上面的例子中，如果你push 多个commit到GitLab现有的分支上，只要提供的commit中有一个包含以下改变，Gitlab将会创建并出发docker build:

• Dockerfile文件
• 任何在docker/scripts/文件夹下的文件
• 任何在dockerfiles文件夹下面的文件或者子文件夹
• 任何在more_scripts文件夹下以rb, py, sh为扩展名的文件

Warning:在新的分支或者tags上面使用这个功能的时候，这里有一些注意事项，看一下面一个章节。

在新的分支或者tags上面使用changes

如果你push新的分支或者tag到Gitlab上面，这个策略将会总是被评估为true,并且Gitlab将会创建job.到目前为止，这个功能还没有于merge requests联系在一起，因为GitLab创建pipeline是在用户创建merge request之前，在这个时候我们无法知道目标分支是哪个。
没有目标分支，不可能知道共同的祖先是谁，因此在这种情况下我们总是创建job.这个功能最好在稳定的分支上工作，因为在这中情况下Gitlab使用分支中上次commit的结果于这次push的SHA做比较。

tags

tags被用来从Runner列表中选择允许在这个项目中运行的Runner.
在注册Runner期间你可以指定Runner的tag,比如ruby, postgres, development.
tags允许你在job中运行指定的job:

job:
  tags:
    - ruby
    - postgres

在上面的例子中，我们确保job构建的Runner定义了ruby和postgres的标签。
Tags也是一个在不同的平台上运行不同job的好方法，比如给OSX Runner的tag赋值osx给Window Runner赋值windowstag,下面的job运行在各自的平台：

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

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