极狐 GitLab

优化极狐GitLab CI/CD 配置文件

Tier: 基础版,专业版,旗舰版

Offering: JihuLab.com,私有化部署

您可以使用以下方式降低极狐GitLab CI/CD 配置文件中的复杂度和重复配置:

要创建多个类似但变量值不同的作业,请使用 parallel:matrix。

锚点#

YAML 有一项称为“锚点”的功能,可用于在文档中复制内容。

您可以使用锚点来复制或继承属性。将锚点与隐藏作业结合使用,可以为作业提供模板。

& 字符标记锚点名称,* 字符是引用该锚点的别名。您必须在 YAML 文件中比任何引用该锚点的别名更靠前的位置定义该锚点。

当存在重复键时,最后包含的键生效并覆盖其他键。

在某些情况下(请参阅脚本的 YAML 锚点),您可以使用 YAML 锚点构建数组,其中的多个组成部分在其他位置定义。例如:

yaml
1.default_scripts: &default_scripts 2 - ./default-script1.sh 3 - ./default-script2.sh 4 5job1: 6 script: 7 - *default_scripts 8 - ./job-script.sh

使用 include 关键字时,不能跨多个文件使用 YAML 锚点。锚点仅在其定义所在的文件中有效。要复用不同 YAML 文件中的配置,请使用 !reference 标签或 extends 关键字。

以下示例使用锚点和映射合并。它创建两个作业 test1 和 test2,它们继承 .job_template 配置,各自定义了自己的自定义 script:

yaml
1.job_template: &job_configuration # Hidden yaml configuration that defines an anchor named 'job_configuration' 2 image: ruby:2.6 3 services: 4 - postgres 5 - redis 6 7test1: 8 <<: *job_configuration # Add the contents of the 'job_configuration' alias 9 script: 10 - test1 project 11 12test2: 13 <<: *job_configuration # Add the contents of the 'job_configuration' alias 14 script: 15 - test2 project

& 设置锚点的名称(job_configuration),<< 表示“将给定的哈希合并到当前哈希中”,* 包含指定的锚点(再次为 job_configuration)。此示例的展开版本为:

yaml
1.job_template: 2 image: ruby:2.6 3 services: 4 - postgres 5 - redis 6 7test1: 8 image: ruby:2.6 9 services: 10 - postgres 11 - redis 12 script: 13 - test1 project 14 15test2: 16 image: ruby:2.6 17 services: 18 - postgres 19 - redis 20 script: 21 - test2 project

您可以使用锚点定义两组服务。例如,test:postgres 和 test:mysql 共享 .job_template中定义的 script,但使用不同的 services,分别在 .postgres_services 和 .mysql_services中定义:

yaml
1.job_template: &job_configuration 2 script: 3 - test project 4 tags: 5 - dev 6 7.postgres_services: 8 services: &postgres_configuration 9 - postgres 10 - ruby 11 12.mysql_services: 13 services: &mysql_configuration 14 - mysql 15 - ruby 16 17test:postgres: 18 <<: *job_configuration 19 services: *postgres_configuration 20 tags: 21 - postgres 22 23test:mysql: 24 <<: *job_configuration 25 services: *mysql_configuration

展开版本为:

yaml
1.job_template: 2 script: 3 - test project 4 tags: 5 - dev 6 7.postgres_services: 8 services: 9 - postgres 10 - ruby 11 12.mysql_services: 13 services: 14 - mysql 15 - ruby 16 17test:postgres: 18 script: 19 - test project 20 services: 21 - postgres 22 - ruby 23 tags: 24 - postgres 25 26test:mysql: 27 script: 28 - test project 29 services: 30 - mysql 31 - ruby 32 tags: 33 - dev

您可以看到,隐藏作业被方便地用作模板,并且 tags: [postgres] 覆盖了 tags: [dev]。

脚本的 YAML 锚点#

您可以将 YAML 锚点与 script、before_script 和 after_script 结合使用,以在多个作业中使用预定义命令:

