此文档用于描述. gitlab-ci.yml 语法，.gitlab-ci.yml 文件被用来管理项目的 runner 任务。
如果想要快速的了解 GitLab CI ，可查看快速引导。

.gitlab-ci.yml

从 7.12 版本开始，GitLab CI 使用 YAML 文件 (.gitlab-ci.yml) 来管理项目配置。该文件存放于项目仓库的根目录，它定义该项目如何构建。

开始构建之前 YAML 文件定义了一系列带有约束说明的任务。这些任务都是以任务名开始并且至少要包含script部分：

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

上面这个例子就是一个最简单且带有两个独立任务的 CI 配置，每个任务分别执行不同的命令。

script可以直接执行系统命令 (例如：./configure;make;make install) 或者是直接执行脚本(test.sh)。

任务是由 Runners 接管并且由服务器中 runner 执行。更重要的是，每一个任务的执行过程都是独立运行的。

用下面这个例子来说明 YAML 语法还有更多复杂的任务：

image: ruby:2.1
services:
  - postgres

before_script:
  - bundle install

after_script:
  - rm secrets

stages:
  - build
  - test
  - deploy

job1:
  stage: build
  script:
    - execute-script-for-job1
  only:
    - master
  tags:
    - docker

下面列出保留字段，这些保留字段不能被定义为job名称：

关键字	是否必须	描述
image	否	用于 docker 镜像，查看 docker 文档
services	否	用于 docker 服务，查看 docker 文档
stages	否	定义构建阶段
types	否	stages 的别名 (已废除)
before_script	否	定义在每个 job 之前运行的命令
after_script	否	定义在每个 job 之后运行的命令
variable	否	定义构建变量
cache	否	定义一组文件列表，可在后续运行中使用

image 和 services

这两个关键字允许使用一个自定义的 Docker 镜像和一系列的服务，并且可以用于整个 job 周期。详细配置文档请查看 a separate document。

before_script

before_script用来定义所有 job 之前运行的命令，包括 deploy(部署) jobs，但是在修复 artifacts 之后。它可以是一个数组或者是多行字符串。

after_script

GitLab 8.7 开始引入，并且要求 Gitlab Runner v1.2

after_script用来定义所有 job 之后运行的命令。它必须是一个数组或者是多行字符串

stages

stages用来定义可以被 job 调用的 stages。stages 的规范允许有灵活的多级 pipelines。

stages 中的元素顺序决定了对应 job 的执行顺序：

1. 相同stage的job可以平行执行。
2. 下一个stage的job会在前一个stage的job成功后开始执行。

接下仔细看看这个例子，它包含了 3 个 stage：

stages:
 - build
 - test
 - deploy

1. 首先，所有build的 jobs 都是并行执行的。
2. 所有build的 jobs 执行成功后，test的 jobs 才会开始并行执行。
3. 所有test的 jobs 执行成功，deploy的 jobs 才会开始并行执行。
4. 所有的deploy的 jobs 执行成功，commit 才会标记为success
5. 任何一个前置的 jobs 失败了，commit 会标记为failed并且下一个 stages 的 jobs 都不会执行。

这有两个特殊的例子值得一提：

1. 如果.gitlab-ci.yml中没有定义stages，那么 job's stages 会默认定义为 build，test 和 deploy。
2. 如果一个 job 没有指定stage，那么这个任务会分配到test stage。

types

已废除，将会在 10.0 中移除。用 stages 替代。

与 stages 同义

variables

GitLab Runner V0.5.0. 开始引入

GItLab CI 允许在.gitlab-ci.yml文件中添加变量，并在 job 环境中起作用。因为这些配置是存储在 git 仓库中，所以最好是存储项目的非敏感配置，例如：

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

这些变量可以被后续的命令和脚本使用。服务容器也可以使用 YAML 中定义的变量，因此我们可以很好的调控服务容器。变量也可以定义成 job level。

除了用户自定义的变量外，Runner 也可以定义它自己的变量。CI_COMMIT_REG_NAME就是一个很好的例子，它的值表示用于构建项目的分支或 tag 名称。除了在.gitlab-ci.yml中设置变量外，还有可以通过 GitLab 的界面上设置私有变量。

更多关于 variables。

cache

Gitlab Runner v0.7.0 开始引入。

cache用来指定需要在 job 之间缓存的文件或目录。只能使用该项目工作空间内的路径。

从 GitLab 9.0 开始，pipelines 和 job 就默认开启了缓存

如果cache定义在 jobs 的作用域之外，那么它就是全局缓存，所有 jobs 都可以使用该缓存。

