极狐GitLab CI/CD include 示例

您可以使用 include 在 CI/CD 作业中包含外部 YAML 文件。

包含单个配置文件

要包含单个配置文件,请使用以下任一语法选项:

  • include 本身带有单个文件。如果是本地文件,则与 include:local 相同。如果是一个远端文件,则与 include:remote 相同。

    include: '/templates/.after-script-template.yml'
    

包含一组配置文件

您可以包含一组配置文件:

  • 如果不指定 include 类型,根据需要,每个数组项默认为 include:localinclude:remote

    include:
      - 'https://gitlab.com/awesome-project/raw/main/.before-script-template.yml'
      - '/templates/.after-script-template.yml'
    
  • 您可以定义单个项目数组:

    include:
      - remote: 'https://gitlab.com/awesome-project/raw/main/.before-script-template.yml'
    
  • 您可以定义一个数组并明确指定多个 include 类型:

    include:
      - remote: 'https://gitlab.com/awesome-project/raw/main/.before-script-template.yml'
      - local: '/templates/.after-script-template.yml'
      - template: Auto-DevOps.gitlab-ci.yml
    
  • 您可以定义一个结合默认和特定 include 类型的数组:

    include:
      - 'https://gitlab.com/awesome-project/raw/main/.before-script-template.yml'
      - '/templates/.after-script-template.yml'
      - template: Auto-DevOps.gitlab-ci.yml
      - project: 'my-group/my-project'
        ref: main
        file: '/templates/.gitlab-ci-template.yml'
    

使用包含的配置文件中的 default 配置

您可以在配置文件中定义 default 部分。当您使用带有 include 关键字的 default 部分时,默认值适用于流水线中的所有作业。

例如,您可以使用带有 before_scriptdefault 部分。

名为 /templates/.before-script-template.yml 的自定义配置文件的内容:

default:
  before_script:
    - apt-get update -qq && apt-get install -y -qq sqlite3 libsqlite3-dev nodejs
    - gem install bundler --no-document
    - bundle install --jobs $(nproc)  "${FLAGS[@]}"

.gitlab-ci.yml 的内容:

include: '/templates/.before-script-template.yml'

rspec1:
  script:
    - bundle exec rspec

rspec2:
  script:
    - bundle exec rspec

默认的 before_script 命令在 script 命令之前在两个 rspec 作业中执行。

覆盖包含的配置值

当您使用 include 关键字时,您可以覆盖包含的配置值以使其适应您的流水线要求。

以下示例显示了在 .gitlab-ci.yml 文件中自定义的 include 文件。 特定的 YAML 定义的变量和 production 作业的详细信息被覆盖。

名为 autodevops-template.yml 的自定义配置文件的内容:

variables:
  POSTGRES_USER: user
  POSTGRES_PASSWORD: testing_password
  POSTGRES_DB: $CI_ENVIRONMENT_SLUG

production:
  stage: production
  script:
    - install_dependencies
    - deploy
  environment:
    name: production
    url: https://$CI_PROJECT_PATH_SLUG.$KUBE_INGRESS_BASE_DOMAIN
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

.gitlab-ci.yml 的内容:

include: 'https://company.com/autodevops-template.yml'

image: alpine:latest

variables:
  POSTGRES_USER: root
  POSTGRES_PASSWORD: secure_password

stages:
  - build
  - test
  - production

production:
  environment:
    url: https://domain.com

.gitlab-ci.yml 文件中定义的 POSTGRES_USERPOSTGRES_PASSWORD 变量以及 production 作业的 environment:url 覆盖了 autodevops-template.yml 文件中定义的值。其他关键字不变。这种方法称为 merging

include 的合并方法

include 配置通过以下过程与主配置文件合并:

  • 包含的文件按照配置文件中定义的顺序读取,包含的配置按照相同的顺序合并在一起。
  • 如果包含的文件也使用了 include,则嵌套的 include 配置首先(递归)合并。
  • 如果参数重叠,则在合并来自包含文件的配置时,最后包含的文件优先。
  • 所有用 include 添加的配置合并后,主配置和被包含的配置合并。

