Gitlab CI 配置文件 .gitlab-ci.yaml 详解（上）

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...上查看使用Review Apps的简单示例。

继续阅读：Gitlab CI 配置文件 .gitlab-ci.yaml 详解（下）