- 包含单个配置文件
- 包含一组配置文件
- 使用包含的配置文件中的
default
配置 - 覆盖包含的配置值
- 覆盖包含的配置数组
- 使用 nested includes
- 将变量与
include
一起使用 - 使用
rules
withinclude
- 将
include:local
与通配符文件路径一起使用
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'