yaml
1.some-script-before: &some-script-before 2 - echo "Execute this script first" 3 4.some-script: &some-script 5 - echo "Execute this script second" 6 - echo "Execute this script too" 7 8.some-script-after: &some-script-after 9 - echo "Execute this script last" 10 11job1: 12 before_script: 13 - *some-script-before 14 script: 15 - *some-script 16 - echo "Execute something, for this job only" 17 after_script: 18 - *some-script-after 19 20job2: 21 script: 22 - *some-script-before 23 - *some-script 24 - echo "Execute something else, for this job only" 25 - *some-script-after

使用 extends 复用配置节#

您可以使用 extends 关键字在多个作业中复用配置。它类似于 YAML 锚点,但更简单,而且您可以将 extends 与 includes 一起使用。

extends 支持多级继承。由于会增加复杂度,您应避免使用超过三级的继承,但最多可以使用十一级。以下示例有两级继承:

yaml
1.tests: 2 rules: 3 - if: $CI_PIPELINE_SOURCE == "push" 4 5.rspec: 6 extends: .tests 7 script: rake rspec 8 9rspec 1: 10 variables: 11 RSPEC_SUITE: '1' 12 extends: .rspec 13 14rspec 2: 15 variables: 16 RSPEC_SUITE: '2' 17 extends: .rspec 18 19spinach: 20 extends: .tests 21 script: rake spinach

从 extends中排除某个键#

要从扩展内容中排除某个键,必须将其赋值为 null,例如:

yaml
1.base: 2 script: test 3 variables: 4 VAR1: base var 1 5 6test1: 7 extends: .base 8 variables: 9 VAR1: test1 var 1 10 VAR2: test2 var 2 11 12test2: 13 extends: .base 14 variables: 15 VAR2: test2 var 2 16 17test3: 18 extends: .base 19 variables: {} 20 21test4: 22 extends: .base 23 variables: null

合并后的配置:

yaml
1test1: 2 script: test 3 variables: 4 VAR1: test1 var 1 5 VAR2: test2 var 2 6 7test2: 8 script: test 9 variables: 10 VAR1: base var 1 11 VAR2: test2 var 2 12 13test3: 14 script: test 15 variables: 16 VAR1: base var 1 17 18test4: 19 script: test 20 variables: null

同时使用 extends 和 include#

要复用不同配置文件中的配置,请结合使用 extends 和 include。

在以下示例中,included.yml 文件中定义了一个 script。然后,在 .gitlab-ci.yml 文件中,extends 引用了 script的内容:

  • included.yml:

    yaml
    .template: script: - echo Hello!
  • .gitlab-ci.yml:

    yaml
    include: included.yml useTemplate: image: alpine extends: .template

合并细节#

您可以使用 extends 合并哈希,但不能合并数组。当存在重复键时,极狐GitLab 会基于这些键执行反向深度合并。最后一个成员中的键始终覆盖其他层级中定义的任何内容。例如:

yaml
1.only-important: 2 variables: 3 URL: "http://my-url.internal" 4 IMPORTANT_VAR: "the details" 5 rules: 6 - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH 7 - if: $CI_COMMIT_BRANCH == "stable" 8 tags: 9 - production 10 script: 11 - echo "Hello world!" 12 13.in-docker: 14 variables: 15 URL: "http://docker-url.internal" 16 tags: 17 - docker 18 image: alpine 19 20rspec: 21 variables: 22 GITLAB: "is-awesome" 23 extends: 24 - .only-important 25 - .in-docker 26 script: 27 - rake rspec

结果就是以下 rspec 作业:

yaml
1rspec: 2 variables: 3 URL: "http://docker-url.internal" 4 IMPORTANT_VAR: "the details" 5 GITLAB: "is-awesome" 6 rules: 7 - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH 8 - if: $CI_COMMIT_BRANCH == "stable" 9 tags: 10 - docker 11 image: alpine 12 script: 13 - rake rspec