这种合并方法是深度合并,其中哈希映射在配置中的任何深度合并。要合并哈希映射 A(包含到目前为止合并的配置)和 B(下一个配置),键和值按如下方式处理:

  • 当键只存在于 A 中时,使用 A 中的键和值。
  • 当键在 A 和 B 中都存在,且它们的值都是哈希映射时,合并这些哈希映射。
  • 当键同时存在于 A 和 B 中,并且其中一个值不是哈希映射时,使用 B 中的值。
  • 否则,使用 B 中的键和值。

例如,使用包含两个文件的配置:

  • .gitlab-ci.yml 文件:

    include: 'common.yml'
    
    variables:
      POSTGRES_USER: username
    
    test:
      rules:
        - if: $CI_PIPELINE_SOURCE == "merge_request_event"
          when: manual
      artifacts:
        reports:
          junit: rspec.xml
    
  • common.yml 文件:

    variables:
      POSTGRES_USER: common_username
      POSTGRES_PASSWORD: testing_password
    
    test:
      rules:
        - when: never
      script:
        - echo LOGIN=${POSTGRES_USER} > deploy.env
        - rake spec
      artifacts:
        reports:
          dotenv: deploy.env
    

合并结果:

variables:
  POSTGRES_USER: username
  POSTGRES_PASSWORD: testing_password

test:
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
      when: manual
  script:
    - echo LOGIN=${POSTGRES_USER} > deploy.env
    - rake spec
  artifacts:
    reports:
      junit: rspec.xml
      dotenv: deploy.env

在此示例中:

  • 仅在所有文件合并在一起后才评估变量。包含文件中的作业可能最终使用在不同文件中定义的变量值。
  • rules 是一个数组,因此无法合并。顶级文件优先。
  • artifacts 是一个哈希映射,因此可以进行深度合并。

覆盖包含的配置数组

您可以使用合并来扩展和覆盖包含模板中的配置,但不能添加或修改数组中的单个项目。例如,将额外的 notify_owner 命令添加到扩展的 production 作业的 script 数组中:

autodevops-template.yml 的内容:

production:
  stage: production
  script:
    - install_dependencies
    - deploy

.gitlab-ci.yml 的内容:

include: 'autodevops-template.yml'

stages:
  - production

production:
  script:
    - install_dependencies
    - deploy
    - notify_owner

如果 .gitlab-ci.yml 文件中没有重复 install_dependenciesdeploy,那么 production 作业在脚本中将只有 notify_owner

使用 nested includes

您可以在配置文件中嵌套 include 部分,然后将其包含在另一个配置中。例如,对于 include 关键字嵌套了三层深度:

.gitlab-ci.yml 的内容:

include:
  - local: /.gitlab-ci/another-config.yml

/.gitlab-ci/another-config.yml 的内容:

include:
  - local: /.gitlab-ci/config-defaults.yml

/.gitlab-ci/config-defaults.yml 的内容:

default:
  after_script:
    - echo "Job complete."

Use nested includes with duplicate includes entries

引入于 14.8 版本。

Nested includes 可以包含相同的配置文件。重复的配置文件被多次包含,但效果和只包含一次一样。

例如,使用以下 nested includes,其中 defaults.gitlab-ci.yml 被包含多次:

  • .gitlab-ci.yml 文件的内容:

    include:
      - template: defaults.gitlab-ci.yml
      - local: unit-tests.gitlab-ci.yml
      - local: smoke-tests.gitlab-ci.yml
    
  • defaults.gitlab-ci.yml 文件的内容:

    default:
      before_script: default-before-script.sh
      retry: 2
    
  • unit-tests.gitlab-ci.yml 文件的内容:

    include:
      - template: defaults.gitlab-ci.yml
    
    unit-test-job:
      script: unit-test.sh
      retry: 0
    
  • smoke-tests.gitlab-ci.yml 文件的内容:

    include:
      - template: defaults.gitlab-ci.yml
    
    smoke-test-job:
      script: smoke-test.sh
    

最终的配置将是:

unit-test-job:
  before_script: default-before-script.sh
  script: unit-test.sh
  retry: 0

smoke-test-job:
  before_script: default-before-script.sh
  script: smoke-test.sh
  retry: 2

将变量与 include 一起使用

  • 引入于 13.8 版本。
  • 功能标志移除于 13.9 版本
  • 对项目、群组和实例变量的支持添加于 14.2 版本。
  • 对流水线变量的支持添加于 14.5 版本。

