gitlab-ci.yml配置说明(官方文档翻译)

人工翻译自官方文档:https://docs.gitlab.com/ce/ci/yaml/README.html
欢迎转载,请注明出处:https://github.com/szyhf/gitlab-study

本文整理了.gitlab-ci.yml的使用方式,这个文件被GitLabRunner用于管理项目的构建。

.gitlab-ci.yml

.gitlab-ci.yml是从7.12版本开始启用的项目CI配置文件,本文件应该放在项目的根目录中,里边描述了你的项目应该如何构建。

一个yaml文件定义了一组各不相同的job,并定义了它们应该怎么运行。这组jobs会被定义为yaml文件的顶级元素,并且每个job的子元素中总有一个名为script的节点。

A set of jobs,强调是Set所以名称必须不同。

job1:
    script: "job1的执行脚本命令(shell)“

job2:
    script:
        - "job2的脚本命令1(shell)"
        - “job2的脚本命令2(shell)”

上述的文件是最简单的CI配置例子,每个job都执行了不同的命令,其中job1只执行了1条命令,job2通过数组的定义按顺序执行了两条命令。

当然,每个命令可以直接执行代码(./configure;make;make install)或者在仓库目中运行另一个脚本(test.sh)。

Job配置会被Runner读取并用于构建项目,并且在Runner的环境中被执行。很重要的一点是,每个job都会独立的运行,相互间并不依赖。

Each job is run independently from each other.

下边是一个比较复杂的CI配置文件例子:

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 )作为Excutor时有效}
services 使用的Docker服务,使用Docker 作为Excutor时有效
stages 定义构建的stages
types stages的别名
before_script 定义所有job执行之前需要执行的脚本命令
after_script 定义所有job执行完成后需要执行的脚本命令
variables 定义构建变量
cache 定义一组文件,该组文件会在运行时被缓存,下次运行仍然可以使用

image和services

这两个关键字允许用户自定义运行时使用的Docker image,及一组可以在构建时使用的Service。这个特性的详细说明在 Docker integration - GitLab Documentation中。

before_script

被用于定义所有job被执行之前的命令,包括部署构建环境。它可以是一个数组元素或者一个多行文本元素。

after_script

Gitlab8.7及GitlabRunner1.2以上才支持本关键字

被用于定义所有job被执行完之后要执行的命令。同样可以是一个数组或者一个多行文本。

stages

用于定义可以被job使用的stage. 定义stages可以实现柔性的多stage执行管道。

The specification of stages allows for having flexible multi stage pipelines.

stages定义的元素顺序决定了构建的执行顺序:

  1. 同样stage的job是并行执行的。
  2. 下一个stage的jobs是当上一个stage的josb全部执行成功后才会执行。

让我们看一个简单的例子,以下有3个stage:

stages:
    - build
    - test
    - deploy
  1. 首先,所有stage属性为build的job会被并行执行.
  2. 如果所有stage属性为build的job都执行成功了,stage为test的job会被并行执行。
  3. 如果所有stage为test的job都执行成功了,则stage为deploy的job会被并行执行。
  4. 如果所有stage为deploy的job都执行成功了,则提交被标记为success。
  5. 如果任何一个前置job失败了,则提交被标记为failed并且任何下一个stage的job都不会被执行。

两个有价值的提示:

  1. 如果配置文件中没有定义stages,那么默认情况下的stages属性为build、test和deploy。
  2. 如果一个job没有定义stage属性,则它的stage属性默认为test。

types

stages的别名。

variables

从Runner0.5.0开始支持

GitlabCI允许你在.gitlab-ci.yml文件中设置构建环境的环境变量。这些变量会被存储在git仓库中并用于记录不敏感的项目配置信息,例如:

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

这些变量会在之后被用于执行所有的命令和脚本。Yaml配置的变量同样会被设置于所有被建立的service容器中,这可以让使用更加方便。variables同样可以设置为job级别的属性。

除了用户自定义的变量外,同样有Runner自动设置的变量。例如说CI_BUILD_REF_NAME,这个变量定义了正在构建的git仓库的branch或者tag的名称。

除了在.gitlab-ci.yml中设置的非敏感变量外,Gitlab的UI中还提供了设置敏感变量的功能。

更多关于变量的说明

cache

Runner0.7.0之后被介绍

用于定义一系列需要在构建时被缓存的文件或者目录。只能定义在项目工作环境中的目录或者文件。

cache is used to specify a list of files and directories which should be cached between builds.

默认情况下缓存功能是对每个job和每个branc都开启的。

如果cache在job元素之外被蒂尼,这意味着全局设置,并且所有的job会使用这个设置。以下是一些例子:

  • 缓存所有在binaries目录中的文件和.config文件:
rspec:
  script: test
  cache:
    paths:
    - binaries/
    - .config
  • 缓存所有git未追踪的文件
rspec:
  script: test
  cache:
    untracked: true
  • 缓存所有git未追踪的文件和在binaries目录下的文件