缓存binaries和.config中的所有文件：

rspec:
  script: test
  cache:
    paths:
    - binaries/
    - .config

缓存 git 中没有被跟踪的文件：

rspec:
  script: test
  cache:
    untracked: true

缓存binaries下没有被 git 跟踪的文件：

rspec:
  script: test
  cache:
    untracked: true
    paths:
    - binaries/

job 中优先级高于全局的。下面这个rspecjob 中将只会缓存binaries/下的文件：

cache:
  paths:
  - my/files

rspec:
  script: test
  cache:
    key: rspec
    paths:
    - binaries/

注意，缓存是在 jobs 之前进行共享的。如果你不同的 jobs 缓存不同的文件路径，必须设置不同的 cache:key，否则缓存内容将被重写。

缓存只是尽力而为之，所以别期望缓存会一直存在。查看更多详细内容，请查阅 GitLab Runner。

缓存 key

GitLab Runner v1.0.0 开始引入。

key指令允许我们定义缓存的作用域 (亲和性)，可以是所有 jobs 的单个缓存，也可以是每个 job，也可以是每个分支或者是任何你认为合适的地方。

它也可以让你很好的调整缓存，允许你设置不同 jobs 的缓存，甚至是不同分支的缓存。

cache:key可以使用任何的预定义变量。

默认 key 是默认设置的这个项目缓存，因此默认情况下，每个 pipelines 和 jobs 中可以共享一切，从 GitLab 9.0 开始。

配置示例

缓存每个 job：

cache:
  key: "$CI_JOB_NAME"
  untracked: true

缓存每个分支：

cache:
  key: "$CI_COMMIT_REF_NAME"
  untracked: true

缓存每个 job 且每个分支：

cache:
  key: "$CI_JOB_NAME/$CI_COMMIT_REF_NAME"
  untracked: true

缓存每个分支且每个 stage：

cache:
  key: "$CI_JOB_STAGE/$CI_COMMIT_REF_NAME"
  untracked: true

如果使用的 Windows Batch(windows 批处理) 来跑脚本需要用%替代$：

cache:
  key: "%CI_JOB_STAGE%/%CI_COMMIT_REF_NAME%"
  untracked: true

Jobs

.gitlab-ci.yml允许指定无限量 jobs。每个 jobs 必须有一个唯一的名字，而且不能是上面提到的关键字。job 由一列参数来定义 jobs 的行为。

job_name:
  script:
    - rake spec
    - coverage
  stage: test
  only:
    - master
  except:
    - develop
  tags:
    - ruby
    - postgres
  allow_failure: true

Keyword	Required	Description
script	yes	Runner 执行的命令或脚本
image	no	所使用的 docker 镜像，查阅使用 docker 镜像
services	no	所使用的 docker 服务，查阅使用 docker 镜像
stage	no	定义 job stage（默认：test）
type	no	stage的别名（已弃用）
variables	no	定义 job 级别的变量
only	no	定义一列 git 分支，并为其创建 job
except	no	定义一列 git 分支，不创建 job
tags	no	定义一列 tags，用来指定选择哪个 Runner（同时 Runner 也要设置 tags）
allow_failure	no	允许 job 失败。失败的 job 不影响 commit 状态
when	no	定义何时开始 job。可以是on_success，on_failure，always或者manual
dependencies	no	定义 job 依赖关系，这样他们就可以互相传递 artifacts
cache	no	定义应在后续运行之间缓存的文件列表
before_script	no	重写一组在作业前执行的命令
after_script	no	重写一组在作业后执行的命令
environment	no	定义此作业完成部署的环境名称
coverage	no	定义给定作业的代码覆盖率设置

script

script是 Runner 执行的 yaml 脚本。举个例子：

job:
  script: "bundle exec rspec"

该参数也可以用数组包含多个命令：

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

有时候，script命令需要被单引号或者是双引号包裹起来。举个例子，当命令中包含冒号 (:) 时，script 需要被包在双引号中，这样 YAML 解析器才可以正确解析为一个字符串而不是一个键值对 (key:value)。使用这些特殊字符的时候一定要注意：:,{,},[,],,,&,*,#,?,|,-,<,>,=,!。

stage

stage允许一组 jobs 进入不同的 stages。jobs 在相同的stage时会parallel同时进行。查阅stages更多的用法请查看 stages。

only and except

only和 except 是两个参数用分支策略来限制 jobs 构建：

1. only定义哪些分支和标签的 git 项目将会被 job 执行。
2. except定义哪些分支和标签的 git 项目将不会被 job 执行。