在此示例中:

  • variables 节会合并,但 URL: "http://docker-url.internal" 会覆盖 URL: "http://my-url.internal"。
  • tags: ['docker'] 会覆盖 tags: ['production']。
  • script 不会合并,但 script: ['rake rspec'] 会覆盖 script: ['echo "Hello world!"']。您可以使用 YAML 锚点来合并数组。

!reference 标签#

使用 !reference 自定义 YAML 标签可以从其他作业节中选择关键字配置,并在当前节中复用它。与 YAML 锚点不同,您可以使用 !reference 标签复用包含文件中的配置。

如果您使用 !reference 标签来覆盖已包含文件中的配置,请考虑改用 CI/CD 输入。

您不能将 !reference 标签与输入结合使用:

  • 您不能在 !reference 标签的路径中使用输入,例如 !reference [.settings, "$[[ inputs.key ]]"]。路径段在解析 YAML 文件时读取, 此时输入尚未插值,因此输入会被视为字面文本,引用将无法找到。
  • 不要在输入值中使用 !reference 标签,因为 标签在输入插值之后才会解析。

在以下示例中,来自两个不同位置的 script 和 after_script 在 test 作业中被复用:

  • configs.yml:

    yaml
    .setup: script: - echo creating environment
  • .gitlab-ci.yml:

    yaml
    1include: 2 - local: configs.yml 3 4.teardown: 5 after_script: 6 - echo deleting environment 7 8test: 9 script: 10 - !reference [.setup, script] 11 - echo running my own command 12 after_script: 13 - !reference [.teardown, after_script]

在以下示例中,test-vars-1 复用 .vars中的所有变量,而 test-vars-2 选择特定变量并将其复用为新的 MY_VAR 变量。

yaml
1.vars: 2 variables: 3 URL: "http://my-url.internal" 4 IMPORTANT_VAR: "the details" 5 6test-vars-1: 7 variables: !reference [.vars, variables] 8 script: 9 - printenv 10 11test-vars-2: 12 variables: 13 MY_VAR: !reference [.vars, variables, IMPORTANT_VAR] 14 script: 15 - printenv

您可以使用多个 !reference 标签,用 rules、script 或 stages 构建数组。例如:

yaml
1.rules_prod: 2 - if: $CI_PIPELINE_SOURCE == "merge_request_event" 3 - if: $CI_PIPELINE_SOURCE == "schedule" 4 5.rules_staging: 6 - if: $CI_COMMIT_BRANCH =~ /^wip-.*/ 7 - if: $CI_PIPELINE_SOURCE == "push" 8 9deploy_job: 10 script: echo test 11 rules: 12 - !reference [.rules_prod] 13 - !reference [.rules_staging]

对于所有其他关键字,您会收到 config should be an array of 验证错误。

在 script、before_script 和 after_script中嵌套 !reference 标签#

您可以在 script、before_script 和 after_script 节中将 !reference 标签嵌套最多 10 层。在构建更复杂的脚本时,使用嵌套标签来定义可复用的节。例如:

yaml
1.snippets: 2 one: 3 - echo "ONE!" 4 two: 5 - !reference [.snippets, one] 6 - echo "TWO!" 7 three: 8 - !reference [.snippets, two] 9 - echo "THREE!" 10 11nested-references: 12 script: 13 - !reference [.snippets, three]

在此示例中,nested-references 作业会运行全部三个 echo 命令。

配置 IDE 以支持 !reference 标签#

流水线编辑器支持 !reference 标签。不过,您的编辑器默认可能会将 !reference 等自定义 YAML 标签的架构规则视为无效。您可以配置某些编辑器以接受 !reference 标签。例如:

  • 在 VS Code 中,您可以将 vscode-yaml 设置为在 settings.json 文件中解析 customTags:

    json
    "yaml.customTags": [ "!reference sequence" ]
  • 在 Sublime Text 中,如果您使用 LSP-yaml 包,可以在 LSP-yaml 用户设置中设置 customTags:

    json
    { "settings": { "yaml.customTags": ["!reference sequence"] } }