在您的 .gitlab-ci.yml 文件的 include 部分,您可以使用:

  • 项目变量
  • 群组变量
  • 实例变量
  • 项目预定义变量
  • 在 14.2 及更高版本,$CI_COMMIT_REF_NAME 预定义变量

    当在 include 中使用时,CI_COMMIT_REF_NAME 变量返回完整的 ref 路径,如 refs/heads/branch-name。在 include:rules 中,可能需要使用 if: $CI_COMMIT_REF_NAME =~ /main/(不是== main)。已在 GitLab 14.5 中解决。

在 14.5 及更高版本中,您还可以使用:

  • 触发器变量
  • 计划流水线变量
  • 手动流水线运行变量
  • 流水线预定义变量

    在创建流水线之前解析 YAML 文件,因此以下流水线预定义变量可用:

    • CI_PIPELINE_ID
    • CI_PIPELINE_URL
    • CI_PIPELINE_IID
    • CI_PIPELINE_CREATED_AT

示例:

include:
  project: '$CI_PROJECT_PATH'
  file: '.compliance-gitlab-ci.yml'

您不能使用在作业中定义的变量,或者在定义所有作业的默认变量的全局 variables 部分中。因为 Includes 在 jobs 之前生效,因此这些变量不能与 include 一起使用。

使用 rules with include

  • 引入于 14.2 版本,在名为 ci_include_rules 的功能标志后默认禁用。
  • 在私有化部署版上启用于 14.3 版本。
  • 功能标志 ci_include_rules 移除于 14.4 版本。
  • exists 关键字支持添加于 14.5 版本。

您可以使用 rulesinclude 来有条件地包含其他配置文件。

您只能将 rules某些变量,以及以下关键字一起使用:

您不能使用 needs: 来创建指向使用 include:local:rules 添加的作业的作业依赖项。验证配置后,极狐GitLab 返回 undefined need: <job-name>

include with rules:if

使用 rules:if 根据 CI/CD 变量的状态有条件地包含其他配置文件。例如:

include:
  - local: builds.yml
    rules:
      - if: $INCLUDE_BUILDS == "true"
  - local: deploys.yml
    rules:
      - if: $CI_COMMIT_BRANCH == "main"

test:
  stage: test
  script: exit 0

include with rules:exists

使用 rules:exists 根据文件的存在有条件地包含其他配置文件。例如:

include:
  - local: builds.yml
    rules:
      - exists:
          - file.md

test:
  stage: test
  script: exit 0

在此示例中,极狐GitLab 检查当前项目中是否存在 file.md

如果您使用 rules:exists 配置 include,添加来自不同项目的配置文件,则会出现一个已知问题。极狐GitLab 检查其他项目中是否存在该文件。例如:

include:
- project: my-group/my-project-2
  ref: main
  file: test-file.yml
  rules:
    - exists:
        - file.md

test:
  stage: test
  script: exit 0

在此示例中,极狐GitLab 检查 my-group/my-project-2 中是否存在 test-file.yml,而不是当前项目。

include:local 与通配符文件路径一起使用

  • 引入于 13.11 版本。
  • 功能标志移除于 14.2 版本。

您可以在 include:local 中使用通配符路径(***)。

例子:

include: 'configs/*.yml'

当流水线运行时,系统:

  • configs 目录中的所有 .yml 文件添加到流水线配置中。
  • 不在 configs 目录的子文件夹中添加 .yml 文件。 为此,请添加以下配置:

    # This matches all `.yml` files in `configs` and any subfolder in it.
    include: 'configs/**.yml'
    
    # This matches all `.yml` files only in subfolders of `configs`.
    include: 'configs/**/*.yml'
    

故障排除

Maximum of 150 nested includes are allowed! 错误

流水线的嵌套包含文件的最大数量为 150。 如果您在流水线中收到 Maximum 150 includes are allowed 错误消息,则可能是:

  • 一些嵌套配置包括过多的额外嵌套 include 配置。
  • 嵌套包含中存在意外循环。例如,include1.yml 包含 include2.yml,后者包含 include1.yml,从而创建递归循环。

为帮助降低发生这种情况的风险,请使用流水线编辑器,编辑流水线配置文件,以验证是否达到限制。您可以一次删除一个包含文件,以尝试缩小哪个配置文件是循环源或过多包含文件的范围。