下面是 refs 策略的使用规则：

• only和except可同时使用。如果only和except在一个 job 配置中同时存在，则以only为准，跳过except(从下面示例中得出)。
• only和except可以使用正则表达式。
• only和except允许使用特殊的关键字：branches，tags和triggers。
• only和except允许使用指定仓库地址但不是 forks 的仓库 (查看示例 3)。

在下面这个例子中，job将只会运行以issue-开始的 refs(分支)，然而 except 中设置将被跳过。

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

在下面这个例子中，job将只会执行有 tags 的 refs，或者通过 API 触发器明确地请求构建。

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

仓库路径只能用于父级仓库执行 jobs，而不是 forks：

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

上面这个例子将会为所有的分支执行job，但 master 分支除外。

Job variables

在 job 中是可以使用关键字variables来定义 job 变量。它的运行原理跟 global-level 是一样的，但是它允许设置特殊的 job 变量。

当设置了 job 级别的关键字variables，它会覆盖全局 YAML 和预定义中的 job 变量。想要关闭全局变量可以在 job 中设置一个空数组：

job_name:
  variables: []

Job 变量的优先级关系可查看 variables 文档说明。

tags

tags可以从允许运行此项目的所有 Runners 中选择特定的 Runners 来执行 jobs。

在注册 Runner 的过程中，我们可以设置 Runner 的标签，比如ruby，postgres，development。

tags可通过 tags 来指定特殊的 Runners 来运行 jobs：

job:
  tags:
    - ruby
    - postgres

上面这个示例中，需要确保构建此job的 Runner 必须定义了ruby和postgres这两个 tags。

allow_failure

allow_failure可以用于当你想设置一个 job 失败的之后并不影响后续的 CI 组件的时候。失败的 jobs 不会影响到 commit 状态。

当开启了允许 job 失败，所有的 intents 和 purposes 里的 pipeline 都是成功 / 绿色，但是也会有一个 "CI build passed with warnings" 信息显示在 merge request 或 commit 或 job page。这被允许失败的作业使用，但是如果失败表示其他地方应采取其他（手动）步骤。

下面的这个例子中，job1和job2将会并列进行，如果job1失败了，它也不会影响进行中的下一个 stage，因为这里有设置了allow_failure: true。

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 is used to implement jobs that are run in case of failure or despite the failure.

when可以设置以下值：

1. on_success - 只有前面 stages 的所有工作成功时才执行。 这是默认值。
2. on_failure - 当前面 stages 中任意一个 jobs 失败后执行。
3. always - 无论前面 stages 中 jobs 状态如何都执行。
4. `manual ` - 手动执行 (GitLab8.10 增加)。更多请查看手动操作。

举个例子：

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

脚本说明：

1. 只有当build_job失败的时候才会执行`cleanup_build_job 。
2. 不管前一个 job 执行失败还是成功都会执行`cleanup_job 。
3. 可以从 GitLab 界面中手动执行deploy_jobs。

Manual actions

GitLab 8.10 开始引入手动执行。GitLab 9.0 开始引入手动停止。GitLab 9.2 开始引入保护手动操作。

手动操作指令是不自动执行的特殊类型的 job；它们必须要人为启动。手动操作指令可以从 pipeline，build，environment 和 deployment 视图中启动。

部署到生产环境是手动操作指令的一个很好示例。

了解更多请查看 environments documentation。

手动操作指令可以是可选的或阻塞。在定义了手动执行的那个 stage 中，手动操作指令将会停止 pipline 中的自动执行指令。当有人通过点击 play 按钮来执行需要手动执行的 job 时，可以来恢复 pipeline 的执行。

当 pipeline 被阻塞时，即使是 pipeline 是成功状态也不会 merge。被阻塞的 pipelines 也有一个特殊的状态，叫manual。

手动操作指令默认是不阻塞的。如果你想要手动操作指令产生阻塞，首先需要在 job 的配置文件.gitlab-ci.yml中添加allow_failure:false。

可选的手动操作指令默认设置allow_failure:true。

可选动作的状态不影响整个 pipeline 的状态。

手动操作指令被认为是写操作，所以当前用户触发操作时，必须拥有操作保护分支的权限。换句话说，为了触发一个手动操作指令到 pipeline 中正在运行的指定分支，当前用户必须拥有推送到这分支的权限。

enviroment

注意：

• GitLab 8.9 开始引入。
• 更多关于 environment 说明或者示例可以查看 documentation about environments。

