Gitlab CI 配置文件 .gitlab-ci.yaml 详解(下)

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

参考阅读:Gitlab CI 配置文件 .gitlab-ci.yaml 详解(上)

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:osxbuild: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_scriptafter_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模块中设置。如果没有设置,将从项目中使用默认值。

可以设置的值有:clonefetch,和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设置为clonefetch时,可以使用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将意味着clonefetch策略都会让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模块中设置。

它的可用值有:nonenormalrecursive

  • 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 fetchgit 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,test1test2,该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:postgrestest: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://fennay.github.io/

本文参与腾讯云自媒体分享计划,欢迎正在阅读的你也加入,一起分享。

发表于

我来说两句

0 条评论
登录 后参与评论

扫码关注云+社区

领取腾讯云代金券