rspec:
  script: test
  cache:
    untracked: true
    paths:
    - binaries/
  • job级别定义的cache设置会负载全局级别的cache配置。该例子将仅缓存目录binaries
cache:
  paths:
  - my/files

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

cache功能仅提供最努力的支持,但不要指望它总能生效。更多的实现细节,可以参阅GitlabRunner。

The cache is provided on a best-effort basis, so don't expect that the cache will be always present.

cache:key

Runner1.0.0中被介绍

key允许你在不同的job之间定义cache的种类,例如所有job共享的cache单例、一个job一个的cache、一个branch一个的cache等等。

这允许你更便利的使用缓存,允许你在不同的job甚至不同的branche间共享缓存。

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

例子

  • 缓存每个job
cache:
  key: "$CI_BUILD_NAME"
  untracked: true

缓存每个branch

cache:
  key: "$CI_BUILD_REF_NAME"
  untracked: true

缓存每个job和branch

cache:
  key: "$CI_BUILD_NAME/$CI_BUILD_REF_NAME"
  untracked: true

缓存每个branch和每个stage

cache:
  key: "$CI_BUILD_STAGE/$CI_BUILD_REF_NAME"
  untracked: true

这段感觉怎么翻译都啰嗦,就这样吧

如果是在Windows环境下开发,需要使用%代替$标识环境变量:

cache:
  key: "%CI_BUILD_STAGE%/%CI_BUILD_REF_NAME%"
  untracked: true

Jobs

.gitlab-ci.yml允许配置无限个job。每个job必须有一个唯一的名称,并且不能是前文所说的任何一个保留字。一个job由一系列定义构建行为的参数组成。

job_name:
  script:
    - rake spec
    - coverage
  stage: test
  only:
    - master
  except:
    - develop
  tags:
    - ruby
    - postgres
  allow_failure: true
关键字 必要性 介绍
script 定义了Runner会执行的脚本命令
image 使用Docker镜像,多内容参考使用Docker镜像
services 使用Docker服务,更多内容参考 使用Docker镜像
stage 定义构建的stage(默认:test
type stage的别名
variables 定义job级别的环境变量
only 定义一组构建会创建的git refs
except 定义一组构建不会创建的git refs
tags 定义一组tags用于选择合适的Runner
allow_failure 允许构建失败。失败的构建不会影响提交状态。
when 定义什么时候执行构建。可选:on_successon_failurealwaysmanual
dependencies 定义当前构建依赖的其他构建,然后你可以在他们之间传递artifacts
artifacts 定义一组构建artifact。
cache 定义一组可以缓存以在随后的工作中共享的文件
before_script 覆写全局的before_script命令
after_script 覆写全局的after_script命令
environment 定义当前构建完成后的运行环境的名称

script

这是一个或一组会被Runner执行的shell脚本。例如:

jobA:
  script: "bundle exec rspec"

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

有时候,script命令需要被包在双引号或者单引号之间。例如,包含符号(:)的命令需要写在引号中,这样yaml的解析器才能正确的解析,而不会误以为这是一组键值对。在使用包含以下符号的命令时要特别小心:
:{}[],&*#?|-<>=!%@`

stage

stage 允许分组构建不同的stage。构建相同的stage时是并行进行的。更多关于stages的说明可以参阅stages.

only and except

onlyexcept 是管理job在被构建时的refs策略的的参数。

  1. only 设置了需要被构建的branches和tags的名称。
  2. except 设置了不需要被构建的branches和tags的名称。

这里有一些使用refs策略的规则:

  • onlyexcept 是可以相互包含的。如果一个job中 onlyexcept都被定义了,ref会同时被 only 过滤 except
  • onlyexcept 支持正则表达式。
  • onlyexcept 可以使用这几个关键字: branches, tagstriggers
  • onlyexcept 允许通过定义仓库路径的方式来过滤要fork的job。

在以下的例子中,job将只会启动以issue-开头的refs,并且跳过所有的branches。

job:
    # 使用正则
    only:
        - /^issue-.*$/
  # 使用关键字
    except:
        - branches

在下边的例子中,job将仅对被打了tag的refs,或者是被API触发器触发时
才执行:

job:
  # 使用关键字
  only:
    - tags
    - triggers

仓库路径可以用于让job仅为父仓库执行并且不fork:

The repository path can be used to have jobs executed only for the parent repository and not forks:

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

上述的例子将会为除了master以外的所有的branches运行job

job variables

可以通过使用variables定义job级别的构建变量。

(未完待续)

2 评论

  1. 文档好像更新了,cache:key不能包含/和.,原文:
    >variable cannot contain the / character, or the equivalent
    URI-encoded %2F; a value made only of dots (., %2E) is also forbidden.

发表评论

电子邮件地址不会被公开。 必填项已用*标注

此站点使用Akismet来减少垃圾评论。了解我们如何处理您的评论数据