本文档是描述 .gitlab-ci.yml 详细用法的下半部分，上半部分的内容请参考这里。.gitlab-ci.yml 文件被用来管理项目的 runner 任务。如果想要快速的了解GitLab CI ，可查看快速引导。 该文件存放于项目仓库的根目录，它定义该项目如何构建。
参考阅读：Gitlab CI 配置文件 .gitlab-ci.yaml 详解（上）
artifacts
注意：
- 非Windows平台从GitLab Runner v0.7.0中引入。
- Windows平台从GitLab Runner V1.0.0中引入。
- 在GItLab 9.2之前，在artifacts之后存储缓存。
- 在GItLab 9.2之后，在artifacts之前存储缓存。
- 目前并不是所有的executors都支持。
- 默认情况下，job artifacts 只正对成功的jobs收集。
artifacts用于指定成功后应附加到job的文件和目录的列表。只能使用项目工作间内的文件或目录路径。如果想要在不通的job之间传递artifacts，请查阅依赖关系。以下是一些例子：
发送binaries和.config中的所有文件：
artifacts:
paths:
- binaries/
- .config
发送所有没有被Git跟踪的文件：
artifacts: untracked: true
发送没有被Git跟踪和binaries中的所有文件：
artifacts: untracked: true paths: - binaries/
定义一个空的dependencies可以禁用artifact传递：
job:
stage: build
script: make build
dependencies: []
有时候只需要为标签为releases创建artifacts，以避免将临时构建的artifacts传递到生产服务器中。
只为tags创建artifacts（default-job将不会创建artifacts）：
default-job:
script:
- mvn test -U
except:
- tags
release-job:
script:
- mvn package -U
artifacts:
paths:
- target/*.war
only:
- tags
在job成功完成后artifacts将会发送到GitLab中，同时也会在GitLab UI中提供下载。
artifacts:name
GitLab 8.6 和 Runner v1.1.0 引入。
name允许定义创建的artifacts存档的名称。这样一来，我们可以为每个存档提供一个唯一的名称，当需要从GitLab中下载是才不会混乱。artifacts:name可以使用任何的预定义变量(predefined variables)。它的默认名称为artifacts，当下载是就变成了artifacts.zip。
配置示例
通过使用当前job的名字作为存档名称：
job:
artifacts:
name: "$CI_JOB_NAME"
使用当前分支名称或者是tag作为存到名称，只存档没有被Git跟踪的文件：
job:
artifacts:
name: "$CI_COMMIT_REF_NAME"
untracked: true
使用当前job名称和当前分支名称或者是tag作为存档名称，只存档没有被Git跟踪的文件：
job:
artifacts:
name: "${CI_JOB_NAME}_${CI_COMMIT_REF_NAME}"
untracked: true
使用当前stage和分支名称作为存档名称：
job:
artifacts:
name: "${CI_JOB_STAGE}_${CI_COMMIT_REF_NAME}"
untracked: true
如果是使用Windows批处理来运行yaml脚本，需要用%替换$：
job:
artifacts:
name: "%CI_JOB_STAGE%_%CI_COMMIT_REF_NAME%"
untracked: true
artifacts:when
GitLab 8.9和GitLab Runner v1.3.0 引入。
在job失败的时候，artifacts:when用来上传artifacts或者忽略失败。
artifacts:when可以设置一下值：
on_success- 当job成功的时候上传artifacts。默认值。on_failure- 当job失败的时候上传artifacts。always- 不论job失败还是成功都上传artifacts。
示例配置
只在job失败的时候上传artifacts。
job:
artifacts:
when: on_failure
artifacts:expire_in
GitLab 8.9 和 GitLab Runner v1.3.0 引入。
artifacts:expire_in用于过期后删除邮件上传的artifacts。默认情况下，artifacts都是在GitLab中永久保存。expire_in允许设置设置artifacts的存储时间，从它们被上传存储到GitLab开始计算。
可以通过job页面的Keep来修改有效期。
过期后，artifacts会被通过一个默认每小时执行一次的定时job删除，所以在过期后无法访问artifacts。
expire_in是一个时间区间。下面可设置的值：
- '3 mins 4 sec'
- '2 hrs 20 min'
- '2h20min'
- '6 mos 1 day'
- '47 yrs 6 mos and 4d'
- '3 weeks and 2 days'
示例配置
设置artifacts的有效期为一个星期：
job:
artifacts:
expire_in: 1 week
dependencies
GitLab 8.6 和 GitLab RUnner v1.1.1引入。
这个功能应该与artifacts一起使用，并允许定义在不同jobs之间传递artifacts。
注意：所有之前的stages都是默认设置通过。
如果要使用此功能，应该在上下文的job中定义dependencies，并且列出之前都已经通过的jobs和可下载的artifacts。你只能在当前执行的stages前定义jobs。你如果在当前stages或者后续的stages中定义了jobs，它将会报错。可以通过定义一个空数组是当前job跳过下载artifacts。
在接下来的例子中，我们定义两个带artifacts的jobs，build:osx和build:linux。当test:osx开始执行的时候，build:osx的artifacts就会开始下载并且会在build的stages下执行。同样的会发生在test:linux，从build:linux中下载artifacts。
因为stages的优先级关系，deployjob将会下载之前jobs的所有artifacts：
build:osx:
stage: build
script: make build:osx
artifacts:
paths:
- binaries/
build:linux:
stage: build
script: make build:linux
artifacts:
paths:
- binaries/
test:osx:
stage: test
script: make test:osx
dependencies:
- build:osx
test:linux:
stage: test
script: make test:linux
dependencies:
- build:linux
deploy:
stage: deploy
script: make deploy
before_script 和 after_script
它可能会覆盖全局定义的before_script和after_script：
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
coverage
注意：GitLab 8.17 中 引入。
coverage允许你配置代码覆盖率将会从该job中提取输出。
在这里正则表达式是唯一有效的值。因此，字符串的前后必须使用/包含来表明一个正确的正则表达式规则。特殊字符串需要转义。
一个简单的例子：
job1: coverage: '/Code coverage: \d+\.\d+/'
Git Strategy
GitLab 8.9中以试验性功能引入。将来的版本中可能改变或完全移除。
GIT_STRATEGY要求GitLab Runner v1.7+。
你可以通过设置GIT_STRATEGY用于获取最新的代码，可以再全局variables或者是在单个job的variables模块中设置。如果没有设置，将从项目中使用默认值。
可以设置的值有：clone，fetch，和none。
clone是最慢的选项。它会从头开始克隆整个仓库，包含每一个job，以确保项目工作区是最原始的。
variables: GIT_STRATEGY: clone
当它重新使用项目工作区是，fetch是更快（如果不存在则返回克隆）。git clean用于撤销上一个job做的任何改变，git fetch用于获取上一个job到现在的的commit。
variables:
GIT_STRATEGY: fetch
none也是重新使用项目工作区，但是它会跳过所有的Git操作（包括GitLab Runner前的克隆脚本，如果存在的话）。它主要用在操作job的artifacts（例如：deploy）。Git数据仓库肯定是存在的，但是他肯定不是最新的，所以你只能依赖于从项目工作区的缓存或者是artifacts带来的文件。
variables:
GIT_STRATEGY: none
Git Checout
GitLab Runner 9.3 引入。
当GIT_STRATEGY设置为clone或fetch时，可以使用GIT_CHECKOUT变量来指定是否应该运行git checkout。如果没有指定，它默认为true。就像GIT_STRATEGY一样，它可以设置在全局variables或者是单个job的variables中设置。
如果设置为false，Runner就会：
fetch- 更新仓库并在当前版本中保留工作副本，clone- 克隆仓库并在默认分支中保留工作副本。
Having this setting set to true will mean that for both clone and fetch strategies the Runner will checkout the working copy to a revision related to the CI pipeline:
【如果设置这个为true将意味着clone和fetch策略都会让Runner执行项目工作区更新到最新：】
variables: GIT_STRATEGY: clone GIT_CHECKOUT: false script: - git checkout master - git merge $CI_BUILD_REF_NAME
Git Submodule Strategy
需要GitLab Runner v1.10+。
GIT_SUBMODULE_STRATEGY变量用于在构建之前拉取代码时，Git子模块是否或者如何被引入。就像GIT_STRATEGY一样，它可在全局variables或者是单个job的variables模块中设置。
它的可用值有：none，normal和recursive：
none意味着在拉取项目代码时，子模块将不会被引入。这个是默认值，与v1.10之前相同的。normal意味着在只有顶级子模块会被引入。它相当于：
git submodule sync
git submodule update --init
recursive意味着所有的子模块（包括子模块的子模块）都会被引入，他相当于：
git submodule sync --recursive
git submodule update --init --recursive
注意：如果想要此功能正常工作，子模块必须配置（在.gitmodules）下面中任意一个：
- 可访问的公共仓库http(s)地址，
- 在同一个GitLab服务器上有一个可访问到另外的仓库的真实地址。更多查看Git 子模块文档。
Job stages attempts
GitLab引入，要求GItLab Runner v1.9+。
正在执行的job将会按照你设置尝试次数依次执行下面的stages：
| 变量 | 描述 |
|---|---|
| GET_SOURCES_ATTEMPTS | 获取job源的尝试次数 |
| ARTIFACT_DOWNLOAD_ATTEMPTS | 下载artifacts的尝试次数 |
| RESTORE_CACHE_ATTEMPTS | 重建缓存的尝试次数 |
默认是一次尝试。
例如：
variables:
GET_SOURCES_ATTEMPTS: 3
你可以在全局variables模块中设置，也可以在单个job的variables模块中设置。
Shallow cloning
GitLab 8.9 以实验性功能引入。在将来的版本中有可能改变或者完全移除。
你可以通过GIT_DEPTH来指定抓取或克隆的深度。它可浅层的克隆仓库，这可以显著加速具有大量提交和旧的大型二进制文件的仓库的克隆。这个设置的值会传递给git fetch和git clone。
注意：如果设置depth=1，并且有一个jobs队列或者是重试jobs，则jobs可能会失败。
由于Git抓取和克隆是基于一个REF，例如分支的名称，所以Runner不能指定克隆一个commit SHA。如果队列中有多个jobs，或者您正在重试旧的job，则需要测试的提交应该在克隆的Git历史记录中存在。设置GIT_DEPTH太小的值可能会导致无法运行哪些旧的commits。在job日志中可以查看unresolved reference。你应该考虑设置GIT_DEPTH为一个更大的值。
当GIT_DEPTH只设置了部分存在的记录时，哪些依赖于git describe的jobs也许不能正确的工作。
只抓取或克隆最后的3次commits：
variables: GIT_DEPTH: "3"
Hidden keys
GitLab 8.6 和 GitLab Runner v1.1.1引入。
Key 是以.开始的，GitLab CI 将不会处理它。你可以使用这个功能来忽略jobs，或者用Special YAML features 转换隐藏键为模版。
在下面这个例子中，.key_name将会被忽略：
.key_name:
script:
- rake spec
Hidden keys 可以是像普通CI jobs一样的哈希值，但你也可以利用special YAMLfeatures来使用不同类型的结构。
Special YAML features
使用special YAML features 像anchors(&)，aliases(*)和map merging(<<)，这将使您可以大大降低.gitlab-ci.yml的复杂性。查看更多YAML features。
Anchors
GitLab 8.6 和 GitLab Runner v1.1.1引入。
YAML有个方便的功能称为"锚",它可以让你轻松的在文档中复制内容。Anchors可用于复制/继承属性，并且是使用hidden keys来提供模版的完美示例。
下面这个例子使用了anchors和map merging。它将会创建两个jobs，test1和test2，该jobs将集成.job_template的参数，每个job都自定义脚本：
.job_template: &job_definition # Hidden key that defines an anchor named 'job_definition'
image: ruby:2.1
services:
- postgres
- redis
test1:
<<: *job_definition # Merge the contents of the 'job_definition' alias
script:
- test1 project
test2:
<<: *job_definition # Merge the contents of the 'job_definition' alias
script:
- test2 project
&在anchor的名称(job_definition)前设置，<<表示"merge the given hash into the current one"，*包括命名的anchor(job_definition)。扩展版本如下：
.job_template:
image: ruby:2.1
services:
- postgres
- redis
test1:
image: ruby:2.1
services:
- postgres
- redis
script:
- test1 project
test2:
image: ruby:2.1
services:
- postgres
- redis
script:
- test2 project
让我们来看另外一个例子。这一次我们将用anchors来定义两个服务。两个服务会创建两个job，test:postgres和test:mysql，他们会在.job_template中共享定义的script指令，以及分别在.postgres_services和.mysql_services中定义的service指令：
.job_template: &job_definition
script:
- test project
.postgres_services:
services: &postgres_definition
- postgres
- ruby
.mysql_services:
services: &mysql_definition
- mysql
- ruby
test:postgres:
<<: *job_definition
services: *postgres_definition
test:mysql:
<<: *job_definition
services: *mysql_definition
扩展版本如下：
.job_template:
script:
- test project
.postgres_services:
services:
- postgres
- ruby
.mysql_services:
services:
- mysql
- ruby
test:postgres:
script:
- test project
services:
- postgres
- ruby
test:mysql:
script:
- test project
services:
- mysql
- ruby
你可以看到hidden keys被方便的用作模版。
Triggers
Triggers 可用于强制使用API调用重建特定分支，tag或commits。在triggers文档中查看更多。
pages
pages是一个特殊的job，用于将静态的内容上传到GitLab，可用于为您的网站提供服务。它有特殊的语法，因此必须满足以下两个要求：
- 任何静态内容必须放在
public/目录下 artifacts必须定义在public/目录下
下面的这个例子是将所有文件从项目根目录移动到public/目录。.public工作流是cp，并且它不会循环复制public/本身。
pages:
stage: deploy
script:
- mkdir .public
- cp -r * .public
- mv .public public
artifacts:
paths:
- public
only:
- master
更多内容请查看GitLab Pages用户文档。
Validate the .gitlab-ci.yml
GitLab CI的每个实例都有一个名为Lint的嵌入式调试工具。 你可以在gitlab实例的/ci/lint下找到该链接。
Skipping jobs
如果你的commit信息中包含[ci skip]或者[skip ci]，不论大小写，那么这个commit将会创建但是jobs也会跳过。
Examples
访问examples README来查看各种语言的GitLab CI用法示例。