environment用于定义 job 部署到特殊的环境中。如果指定了environment，并且没有该名称下的环境，则会自动创建新环境。

在最简单的格式中，环境关键字可以定义为：

deploy to production:
  stage: deploy
  script: git push production HEAD:master
  environment:
    name: production

在上面这个例子中，deploy to profuctionjob 将会执行部署到production环境的操作。

environment:name

注意

• GitLab 8.11 开始引入。
• 在 GitLab8.11 之前，环境名称定义为environment:production。现在推荐的做法是定义为name关键字。

environment名称可以包含：

• 英文字母 (letters)
• 数字 (digits)
• 空格 (spaces)
• -
• _
• /
• $
• {
• }

常用的名称有qa,staging，和production，当然你可以在你的工作流中使用任意名字。

除了在environment关键字右边紧跟 name 定义方法外，也是可以为环境名称单独设定一个值。例如，用name关键字在environment下面设置：

deploy to production:
  stage: deploy
  script: git push production HEAD:master
  environment:
    name: production

environment:url

注意：

• GitLab 8.11 开始引用。
• 在 GitLab 8.11 之前，URL 只能在 GitLab's UI 中添加。现在推荐的定义方法是在.gitlab-ci.yml。

这是设置一个可选值，它会显示在按钮中，点击它可以带你到设置的 URL 页面。

在下面这个例子中，如果 job 都成功完成了，在 environment/deployments 页面中将会创建一个合并请求的按钮，它将指向https://prod.example.com。

deploy to production:
  stage: deploy
  script: git push production HEAD:master
  environment:
    name: production
    url: https://prod.example.com

environment:on_stop

注意：

• GitLab 8.13 中开始引入。
• 从 GitLab 8.14 开始，当在 environment 中定义了一个 stop 操作，GitLab 将会在相关联的分支本删除时自动触发一个 stop 操作。

关闭 (停止)environments 可以通过在environment下定义关键字on_stop来实现。它定义了一个不同的 job，用于关闭 environment。

请查看environment:action模块中例子。

environment:action

Gitlab 8.13 开始引入。

action和on_stop联合使用，定义在 job 中，用来关闭 environment。

举个例子：

review_app:
  stage: deploy
  script: make deploy-app
  environment:
    name: review
    on_stop: stop_review_app

stop_review_app:
  stage: deploy
  script: make delete-app
  when: manual
  environment:
    name: review
    action: stop

上面这个例子中，我们定义了review_appjob 来部署到review环境中，同时我们也定义了一个新stop_review_appjob 在on_stop中。一旦review_appjob 执行完成并且成功，它将触发定义在when中的stop_review_appjob。在这种情况下，我们设置为manual，需要通过 GitLab's web 界面来允许 manual action。

stop_review_appjob 需要定义下面这些关键字：

• when - 说明
• environment:name
• environment:action
• stage需要和review_app相同，以便分支删除被删除的时候自动执行停止。

dynamic environment

注意：

• GitLab 8.12 开始引入，并且要求 GitLab Runner 1.6 。
• GitLab 8.15 开始引入$CI_ENVIRONMENT_SLUG。

environment也可以是代表配置项，其中包含name和url。这些参数可以使用任何的 CI variables(包括预定义、安全变量和.gitlab-ci.yml中的变量)。

举个例子：

deploy as review app:
  stage: deploy
  script: make deploy
  environment:
    name: review/$CI_COMMIT_REF_NAME
    url: https://$CI_ENVIRONMENT_SLUG.example.com/

当$CI_COMMIT_REF_NAME 被 Runner 设置为 environment variable 时，deply as review appjob 将会被指定部署到动态创建revuew/$CI_COMMIT_REF_NAME的环境中。$CI_ENVIRONMENT_SLUG变量是基于环境名称的，最终组合成完整的 URLs。在这种情况下，如果deploy as review appjob 是运行在名称为pow的分支下，那么可以通过 URLhttps"//review-pw.example.com/来访问这个环境。

这当然意味着托管应用程序的底层服务器已经正确配置。

常见的做法是为分支创建动态环境，并讲它们作为 Review Apps。可以通过 https://gitlab.com/gitlab-exa... Apps 的简单示例。

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可以设置一下值：

1. on_success - 当 job 成功的时候上传 artifacts。默认值。
2. on_failure - 当 job 失败的时候上传 artifacts。
3. 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，可用于为您的网站提供服务。它有特殊的语法，因此必须满足以下两个要求：

1. 任何静态内容必须放在public/目录下
2. 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 用法示例。

官方文档地址：https://docs.gitlab.com/ce/ci...