gitlab 中extend与include的区别 gitlab ci when

本文档是描述 .gitlab-ci.yml 详细用法的下半部分，上半部分的内容请参考这里。.gitlab-ci.yml 文件被用来管理项目的 runner 任务。如果想要快速的了解GitLab CI ，可查看快速引导。 该文件存放于项目仓库的根目录，它定义该项目如何构建。

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(<

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:
<<: merge the contents of alias>
script:
- test1 project
test2:
<<: merge the contents of alias>
script:
- test2 project
&在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:
<<:>
services: *postgres_definition
test:mysql:
<<:>
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
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用法示例。