在.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行为的参数定义而成。

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允许使用特殊的关键字：

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!"