GitLab CI/CD include 示例

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

包含单个配置文件

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

  • include 本身带有单个文件，与 include:local 相同： 

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

  • include 与单个文件，并指定 include 类型： 

    include:
  remote: 'https://gitlab.com/awesome-project/raw/main/.before-script-template.yml'

包含一组配置文件

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

  • 如果不指定 include 类型，则类型默认为 include:local： 

    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_script 的 default 部分。

名为 /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_USER 和 POSTGRES_PASSWORD 变量以及 production 作业的 environment:url 覆盖了 autodevops-template.yml 文件中定义的值。其他关键字不变。这种方法称为 merging。

覆盖包含的配置数组

您可以使用合并来扩展和覆盖包含模板中的配置，但不能添加或修改数组中的单个项目。例如，将额外的 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_dependencies 和 deploy，那么 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 版本。

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

您只能将以下规则与 include 一起使用（并且只能与某些变量一起使用）：

  • if 规则。例如： 

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

test:
  stage: test
  script: exit 0

  • exists 规则。 例如： 

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

test:
  stage: test
  script: exit 0

不支持 rules 关键字 changes。

您不能使用 needs: 创建指向使用 include:local:rules 所添加作业的作业依赖项。当检查配置的有效性时，系统返回 undefined need: <job-name>。

将 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'