本文档列出了 GitLab .gitlab-ci.yml
文件的配置选项。
- 有关 GitLab CI/CD 的快速介绍,请遵循快速入门指南。
- 有关示例集合,请参阅 GitLab CI/CD 示例。
- 要查看企业使用的大型
.gitlab-ci.yml
文件,请参阅gitlab的.gitlab-ci.yml文件。
当在编辑您的 .gitlab-ci.yml
文件时,可以使用 CI Lint 工具来验证它。
关键字
GitLab CI/CD 流水线配置包括:
-
配置流水线行为的全局关键字:
关键字 描述 default 作业关键字的自定义默认值。 stages 流水线阶段的名称和顺序。 workflow 控制运行的流水线类型。 include 从其他 YAML 文件导入配置。 -
作业由作业关键字配置:
关键字 | 描述 |
---|---|
after_script | 覆盖作业后执行的一组命令。 |
allow_failure | 允许作业失败。失败的作业不会导致流水线失败。 |
artifacts | 成功时附加到作业的文件和目录列表。 |
before_script | 覆盖在作业之前执行的一组命令。 |
cache | 应在后续运行之间缓存的文件列表。 |
coverage | 给定作业的代码覆盖率设置。 |
dast_configuration | 在作业级别使用来自 DAST 配置文件的配置。 |
dependencies | 通过提供要从中获取产物的作业列表,来限制将哪些产物传递给特定作业。 |
environment | 作业部署到的环境的名称。 |
except | 控制何时不创建作业。 |
extends | 此作业继承自的配置条目。 |
image | 使用 Docker 镜像。 |
inherit | 选择所有作业继承的全局默认值。 |
interruptible | 定义当新运行使作业变得多余时,是否可以取消作业。 |
needs | 在 stage 顺序之前执行的作业。 |
only | 控制何时创建作业。 |
pages | 上传作业的结果,与 GitLab Pages 一起使用。 |
parallel | 应该并行运行多少个作业实例。 |
release | 指示运行器生成 release 对象。 |
resource_group | 限制作业并发。 |
retry | 在失败的情况下可以自动重试作业的时间和次数。 |
rules | 用于评估和确定作业的选定属性以及它是否已创建的条件列表。 |
script | 由 runner 执行的 Shell 脚本。 |
secrets | 作业所需的 CI/CD secret 信息。 |
services | 使用 Docker 服务镜像。 |
stage | 定义作业阶段。 |
tags | 用于选择 runner 的标签列表。 |
timeout | 定义优先于项目范围设置的自定义作业级别超时。 |
trigger | 定义下游流水线触发器。 |
variables | 在作业级别定义作业变量。 |
when | 何时运行作业。 |
全局关键字
某些关键字未在作业中定义。这些关键字控制流水线行为或导入额外的流水线配置。
default
您可以为某些关键字设置全局默认值。 未定义一个或多个所列关键字的作业使用在 default:
部分中定义的值。
关键字类型:全局关键字。
可能的输入:以下关键字可以具有自定义默认值:
- after_script
- artifacts
- before_script
- cache
- image
- interruptible
- retry
- services
- tags
- timeout
default:
image: ruby:3.0
rspec:
script: bundle exec rspec
rspec 2.7:
image: ruby:2.7
script: bundle exec rspec
示例将 ruby:3.0
镜像设置为流水线中所有作业的默认镜像。 rspec 2.7
作业不使用默认值,因为它使用特定于作业的 image:
部分覆盖了默认值:
额外细节:
- 创建流水线时,每个默认值都会复制到所有未定义该关键字的作业。
- 如果作业已经配置了其中一个关键字,则作业中的配置优先,不会被默认替换。
- 使用 inherit:default 控制作业中默认关键字的继承。
stages
使用 stages
来定义包含作业组的阶段。stages
是为流水线全局定义的。在作业中使用 stage 来定义作业属于哪个阶段。
如果 .gitlab-ci.yml
文件中没有定义 stages
,那么默认的流水线阶段是:
- .pre
build
test
deploy
- .post
stages
项的顺序定义了作业的执行顺序:
- 同一阶段的作业并行运行。
- 下一阶段的作业在上一阶段的作业成功完成后运行。
例如:
stages:
- build
- test
- deploy
-
build
中的所有作业并行执行。 - 如果
build
中的所有作业都成功,test
作业将并行执行。 - 如果
test
中的所有作业都成功,deploy
作业将并行执行。 - 如果
deploy
中的所有作业都成功,则流水线被标记为passed
。
如果任何作业失败,流水线将被标记为 failed
并且后续阶段的作业不会启动。当前阶段的作业不会停止并继续运行。
如果作业未指定 stage,则作业被分配到 test
阶段。
如果定义了一个阶段,但没有作业使用它,则该阶段在流水线中不可见。 这对合规流水线配置很有用,因为:
- 阶段可以在合规性配置中定义,但如果不使用则保持隐藏。
- 当开发人员在作业定义中使用它们时,定义的阶段变得可见。
要使作业更早开始并忽略阶段顺序,请使用 needs 关键字。
workflow
使用 workflow:
来确定是否创建流水线。 在顶层定义此关键字,使用单个 rules:
关键字,类似于在作业中定义的 rules:。
workflow:rules
您可以使用 workflow:rules
模板 导入预先配置的 workflow:rules
条目。
workflow: rules
接受这些关键字:
- if:检查此规则以确定何时运行流水线。
-
when:指定当
if
规则为 true 时要做什么。- 要运行流水线,请设置为
always
。 - 要阻止流水线运行,请设置为
never
。
- 要运行流水线,请设置为
- variables:如果未定义,则使用在别处定义的变量。
当没有规则为 true 时,流水线不会运行。
workflow: rules
的一些示例 if
子句如下:
示例规则 | 详细信息 |
---|---|
if: '$CI_PIPELINE_SOURCE == "merge_request_event"' |
控制合并请求流水线何时运行。 |
if: '$CI_PIPELINE_SOURCE == "push"' |
控制分支流水线和标签流水线何时运行。 |
if: $CI_COMMIT_TAG |
控制标签流水线何时运行。 |
if: $CI_COMMIT_BRANCH |
控制分支流水线何时运行。 |
在此示例中,如果提交标题(提交消息的第一行)不以 -draft
结尾并且流水线用于以下任一情况,则流水线运行:
workflow:
rules:
- if: $CI_COMMIT_TITLE =~ /-draft$/
when: never
- if: $CI_PIPELINE_SOURCE == "merge_request_event"
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
- 合并请求
- 默认分支
这个例子有严格的规则,流水线在任何其他情况下都不运行。
或者,所有规则都可以是 when: never
,最后是 when:always
规则。匹配 when: never
规则的流水线不会运行。 所有其他流水线类型运行:
workflow:
rules:
- if: '$CI_PIPELINE_SOURCE == "schedule"'
when: never
- if: '$CI_PIPELINE_SOURCE == "push"'
when: never
- when: always
此示例阻止了计划或 push
(分支和标签)的流水线。 最后的 when: always
规则运行所有其他流水线类型,包括合并请求流水线。
如果您的规则同时匹配分支流水线和合并请求流水线,则可能会出现重复流水线。
workflow:rules:variables
- 引入于 13.11 版本
- 功能标志移除于 14.1 版本。
您可以在 workflow:rules:
中使用 variables 来定义特定流水线条件的变量。
当条件匹配时,将创建该变量并可供流水线中的所有作业使用。如果该变量已在全局级别定义,则 workflow
变量优先并覆盖全局变量。
关键字类型:全局关键字。
可能的输入:变量名和值对:
- 名称只能使用数字、字母和下划线 (
_
)。 - 值必须是字符串。
workflow:rules:variables
示例:
variables:
DEPLOY_VARIABLE: "default-deploy"
workflow:
rules:
- if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH
variables:
DEPLOY_VARIABLE: "deploy-production" # Override globally-defined DEPLOY_VARIABLE
- if: $CI_COMMIT_REF_NAME =~ /feature/
variables:
IS_A_FEATURE: "true" # Define a new variable.
- when: always # Run the pipeline in other cases
job1:
variables:
DEPLOY_VARIABLE: "job1-default-deploy"
rules:
- if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH
variables: # Override DEPLOY_VARIABLE defined
DEPLOY_VARIABLE: "job1-deploy-production" # at the job level.
- when: on_success # Run the job in other cases
script:
- echo "Run script with $DEPLOY_VARIABLE as an argument"
- echo "Run another script if $IS_A_FEATURE exists"
job2:
script:
- echo "Run script with $DEPLOY_VARIABLE as an argument"
- echo "Run another script if $IS_A_FEATURE exists"
当分支是默认分支时:
- job1 的
DEPLOY_VARIABLE
是job1-deploy-production
。 - job2 的
DEPLOY_VARIABLE
是deploy-production
。
当分支是 feature
时:
- job1 的
DEPLOY_VARIABLE
是job1-default-deploy
,而IS_A_FEATURE
是true
。 - job2 的
DEPLOY_VARIABLE
是default-deploy
,而IS_A_FEATURE
是true
。
当分支是别的东西时:
- job1 的
DEPLOY_VARIABLE
是job1-default-deploy
。 - job2 的
DEPLOY_VARIABLE
是default-deploy
。
include
使用 include
在 CI/CD 配置中包含外部 YAML 文件。 您可以将一个长的 .gitlab-ci.yml
文件拆分为多个文件以提高可读性,或减少同一配置在多个位置的重复。
您还可以将模板文件存储在中央仓库中并将它们包含在项目中。
include
文件:
- 与
.gitlab-ci.yml
文件中的那些合并。 - 无论
include
关键字的位置如何,始终先求值,然后与.gitlab-ci.yml
文件的内容合并。
您可以 nest 最多 100 个 include,在 14.9 及更高版本中,同一个文件可以在 nested includes 中多次 include,但重复的将被忽略。 在 12.4 及更高版本中,解析所有文件的时间限制为 30 秒。
关键字类型:全局关键字。
可能的输入:include
子键:
- include:local
- include:file
- include:remote
- include:template
额外细节:
- 使用合并来自定义和覆盖本地包含的 CI/CD 配置。
- 您可以通过在
.gitlab-ci.yml
文件中使用相同的作业名称或全局关键字,来覆盖包含的配置。这两个配置合并在一起,.gitlab-ci.yml
文件中的配置优先于包含的配置。
include:local
使用 include:local
包含与 .gitlab-ci.yml
文件位于同一仓库中的文件。 使用 include:local
代替符号链接。
关键字类型:全局关键字。
可能的输入:
- 相对于根目录 (
/
) 的完整路径。 - YAML 文件的扩展名必须是
.yml
或.yaml
。 - 您可以在文件路径中使用 * 和 ** 通配符。
include:local
示例:
include:
- local: '/templates/.gitlab-ci-template.yml'
您还可以使用较短的语法来定义路径:
include: '.gitlab-ci-production.yml'
额外细节:
-
.gitlab-ci.yml
文件和本地文件必须在同一个分支上。 - 您不能通过 Git 子模块路径包含本地文件。
- 所有的 nested includes 都在同一个项目范围内执行,所以您可以使用本地、项目、远端或模板 include。
include:file
包含来自同一项目的多个文件引入于 13.6 版本。功能标志移除于 13.8 版本。
要在同一个实例上包含来自另一个私有项目的文件,请使用 include:file
。 您只能将 include:file
与 include:project
结合使用。
关键字类型:全局关键字。
可能的输入:相对于根目录 (/
) 的完整路径。YAML 文件的扩展名必须是.yml
或.yaml
。
include:file
示例:
include:
- project: 'my-group/my-project'
file: '/templates/.gitlab-ci-template.yml'
您还可以指定一个 ref
。 如果不指定值,则 ref 默认为项目的 HEAD
:
include:
- project: 'my-group/my-project'
ref: main
file: '/templates/.gitlab-ci-template.yml'
- project: 'my-group/my-project'
ref: v1.0.0 # Git Tag
file: '/templates/.gitlab-ci-template.yml'
- project: 'my-group/my-project'
ref: 787123b47f14b552955ca2786bc9542ae66fee5b # Git SHA
file: '/templates/.gitlab-ci-template.yml'
您可以包含来自同一项目的多个文件:
include:
- project: 'my-group/my-project'
ref: main
file:
- '/templates/.builds.yml'
- '/templates/.tests.yml'
额外细节:
- 所有 nested includes 都在目标项目的范围内执行。您可以使用
local
(相对于目标项目)、project
、remote
或template
include。 - 当流水线启动时,评估所有方法 include 的
.gitlab-ci.yml
文件配置。配置是一个及时的快照并持久存在于数据库中。在下一个流水线启动之前,系统不会反映对引用的.gitlab-ci.yml
文件配置的任何更改。 - 当您包含来自另一个私有项目的 YAML 文件时,运行流水线的用户必须是这两个项目的成员并且具有运行流水线的适当权限。如果用户无权访问任何包含的文件,则可能会显示
not found or access denied
错误。
include:remote
使用带有完整 URL 的 include:remote
来包含来自不同位置的文件。
关键字类型:全局关键字。
可能的输入:可通过 HTTP/HTTPS GET
请求访问的公共 URL。不支持使用远端 URL 进行身份验证。
YAML 文件的扩展名必须是 .yml
或 .yaml
。
include:remote
示例:
include:
- remote: 'https://gitlab.com/example-project/-/raw/main/.gitlab-ci.yml'
额外细节:
- 所有 nested includes 都以公共用户身份在没有上下文的情况下执行,因此您只能包含公共项目或模板。
- 包含远端 CI/CD 配置文件时要小心。当外部 CI/CD 配置文件更改时,不会触发任何流水线或通知。从安全角度来看,这类似于拉取第三方依赖项。
include:template
使用 include:template
包含 .gitlab-ci.yml 模板。
关键字类型:全局关键字。
可能的输入:.gitlab-ci.yml 模板.
include:template
示例:
# File sourced from the GitLab template collection
include:
- template: Auto-DevOps.gitlab-ci.yml
多个 include:template
文件:
include:
- template: Android-Fastlane.gitlab-ci.yml
- template: Auto-DevOps.gitlab-ci.yml
额外细节:
- 所有 nested includes 仅在用户许可的情况下执行,因此可以使用
project
、remote
或template
include。
作业关键字
以下主题说明如何使用关键字来配置 CI/CD 流水线。
image
使用 image
指定运行作业的 Docker 镜像。
关键字类型:作业关键字。您只能将其用作作业的一部分或在 default: 部分 中使用。
可能的输入:镜像的名称,包括镜像库路径(如果需要),采用以下格式之一:
-
<image-name>
(与使用带有latest
标签的<image-name>
相同) <image-name>:<tag>
<image-name>@<digest>
image
示例:
default:
image: ruby:3.0
rspec:
script: bundle exec rspec
rspec 2.7:
image: registry.example.com/my-group/my-project/ruby:2.7
script: bundle exec rspec
在这个例子中,ruby:3.0
镜像是流水线中所有作业的默认镜像。 rspec 2.7
作业不使用默认值,因为它使用特定于作业的 image:
部分覆盖了默认值。
image:name
作业运行所在的 Docker 镜像的名称。与自身使用的 image: 类似。
关键字类型:作业关键字。您只能将其用作作业的一部分或在 default: 部分 中使用。
可能的输入:镜像的名称,包括镜像库路径(如果需要),采用以下格式之一:
-
<image-name>
(与使用带有latest
标签的<image-name>
相同) <image-name>:<tag>
<image-name>@<digest>
image:name
示例:
image:
name: "registry.example.com/my/image:latest"
image:pull_policy
- 引入于 15.1 版本,功能标志为
ci_docker_image_pull_policy
。默认禁用。- 需要极狐GitLab Runner 15.1 或更高版本。
FLAG: 在私有化部署版上,此功能默认不可用。要使其可用,询问管理员启用功能标志 ci_docker_image_pull_policy
。此功能尚未准备好用于生产用途。
Runner 用于获取 Docker 镜像的拉取策略。
关键字类型:作业关键字。您只能将其用作作业的一部分或在 default 部分中使用。
可能的输入:
- 单个拉取策略或数组中的多个拉取策略。可以是
always
、if-not-present
或never
。
image:pull_policy
示例:
job1:
script: echo "A single pull policy."
image:
name: ruby:3.0
pull_policy: if-not-present
job2:
script: echo "Multiple pull policies."
image:
name: ruby:3.0
pull_policy: [always, if-not-present]
额外细节:
- 如果 runner 不支持定义的拉取策略,则作业将失败并出现类似以下错误:
ERROR: Job failed (system failure): the configured PullPolicies ([always]) are not allowed by AllowedPullPolicies ([never])
。
image:entrypoint
作为容器入口点执行的命令或脚本。
创建 Docker 容器时,entrypoint
被转换为 Docker 的 --entrypoint
选项。 语法类似于 Dockerfile ENTRYPOINT 指令,其中每个 shell 令牌都是数组中的一个单独字符串。
关键字类型:作业关键字。您只能将其用作作业的一部分或在 default: 部分 中使用。
可能的输入:一个字符串。
image:entrypoint
示例:
image:
name: super/sql:experimental
entrypoint: [""]
services
使用 services
指定一个额外的 Docker 镜像来运行脚本。services
镜像链接到 image 关键字中指定的镜像。
关键字类型:作业关键字。您只能将其用作作业的一部分或在 default: 部分 中使用。
可能的输入:服务镜像的名称,包括镜像库路径(如果需要),采用以下格式之一:
-
<image-name>
(与使用带有latest
标签的<image-name>
相同) <image-name>:<tag>
<image-name>@<digest>
services
示例:
default:
image:
name: ruby:2.6
entrypoint: ["/bin/bash"]
services:
- name: my-postgres:11.7
alias: db-postgres
entrypoint: ["/usr/local/bin/db-postgres"]
command: ["start"]
before_script:
- bundle install
test:
script:
- bundle exec rake spec
在此示例中,作业启动一个 Ruby 容器。然后,该作业从该容器启动另一个运行 PostgreSQL 的容器。然后该作业在该容器中运行脚本。
service:pull_policy
- 引入于 15.1 版本,功能标志为
ci_docker_image_pull_policy
。默认禁用。- 在 SaaS 版和私有化部署版上启用于 15.2 版本。
- 需要极狐GitLab Runner 15.1 或更高版本。
Runner 用于获取 Docker 镜像的拉取策略。
关键字类型:作业关键字。您只能将其用作作业的一部分或在 default 部分中使用。
可能的输入:
- 单个拉取策略,或数组中的多个拉取策略。可以是
always
、if-not-present
或never
。
service:pull_policy
的示例:
job1:
script: echo "A single pull policy."
services:
- name: postgres:11.6
pull_policy: if-not-present
job2:
script: echo "Multiple pull policies."
services:
- name: postgres:11.6
pull_policy: [always, if-not-present]
额外细节:
- 如果 runner 不支持定义的拉取策略,则作业将失败并出现类似的错误:
ERROR: Job failed (system failure): the configured PullPolicies ([always]) are not allowed by AllowedPullPolicies ([never])
。
script
使用 script
指定 runner 要执行的命令。
除了 trigger jobs 之外的所有作业都需要一个 script
关键字。
关键字类型:作业关键字。您只能将其用作作业的一部分。
可能的输入:一个数组,包括:
- 单行命令。
- 长命令拆分多行。
- YAML 锚点。
script
示例:
job1:
script: "bundle exec rspec"
job2:
script:
- uname -a
- bundle exec rspec
额外细节:
- 当您使用 script 中的这些特殊字符时,必须使用单引号 (
'
) 或双引号 ("
)。
before_script
使用 before_script
来定义一系列命令,这些命令应该在每个作业的 script
命令之前运行,但在 artifacts 恢复之后。
关键字类型:作业关键字。您只能将其用作作业的一部分或在 default: 部分 中使用。
可能的输入:一个数组,包括:
- 单行命令。
- 长命令拆分多行。
- YAML 锚点。
before_script
示例:
job:
before_script:
- echo "Execute this command before any 'script:' commands."
script:
- echo "This command executes after the job's 'before_script' commands."
额外细节:
- 您在
before_script
中指定的脚本与您在主 script 中指定的任何脚本连接在一起。组合脚本在单个 shell 中一起执行。 - 在顶层使用
before_script
,但不在default
部分,已弃用。
after_script
使用 after_script
定义在每个作业之后运行的命令数组,包括失败的作业。
关键字类型:作业关键字。您只能将其用作作业的一部分或在 default: 部分 中使用。
可能的输入:一个数组,包括:
- 单行命令。
- 长命令拆分多行。
- YAML 锚点。
Example of after_script
:
job:
script:
- echo "An example script section."
after_script:
- echo "Execute this command after the `script` section completes."
额外细节:
您在 after_script
中指定的脚本在一个新的 shell 中执行,与任何 before_script
或 script
命令分开。结果:
- 将当前工作目录设置回默认值(根据定义运行程序如何处理 Git 请求的变量)。
- 无权访问由
before_script
或script
中定义的命令完成的更改,包括:- 在
script
脚本中导出的命令别名和变量。 - 作业树之外的更改(取决于 runner),例如由
before_script
或script
脚本安装的软件。
- 在
- 有一个单独的超时,它被硬编码为 5 分钟。
- 不要影响作业的退出代码。如果
script
部分成功并且after_script
超时或失败,作业将退出,代码为0
(Job Succeeded
)。
如果作业超时或被取消,则不会执行 after_script
命令。 存在一个问题,即为超时或取消的作业添加对执行 after_script
命令的支持。
stage
使用 stage
定义作业在哪个 stage 中运行。同一个 stage
中的作业可以并行执行(参见 额外细节)。
如果没有定义 stage
,则作业默认使用 test
阶段。
关键字类型:作业关键字。您只能将其用作作业的一部分。
可能的输入:包含任意数量阶段名称的数组。 阶段名称可以是:
- 默认阶段。
- 用户定义的阶段。
stage
示例:
stages:
- build
- test
- deploy
job1:
stage: build
script:
- echo "This job compiles code."
job2:
stage: test
script:
- echo "This job tests the compiled code. It runs when the build stage completes."
job3:
script:
- echo "This job also runs in the test stage".
job4:
stage: deploy
script:
- echo "This job deploys the code. It runs when the test stage completes."
额外细节:
- 如果作业在不同的 runner 上运行,则它们可以并行运行。
- 如果您只有一个 runner,如果 runner 的
concurrent
设置大于1
,作业可以并行运行。
stage: .pre
使用 .pre
阶段在流水线开始时运行作业。.pre
始终是流水线的第一阶段。用户定义的阶段在 .pre
之后执行。 您不必在 stages 中定义 .pre
。
如果流水线仅包含 .pre
或 .post
阶段的作业,则它不会运行。 在不同的阶段必须至少有一项其他作业。
关键字类型:您只能将它与作业的 stage
关键字一起使用。
stage: .pre
示例:
stages:
- build
- test
job1:
stage: build
script:
- echo "This job runs in the build stage."
first-job:
stage: .pre
script:
- echo "This job runs in the .pre stage, before all other stages."
job2:
stage: test
script:
- echo "This job runs in the test stage."
stage: .post
使用 .post
阶段使作业在流水线的末尾运行。.post
始终是流水线的最后阶段。用户定义的阶段在 .post
之前执行。 你不必在 stages 中定义 .post
。
如果流水线仅包含 .pre
或 .post
阶段的作业,则它不会运行。 在不同的阶段必须至少有一项其他作业。
关键字类型:您只能将它与作业的 stage
关键字一起使用。
stage: .post
示例:
stages:
- build
- test
job1:
stage: build
script:
- echo "This job runs in the build stage."
last-job:
stage: .post
script:
- echo "This job runs in the .post stage, after all other stages."
job2:
stage: test
script:
- echo "This job runs in the test stage."
extends
使用 extends
来重用配置 section。它是 YAML 锚点 的替代方案,并且更加灵活和可读。
关键字类型:作业关键字。您只能将其用作作业的一部分。
可能的输入:
- 流水线中另一个作业的名称。
- 流水线中其他作业的名称列表(数组)。
extends
示例:
.tests:
script: rake test
stage: test
only:
refs:
- branches
rspec:
extends: .tests
script: rake rspec
only:
variables:
- $RSPEC
在此示例中,rspec
作业使用来自.tests
模板作业的配置。 创建流水线时:
- 根据键执行反向深度合并。
- 将
.tests
内容与rspec
作业合并。 - 不合并键的值。
结果是这个 rspec
作业:
rspec:
script: rake rspec
stage: test
only:
refs:
- branches
variables:
- $RSPEC
额外示例:
- 在 12.0 及更高版本中,您可以为
extends
使用多个父项。 -
extends
关键字最多支持 11 级继承,但应避免使用超过 3 级。 - 在上面的例子中,
.tests
是一个隐藏作业,但也可以从常规作业扩展配置。
rules
使用 rules
来包含或排除流水线中的作业。
创建流水线时会评估规则,并按顺序评估,直到第一次匹配。找到匹配项后,该作业将包含在流水线中或从流水线中排除,具体取决于配置。
您不能在规则中使用作业脚本中创建的 dotenv 变量,因为在任何作业运行之前都会评估规则。
rules
替换了 only/except,并且它们不能在同一个作业中一起使用。如果您将一个作业配置为使用两个关键字,则系统会返回一个 key may not used with rules
错误。
rules
接受以下规则:
if
changes
exists
allow_failure
variables
when
您可以为复杂规则,将多个关键字组合在一起。
作业被添加到流水线中:
- 如果
if
、changes
或exists
规则匹配并且还具有when: on_success
(默认)、when: delay
或when: always
。 - 如果达到的规则只有
when: on_success
、when: delay
或when: always
。
作业未添加到流水线中:
- 如果没有规则匹配。
- 如果规则匹配并且有
when: never
。
您可以在不同的工作中使用 !reference 标签 来重用 rules
配置。
rules:if
使用 rules:if
子句指定何时向流水线添加作业:
- 如果
if
语句为 true,则将作业添加到管流水线中。 - 如果
if
语句为 true,但它与when: never
结合使用,则不要将作业添加到流水线中。 - 如果没有
if
语句为 true,则不要将作业添加到流水线中。
if:
子句根据预定义 CI/CD 变量或自定义 CI/CD 变量。
关键字类型:特定于作业和特定于流水线。您可以将其用作作业的一部分来配置作业行为,或者使用 workflow 来配置流水线行为。
可能的输入:CI/CD 变量表达式。
rules:if
示例:
job:
script: echo "Hello, Rules!"
rules:
- if: $CI_MERGE_REQUEST_SOURCE_BRANCH_NAME =~ /^feature/ && $CI_MERGE_REQUEST_TARGET_BRANCH_NAME != $CI_DEFAULT_BRANCH
when: never
- if: $CI_MERGE_REQUEST_SOURCE_BRANCH_NAME =~ /^feature/
when: manual
allow_failure: true
- if: $CI_MERGE_REQUEST_SOURCE_BRANCH_NAME
额外细节:
- 如果规则匹配并且没有定义
when
,则规则使用为作业定义的when
,如果未定义,则默认为on_success
。 - 在 14.5 及更早版本中,您可以为每个规则定义一次
when
,或者在适用于所有规则的作业级别定义一次。 您不能将作业级别的when
与规则中的when
混用。 - 在 14.6 及更高版本中,您可以将作业级别的
when
与规则中的when
混合使用。rules
中的when
配置优先于在作业级别的when
。 - 与
script
部分中的变量不同,规则表达式中的变量始终格式为$VARIABLE
。- 您可以使用
rules:if
和include
来有条件地包含其他配置文件。
- 您可以使用
- 在 15.0 及更高版本中,
=~
和!~
表达式右侧的变量被认为是正则表达式。
rules:changes
使用 rules:changes
通过检查对特定文件的更改来指定何时将作业添加到流水线。
WARNING: 您应该仅将 rules: changes
用于 分支流水线 或 合并请求流水线。 您可以将 rules:changes
与其他管道类型一起使用,但是当没有 Git push
事件时,rules:changes
总是评估为 true。 标记流水线、计划流水线和手动流水线等没有与它们关联的 Git push
事件。 如果没有将作业限制为分支或合并请求管道的 if:
,则 rules: changes
作业总是 添加到这些管道中。
关键字类型:作业关键字。您只能将其用作作业的一部分。
可能的输入: 文件路径数组。在 13.6 及更高版本中,。
rules:changes
示例:
docker build:
script: docker build -t my-image:$CI_COMMIT_REF_SLUG .
rules:
- if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
changes:
- Dockerfile
when: manual
allow_failure: true
- 如果流水线是合并请求流水线,请检查
Dockerfile
是否有更改。 - 如果
Dockerfile
已更改,则将作业作为手动作业添加到流水线中,即使作业未触发,流水线也会继续运行(allow_failure: true
)。 - 如果
Dockerfile
没有改变,不要将作业添加到任何流水线(与when: never
相同)。
额外细节:
-
rules: changes
的工作方式与 only: changes 和 except: changes 相同。 - 您可以使用
when: never
来实现类似于 except:changes 的规则。 - 如果任何匹配的文件发生更改(
OR
操作),changes
将解析为true
。
rules:exists
当仓库中存在某些文件时,使用 exists
来运行作业。
关键字类型:作业关键字。您只能将其用作作业的一部分。
可能的输入:文件路径数组。路径相对于项目目录 ($CI_PROJECT_DIR
),不能直接链接到项目目录之外。文件路径可以使用 glob 模式。
rules:exists
示例:
job:
script: docker build -t my-image:$CI_COMMIT_REF_SLUG .
rules:
- exists:
- Dockerfile
job
runs if a Dockerfile
exists anywhere in the repository.
额外细节:
- Glob 模式使用 Ruby File.fnmatch 和标志
File::FNM_PATHNAME | File::FNM_DOTMATCH | File::FNM_EXTGLOB
。 - 出于性能原因,系统最多匹配 10,000 个
exists
pattern 或文件路径。在第 10,000 次检查之后,有 patterned globs的规则始终匹配。也就是说,exists
规则总是假设在超过 10,000 个文件的项目中匹配。 - 如果找到任何列出的文件,
exists
解析为true
(OR
操作)。
rules:allow_failure
在 rules:
中使用 allow_failure: true 允许作业在不停止流水线的情况下失败。
您还可以在手动作业中使用 allow_failure: true
。流水线继续运行,无需等待手动作业的结果。allow_failure: false
与规则中的 when: manual
结合导致流水线在继续之前等待手动作业运行。
关键字类型:作业关键字。您只能将其用作作业的一部分。
可能的输入:true
或 false
。如果未定义,则默认为 false
。
rules:allow_failure
示例:
job:
script: echo "Hello, Rules!"
rules:
- if: $CI_MERGE_REQUEST_TARGET_BRANCH_NAME == $CI_DEFAULT_BRANCH
when: manual
allow_failure: true
如果规则匹配,则该作业是带有 allow_failure: true
的手动作业。
额外细节:
- 规则级别
rules:allow_failure
覆盖作业级别 allow_failure,并且仅在特定规则触发作业时适用。
rules:variables
- 引入于 13.7 版本。
- 功能标志移除于 13.10 版本。
在 rules:
中使用 variables 来定义特定条件的变量。
关键字类型:特定于作业。您只能将其用作作业的一部分。
可能的输入:格式为 VARIABLE-NAME: value
的变量哈希。
rules:variables
示例:
job:
variables:
DEPLOY_VARIABLE: "default-deploy"
rules:
- if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH
variables: # Override DEPLOY_VARIABLE defined
DEPLOY_VARIABLE: "deploy-production" # at the job level.
- if: $CI_COMMIT_REF_NAME =~ /feature/
variables:
IS_A_FEATURE: "true" # Define a new variable.
script:
- echo "Run script with $DEPLOY_VARIABLE as an argument"
- echo "Run another script if $IS_A_FEATURE exists"
only / except
NOTE: only
和 except
没有被积极开发。rules 是控制何时向流水线添加作业的首选关键字。
您可以使用 only
和 except
来控制何时向流水线添加作业。
- 使用
only
来定义作业何时运行。 - 使用
except
定义作业 ** 不** 运行的时间。
only:refs
/ except:refs
使用 only:refs
和 except:refs
关键字来控制何时根据分支名称或流水线类型将作业添加到流水线中。
only:refs
和 except:refs
没有被积极开发。rules:if 是使用 refs、正则表达式或变量来控制何时将作业添加到流水线时的首选关键字。
关键字类型:作业关键字。您只能将其用作作业的一部分。
可能的输入:一个包含任意数量的数组:
-
分支名称,例如
main
或my-feature-branch
。 - 正则表达式匹配分支名称,例如 `/^feature-.*/`。
-
以下关键词:
值 描述 api
对于由 pipelines API 触发的流水线。 branches
当流水线的 Git 引用是一个分支时。 chat
对于使用 GitLab ChatOps 命令创建的流水线。 external
当您使用极狐GitLab 以外的 CI 服务时。 external_pull_requests
在 GitHub 上创建或更新外部拉取请求时。 merge_requests
对于在创建或更新合并请求时创建的流水线。启用合并请求流水线、合并结果流水线和合并队列。 pipelines
对于通过使用带有 CI_JOB_TOKEN
的 API 创建的多项目流水线或 trigger 关键字。pushes
对于由 git push
事件触发的流水线,包括分支和标签。schedules
对于计划流水线。 tags
当流水线的 Git 引用是标签时。 triggers
对于使用触发器令牌创建的流水线。 web
对于通过在 GitLab UI 中,从项目的 CI/CD > 流水线 部分选择 运行流水线 创建的流水线。
only:refs
和 except:refs
示例:
job1:
script: echo
only:
- main
- /^issue-.*$/
- merge_requests
job2:
script: echo
except:
- main
- /^stable-branch.*$/
- schedules
额外细节:
-
预定流水线在特定分支上运行,因此配置了
only: branch
的作业也可以在预定流水线上运行。添加except: schedules
以防止带有only: branch
的作业在预定流水线上运行。 -
only
或except
不使用任何其他关键字等价于only: refs
或except: refs
。例如,以下两个作业配置具有相同的行为:job1: script: echo only: - branches job2: script: echo only: refs: - branches
-
如果作业不使用
only
、except
或 rules,则only
默认设置为branches
和tags
。例如,
job1
和job2
是等价的:job1: script: echo "test" job2: script: echo "test" only: - branches - tags
only:variables
/ except:variables
根据 CI/CD 变量 的状态,使用 only:variables
或 except:variables
关键字来控制何时将作业添加到流水线中。
only:variables
和 except:variables
没有被积极开发。rules:if 是使用 refs、正则表达式或变量来控制何时将作业添加到流水线时的首选关键字。
关键字类型:作业关键字。您只能将其用作作业的一部分。
可能的输入:CI/CD 变量表达式的数组。
only:variables
示例:
deploy:
script: cap staging deploy
only:
variables:
- $RELEASE == "staging"
- $STAGING
only:changes
/ except:changes
当 Git 推送事件修改文件时,使用 changes
关键字和 only
来运行作业,或使用 except
来跳过作业。
在具有以下引用的流水线中使用 changes
:
branches
external_pull_requests
merge_requests
only:changes
和 except:changes
没有被积极开发。rules:if 是使用 refs、正则表达式或变量来控制何时将作业添加到流水线时的首选关键字。
关键字类型:作业关键字。您只能将其用作作业的一部分。
可能的输入:一个包含任意数量的数组:
- 文件路径。
- 单个目录的通配符路径,例如
path/to/directory/*
,或一个目录及其所有子目录,例如path/to/directory/**/*
。 - 具有相同扩展名或多个扩展名的所有文件的通配符 (glob) 路径,例如
*.md
或path/to/directory/*.{rb,py,sh}
。请参阅 Ruby fnmatch 文档 或支持的语法列表。 - 根目录或所有目录中文件的通配符路径,用双引号括起来。例如
"*.json"
或"**/*.json"
。
only:changes
示例:
docker build:
script: docker build -t my-image:$CI_COMMIT_REF_SLUG .
only:
refs:
- branches
changes:
- Dockerfile
- docker/scripts/*
- dockerfiles/**/*
- more_scripts/*.{rb,py,sh}
- "**/*.json"
额外细节:
- 如果任何匹配的文件发生更改(
OR
操作),changes
将解析为true
。 - 如果使用除
branches
、external_pull_requests
或merge_requests
以外的引用,changes
无法确定给定文件是新文件还是旧文件,并且总是返回true
。 - 如果您将
only: changes
与其他引用一起使用,作业将忽略更改并始终运行。 - 如果您将
except: changes
与其他引用一起使用,作业将忽略更改并且永远不会运行。
only:kubernetes
/ except:kubernetes
使用 only:kubernetes
或 except:kubernetes
来控制当 Kubernetes 服务在项目中处于活动状态时是否将作业添加到流水线中。
关键字类型:特定于作业。您只能将其用作作业的一部分。
可能的输入:kubernetes
策略只接受 active
关键字。
only:kubernetes
示例:
deploy:
only:
kubernetes: active
在此示例中,deploy
作业仅在项目中的 Kubernetes 服务处于活动状态时运行。
needs
- 引入于 12.2 版本。
- 于 12.3 版本,
needs
数组中的最大作业数从 5 增加到 50。- 于 12.8 版本,
needs: []
让作业立即开始。- 于 14.2 版本,您可以参考与您正在配置的作业处于同一阶段的作业。
使用 needs:
来不按顺序执行作业。使用 needs
的作业之间的关系可以可视化为有向无环图。
您可以忽略阶段排序并运行一些作业,而无需等待其他作业完成。 多个阶段的作业可以同时运行。
关键字类型:作业关键字。您只能将其用作作业的一部分。
可能的输入:
- 一个数组的作业。
- 一个空数组 (
[]
),用于将作业设置为在创建流水线后立即启动。
needs
示例:
linux:build:
stage: build
script: echo "Building linux..."
mac:build:
stage: build
script: echo "Building mac..."
lint:
stage: test
needs: []
script: echo "Linting..."
linux:rspec:
stage: test
needs: ["linux:build"]
script: echo "Running rspec on linux..."
mac:rspec:
stage: test
needs: ["mac:build"]
script: echo "Running rspec on mac..."
production:
stage: deploy
script: echo "Running production..."
示例创建四个执行路径:
- Linter:
lint
作业立即运行,无需等待build
阶段完成,因为它没有需求(needs: []
)。 - Linux 路径:
linux:rspec
和linux:rubocop
作业在linux:build
作业完成后立即运行,无需等待mac:build
完成。 - macOS 路径:
mac:rspec
和mac:rubocop
作业在mac:build
作业完成后立即运行,无需等待linux:build
完成。 -
production
作业在所有先前的作业完成后立即运行;在这种情况下:linux:build
、linux:rspec
、linux:rubocop
、mac:build
、mac:rspec
、mac:rubocop
。
额外细节:
-
needs:
数组中单个作业可以需要的最大作业数是有限的:- 对于自助管理实例,默认限制为 50。此限制可以更改。
- 如果
needs:
指的是使用 parallel 关键字的作业,它取决于并行创建的所有作业,而不仅仅是一个作业。 默认情况下,它还从所有并行作业下载产物。如果产物具有相同的名称,它们会相互覆盖,并且只保存最后下载的产物。 - 在 14.1 及更高版本中,您可以引用与您正在配置的作业处于同一阶段的作业。在自助管理的 14.2 及更高版本上,此功能默认可用。
- 在 14.0 及更早版本中,您只能引用早期阶段的作业。必须为所有使用
needs:
关键字或在作业的needs:
部分中引用的作业明确定义阶段。 - 在 13.9 及更早版本中,如果
needs:
指的是由于only
、except
或rules
可能无法添加到流水线中的作业,则流水线可能无法创建。
needs:artifacts
当作业使用 needs
时,默认情况下它不再下载前一阶段的所有产物,因为带有 needs
的作业可以在早期阶段完成之前开始。使用 needs
,您只能从 needs:
配置中列出的作业中下载产物。
使用 artifacts: true
(默认)或 artifacts: false
来控制何时在使用 needs
的作业中下载产物。
关键字类型:作业关键字。您只能将其用作作业的一部分。 Must be used with needs:job
.
可能的输入:
-
true
(默认)或false
.
needs:artifacts
示例:
test-job1:
stage: test
needs:
- job: build_job1
artifacts: true
test-job2:
stage: test
needs:
- job: build_job2
artifacts: false
test-job3:
needs:
- job: build_job1
artifacts: true
- job: build_job2
- build_job3
在这个例子中:
-
test-job1
作业下载build_job1
产物 -
test-job2
作业不会下载build_job2
产物。 -
test-job3
作业从所有三个build_jobs
下载产物,因为对于所有三个需要的作业,artifacts:
是true
,或默认为true
。
额外细节:
- 在 12.6 及更高版本中,您不能将 dependencies 关键字与
needs
结合使用。
needs:project
(PREMIUM)
使用 needs:project
从其他流水线中最多五个作业下载产物。 从指定引用的最新成功流水线下载产物。 要指定多个作业,请将每个作业添加为 needs
关键字下的单独数组项。
如果为指定的 ref 运行流水线,则带有 needs:project
的作业不会等待流水线完成。相反,该作业从成功完成的最新流水线下载产物。
needs:project
必须与 job:
、ref:
和 artifacts:
一起使用。
关键字类型:作业关键字。您只能将其用作作业的一部分。
可能的输入:
-
needs:project
:完整的项目路径,包括命名空间和群组。 -
job
:从中下载产物的作业。 -
ref
:从中下载产物的引用。 -
artifacts
:必须为true
才能下载产物。
needs:project
示例:
build_job:
stage: build
script:
- ls -lhR
needs:
- project: namespace/group/project-name
job: build-1
ref: main
artifacts: true
- project: namespace/group/project-name-2
job: build-2
ref: main
artifacts: true
在此示例中,build_job
从 group/project-name
和 group/project-name-2
项目中的 main
分支上最新成功的 build-1
和 build-2
作业下载产物。
在 13.3 及更高版本中,您可以在 needs:project
中使用 CI/CD 变量,例如:
build_job:
stage: build
script:
- ls -lhR
needs:
- project: $CI_PROJECT_PATH
job: $DEPENDENCY_JOB_NAME
ref: $ARTIFACTS_DOWNLOAD_REF
artifacts: true
额外细节:
- 要从当前项目中的不同流水线下载产物,请将
project:
设置为与当前项目相同,但使用与当前流水线不同的引用。在同一个 ref 上运行的并发流水线可能会覆盖产物。 - 运行流水线的用户必须至少具有组或项目的报告者角色,或者群组/项目必须具有公开可见性。
- 你不能在与 trigger 相同的作业中使用
needs:project
。 - 当使用
needs:project
从另一个流水线下载产物时,作业不会等待所需的作业完成。有向无环图仅限于同一流水线中的作业。确保其他流水线中所需的作业在需要它的作业尝试下载产物之前完成。 - 您无法从在 parallel: 中运行的作业下载产物。
- 13.3 中引入了对
project
、job
和ref
中的 CI/CD 变量的支持。 13.4 中删除了功能标志。
needs:pipeline:job
引入于 13.7 版本。
子流水线 可以从其父流水线或同一父子流水线层次结构中的另一个子流水线中的作业下载产物。
关键字类型:作业关键字。您只能将其用作作业的一部分。
可能的输入:
-
needs:pipeline
:流水线 ID。必须是存在于同一父子流水线层次结构中的流水线。 -
job:
:从中下载产物的作业。
needs:pipeline:job
示例:
-
父流水线 (
.gitlab-ci.yml
):create-artifact: stage: build script: echo 'sample artifact' > artifact.txt artifacts: paths: [artifact.txt] child-pipeline: stage: test trigger: include: child.yml strategy: depend variables: PARENT_PIPELINE_ID: $CI_PIPELINE_ID
-
子流水线 (
child.yml
):use-artifact: script: cat artifact.txt needs: - pipeline: $PARENT_PIPELINE_ID job: create-artifact
在此示例中,父流水线中的 create-artifact
作业创建了一些产物。child-pipeline
作业触发子流水线,并将 CI_PIPELINE_ID
变量作为新的 PARENT_PIPELINE_ID
变量传递给子流水线。子流水线可以使用 needs:pipeline
中的变量从父流水线下载产物。
额外细节:
-
pipeline
属性不接受当前的流水线 ID ($CI_PIPELINE_ID
)。要从当前流水线中的作业下载产物,请使用 needs。
needs:optional
- 引入于 13.10 版本。
- 功能标志移除于 14.0 版本。
如果需要有时在流水线中不存在的作业,请将 optional: true
添加到 needs
配置中。如果未定义,optional: false
是默认值。
使用 rules、only 或 except 的作业可能并不总是添加到流水线中。系统在启动流水线之前检查 needs
关系:
- 如果需求条目具有
optional: true
并且所需的作业存在于流水线中,则作业会在开始之前等待它完成。 - 如果所需的作业不存在,则可以在满足所有其他 needs 要求时开始该作业。
- 如果
needs
部分仅包含可选作业,并且没有添加到流水线中,则作业会立即启动(与空的needs
条目相同:needs: []
)。 - 如果需要的作业有
optional: false
,但未添加到流水线,则流水线无法启动,并出现类似以下错误:'job1' job needs 'job2' job, but it was not added to the pipeline
。
关键字类型:作业关键字。您只能将其用作作业的一部分。
needs:optional
示例:
build-job:
stage: build
test-job1:
stage: test
test-job2:
stage: test
rules:
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
deploy-job:
stage: deploy
needs:
- job: test-job2
optional: true
- job: test-job1
review-job:
stage: deploy
needs:
- job: test-job2
optional: true
在这个例子中:
-
build-job
、test-job1
和test-job2
按阶段顺序开始。 - 当分支是默认分支时,
test-job2
被添加到流水线中,所以:-
deploy-job
等待test-job1
和test-job2
完成。 -
review-job
等待test-job2
完成。
-
- 当分支不是默认分支时,
test-job2
不会添加到流水线中,所以:-
deploy-job
只等待test-job1
完成,而不等待错过的test-job2
。 -
review-job
没有其他需要的作业并立即启动(与build-job
同时),如needs: []
。
-
needs:pipeline
您可以使用 needs:pipeline
关键字将流水线状态从上游流水线镜像到桥接作业。来自默认分支的最新流水线状态被复制到桥接作业。
关键字类型:作业关键字。您只能将其用作作业的一部分。
可能的输入:
- 完整的项目路径,包括命名空间和群组。如果项目在同一个组或命名空间中,你可以从
project:
关键字中省略它们。例如:project: group/project-name
或project: project-name
。
needs:pipeline
示例:
upstream_bridge:
stage: test
needs:
pipeline: other/project
额外细节:
- 如果您将
job
关键字添加到needs:pipeline
,该作业将不再反映流水线状态。更改为 needs:pipeline:job。
tags
- 于 14.3 版本,在自助管理版上启用的每个作业限制为 50 个标签。
使用 tags
从项目可用的所有 runner 列表中选择一个特定的 runner。
注册 runner 时,您可以指定 runner 的标签,例如 ruby
、postgres
或 development
。要获取并运行作业,必须为 runner 分配作业中列出的每个标签。
关键字类型:作业关键字。您只能将其用作作业的一部分或在 default: 部分 中使用。
可能的输入:
- 标签名称数组。
- 14.1 及更高版本中的 CI/CD 变量。
tags
示例:
job:
tags:
- ruby
- postgres
在此示例中,只有同时具有 ruby
和 postgres
标签的 runner 才能运行该作业。
额外细节:
- 在 14.3 及更高版本中,标签数量必须小于
50
。
allow_failure
使用 allow_failure
来确定当作业失败时,流水线是否应该继续运行。
- 要让流水线继续运行后续作业,请使用
allow_failure: true
。 - 要停止流水线运行后续作业,请使用
allow_failure: false
。
当允许作业失败 (allow_failure: true
) 时,橙色警告 ({status_warning}) 表示作业失败。但是,流水线是成功的,并且关联的提交被标记为已通过且没有警告。
在以下情况下会显示相同的警告:
- 阶段中的所有其他工作均成功。
- 流水线中的所有其他作业均成功。
allow_failure
的默认值为:
- 手动作业为 `true`。
- 对于在 rules 中使用
when:manual
的作业为false
。 - 在所有其它情况下为
false
。
关键字类型:作业关键字。您只能将其用作作业的一部分。
可能的输入:true
或 false
。
allow_failure
示例:
job1:
stage: test
script:
- execute_script_1
job2:
stage: test
script:
- execute_script_2
allow_failure: true
job3:
stage: deploy
script:
- deploy_to_staging
在这个例子中,job1
和 job2
并行运行:
- 如果
job1
失败,deploy
阶段的作业不会启动。 - 如果
job2
失败,deploy
阶段的作业仍然可以启动。
额外细节:
- 您可以使用
allow_failure
作为 rules: 的子键。 - 您可以在手动作业中使用
allow_failure: false
来创建阻塞的手动作业。在手动作业启动并成功完成之前,阻塞的流水线不会在后续阶段运行任何作业。
allow_failure:exit_codes
- 引入于 13.8 版本。
- 功能标志移除于 13.9 版本。
使用 allow_failure:exit_codes
来控制何时允许作业失败。对于任何列出的退出代码,作业是 allow_failure: true
,对于任何其他退出代码,allow_failure
为 false。
关键字类型:作业关键字。您只能将其用作作业的一部分。
可能的输入:
- 单个退出代码。
- 退出代码数组。
allow_failure
示例:
test_job_1:
script:
- echo "Run a script that results in exit code 1. This job fails."
- exit 1
allow_failure:
exit_codes: 137
test_job_2:
script:
- echo "Run a script that results in exit code 137. This job is allowed to fail."
- exit 137
allow_failure:
exit_codes:
- 137
- 255
when
使用 when
配置作业运行的条件。如果未在作业中定义,则默认值为 when: on_success
。
关键字类型:作业关键字。您可以将其用作作业的一部分。when: always
和 when: never
也可以在 workflow:rules 中使用。
可能的输入:
-
on_success
(默认):仅当早期阶段的所有作业都成功或具有allow_failure: true
时才运行作业。 -
manual
:仅在手动触发时运行作业。 -
always
:无论早期阶段的作业状态如何,都运行作业。也可以在workflow:rules
中使用。 -
on_failure
:只有在早期阶段至少有一个作业失败时才运行作业。 -
delayed
:作业的执行延迟指定的持续时间。 -
never
:不要运行作业。只能在 rules 部分或workflow: rules
中使用。
when
示例:
stages:
- build
- cleanup_build
- test
- deploy
- cleanup
build_job:
stage: build
script:
- make build
cleanup_build_job:
stage: cleanup_build
script:
- cleanup build when failed
when: on_failure
test_job:
stage: test
script:
- make test
deploy_job:
stage: deploy
script:
- make deploy
when: manual
cleanup_job:
stage: cleanup
script:
- cleanup after jobs
when: always
在这个例子中,脚本:
- 只有当
build_job
失败时才执行cleanup_build_job
。 - 无论成功或失败,始终将
cleanup_job
作为流水线的最后一步执行。 - 在 GitLab UI 中手动运行时执行
deploy_job
。
额外细节:
- 在 13.5 及更高版本中,您可以在与 trigger 相同的作业中使用
when:manual
。在 13.4 及更早版本中,将它们一起使用会导致错误jobs:#{job-name} when should be on_success, on_failure or always
。 -
allow_failure
的默认行为通过when: manual
更改为true
。但是,如果您将when: manual
与 rules 一起使用,allow_failure
默认为false
。
environment
使用 environment
定义作业部署到的环境。
关键字类型:作业关键字。您只能将其用作作业的一部分。
可能的输入:作业部署到的环境的名称,采用以下格式之一:
- 纯文本,包括字母、数字、空格和以下字符:
-
、_
、/
、$
、{
、}
。 - CI/CD 变量,包括在
.gitlab-ci.yml
文件中定义的预定义、安全或变量。您不能使用在script
部分中定义的变量。
environment
示例:
deploy to production:
stage: deploy
script: git push production HEAD:main
environment: production
额外细节:
- 如果您指定了一个
environment
并且不存在具有该名称的环境,则会创建一个环境。
environment:name
为环境设置名称。
常见的环境名称是 qa
、staging
和 production
,但您可以使用任何名称。
关键字类型:作业关键字。您只能将其用作作业的一部分。
可能的输入:作业部署到的环境的名称,采用以下格式之一:
- 纯文本,包括字母、数字、空格和以下字符:
-
、_
、/
、$
、{
、}
。 - CI/CD 变量,包括在
.gitlab-ci.yml
文件中定义的预定义、安全或变量。 您不能使用在script
部分中定义的变量。
environment:name
示例:
deploy to production:
stage: deploy
script: git push production HEAD:main
environment:
name: production
environment:url
为环境设置 URL。
关键字类型:作业关键字。您只能将其用作作业的一部分。
可能的输入:单个 URL,采用以下格式之一:
- 纯文本,如
https://prod.example.com
。 - CI/CD 变量,包括在
.gitlab-ci.yml
文件中定义的预定义、安全或变量。 您不能使用在script
部分中定义的变量。
environment:url
示例:
deploy to production:
stage: deploy
script: git push production HEAD:main
environment:
name: production
url: https://prod.example.com
额外细节:
- 作业完成后,您可以通过选择合并请求、环境或部署页面中的按钮来访问 URL。
environment:on_stop
关闭(停止)环境可以通过在 environment
下定义的 on_stop
关键字来实现。 它声明了一个为了关闭环境而运行的不同作业。
关键字类型:作业关键字。您只能将其用作作业的一部分。
额外细节:
- 有关更多详细信息和示例,请参阅 environment:action。
environment:action
使用 action
关键字来指定作业如何与环境交互。
值 | 描述 |
---|---|
start |
默认值。 表示作业启动环境。部署是在作业启动后创建的。 |
prepare |
表示作业只准备环境。它不会触发部署。 |
stop |
表示作业停止部署。请参阅下面的示例。 |
举例:
review_app:
stage: deploy
script: make deploy-app
environment:
name: review/$CI_COMMIT_REF_SLUG
url: https://$CI_ENVIRONMENT_SLUG.example.com
on_stop: stop_review_app
stop_review_app:
stage: deploy
variables:
GIT_STRATEGY: none
script: make delete-app
when: manual
environment:
name: review/$CI_COMMIT_REF_SLUG
action: stop
在上面的例子中,review_app
作业部署到 review
环境。在 on_stop
下列出了一个新的 stop_review_app
作业。在 review_app
作业完成后,它会根据 when
下定义的内容触发 stop_review_app
作业。在这种情况下,它被设置为 manual
,因此它需要来自 GitLab UI 的手动操作运行。
同样在示例中,GIT_STRATEGY
设置为 none
。如果 stop_review_app
作业自动触发,则 runner 在删除分支后不会尝试检出代码。
该示例还覆盖了全局变量。如果您的 stop
environment
作业依赖于全局变量,请在设置 GIT_STRATEGY
且在不覆盖全局变量的情况下,更改作业时使用锚点变量。
stop_review_app
作业需要定义以下关键字:
-
when
,定义于:- 作业级别。
-
在规则子句中。如果使用
rules:
和when: manual
,您还应该设置 allow_failure: true,这样即使作业没有运行,可实现也可以完成。
environment:name
environment:action
此外,两个作业都应该具有匹配的 rules 或 only/except 配置。
在上面的示例中,如果配置不相同:
-
stop_review_app
作业可能不会包含在包含review_app
作业的所有流水线中。 - 无法触发
action: stop
来自动停止环境。
environment:auto_stop_in
auto_stop_in
关键字指定环境的生命周期。当环境过期时,系统会自动停止它。
关键字类型:作业关键字。您只能将其用作作业的一部分。
可能的输入:用自然语言编写的一段时间。 例如,这些都是等价的:
168 hours
7 days
one week
environment:auto_stop_in
示例:
review_app:
script: deploy-review-app
environment:
name: review/$CI_COMMIT_REF_SLUG
auto_stop_in: 1 day
当为 review_app
创建环境时,环境的生命周期设置为 1 day
。 每次部署 review app 时,该生命周期也会重置为 1 day
。
environment:kubernetes
使用 kubernetes
关键字将部署配置到与您的项目关联的 Kubernetes 集群。
关键字类型:作业关键字。您只能将其用作作业的一部分。
environment:kubernetes
示例:
deploy:
stage: deploy
script: make deploy-app
environment:
name: production
kubernetes:
namespace: production
此配置使用 production
Kubernetes 命名空间。
额外细节:
- 由极狐GitLab 管理 的 Kubernetes 集群不支持 Kubernetes 配置。
environment:deployment_tier
引入于 13.10 版本。
使用 deployment_tier
关键字指定部署环境的层级。
关键字类型:作业关键字。您只能将其用作作业的一部分。
可能的输入:以下之一:
production
staging
testing
development
other
environment:deployment_tier
示例:
deploy:
script: echo
environment:
name: customer-portal
deployment_tier: production
动态环境
使用 CI/CD 变量动态命名环境。
例如:
deploy as review app:
stage: deploy
script: make deploy
environment:
name: review/$CI_COMMIT_REF_SLUG
url: https://$CI_ENVIRONMENT_SLUG.example.com/
deploy as review app
作业被标记为动态创建 review/$CI_COMMIT_REF_SLUG
环境的部署。$CI_COMMIT_REF_SLUG
是由 runner 设置的 CI/CD 变量。$CI_ENVIRONMENT_SLUG
变量基于环境名称,但适合包含在 URL 中。如果 deploy as review app
作业在名为 pow
的分支中运行,则可以使用类似 https://review-pow.example.com/
的 URL 访问该环境。
常见的用例是为分支机构创建动态环境并将它们用作审核应用程序。
cache
使用 cache
指定要在作业之间缓存的文件和目录列表。您只能使用本地工作副本中的路径。
缓存在流水线和作业之间共享。缓存在产物之前恢复。
cache:paths
使用 cache:paths
关键字来选择要缓存的文件或目录。
关键字类型:作业关键字。您只能将其用作作业的一部分或在 default: 部分 中使用。
可能的输入:相对于项目目录的路径数组($CI_PROJECT_DIR
)。您可以使用使用 glob 模式的通配符:
- 在 GitLab Runner 13.0 及更高版本中,doublestar.Glob。
- 在 GitLab Runner 12.10 及更早版本中,filepath.Match。
cache:paths
示例:
缓存 binaries
中以 .apk
和 .config
文件结尾的所有文件:
rspec:
script:
- echo "This job uses a cache."
cache:
key: binaries-cache
paths:
- binaries/*.apk
- .config
cache:key
使用 cache:key
关键字为每个缓存提供唯一的标识键。使用相同缓存键的所有作业都使用相同的缓存,包括在不同的流水线中。
如果未设置,则默认键为 default
。所有带有 cache:
关键字但没有 cache:key
的作业共享 default
缓存。
必须与 cache: path
一起使用,否则不会缓存任何内容。
关键字类型:作业关键字。您只能将其用作作业的一部分或在 default: 部分 中使用。
可能的输入:
- 一个字符串。
- 预定义变量。
- 两者的结合。
cache:key
示例:
cache-job:
script:
- echo "This job uses a cache."
cache:
key: binaries-cache-$CI_COMMIT_REF_SLUG
paths:
- binaries/
额外细节:
-
如果你使用 Windows Batch 运行你的 shell 脚本,你需要用
%
替换$
。 例如:密钥:%CI_COMMIT_REF_SLUG%
-
cache:key
值不能包含:-
/
字符,或等效的 URI 编码的%2F
。 - 只有
.
字符(任何数字),或等效的 URI 编码的%2E
。
-
-
缓存在作业之间共享,因此如果您为不同的作业使用不同的路径,您还应该设置不同的
cache:key
。 否则缓存内容可能会被覆盖。
cache:key:files
使用 cache:key:files
关键字在一两个特定文件更改时生成新密钥。cache:key:files
可让您重用一些缓存,并减少重建它们的频率,从而加快后续流水线运行的速度。
关键字类型:作业关键字。您只能将其用作作业的一部分或在 default: 部分 中使用。
可能的输入:一个或两个文件路径的数组。
cache:key:files
示例:
cache-job:
script:
- echo "This job uses a cache."
cache:
key:
files:
- Gemfile.lock
- package.json
paths:
- vendor/ruby
- node_modules
此示例为 Ruby 和 Node.js 依赖项创建缓存。缓存绑定到当前版本的 Gemfile.lock
和 package.json
文件。当这些文件之一发生变化时,将计算一个新的缓存键并创建一个新的缓存。任何使用相同的 Gemfile.lock
和 package.json
以及 cache:key:files
的未来作业都会使用新的缓存,而不是重建依赖项。
额外信息:缓存 key
是根据最近更改了每个列出的文件的提交计算得出的 SHA。如果在任何提交中都没有更改任何文件,则回退键是 default
。
cache:key:prefix
使用 cache:key:prefix
将前缀与为 cache:key:files 计算的 SHA 结合起来。
关键字类型:作业关键字。您只能将其用作作业的一部分或在 default: 部分 中使用。
可能的输入:
- 一个字符串
- 预定义变量
- 两者的结合。
cache:key:prefix
示例:
rspec:
script:
- echo "This rspec job uses a cache."
cache:
key:
files:
- Gemfile.lock
prefix: $CI_JOB_NAME
paths:
- vendor/ruby
例如,添加 $CI_JOB_NAME
的 prefix
会使密钥看起来像 rspec-feef9576d21ee9b6a32e30c5c79d0a0ceb68d1e5
。 如果分支更改了 Gemfile.lock
,则该分支会为 cache:key:files
提供一个新的 SHA 校验和。 生成一个新的缓存键,并为该键创建一个新的缓存。如果没有找到 Gemfile.lock
,前缀会被添加到 default
,因此示例中的键是 rspec-default
。
额外细节:如果在任何提交中都没有更改 cache:key:files
中的文件,则会将前缀添加到 default
键。
cache:untracked
使用 untracked: true
来缓存 Git 仓库中所有未跟踪的文件:
关键字类型:作业关键字。您只能将其用作作业的一部分或在 default: 部分 中使用。
可能的输入:true
或 false
(默认)。
cache:untracked
示例:
rspec:
script: test
cache:
untracked: true
额外细节:
-
您可以将
cache:untracked
与cache:paths
结合使用来缓存所有未跟踪的文件以及配置路径中的文件。例如:rspec: script: test cache: untracked: true paths: - binaries/
cache:when
使用 cache:when
定义何时根据作业的状态保存缓存。
关键字类型:作业关键字。您只能将其用作作业的一部分或在 default: 部分 中使用。
可能的输入:
-
on_success
(默认):仅在作业成功时保存缓存。 -
on_failure
:仅在作业失败时保存缓存。 -
always
:始终保存缓存。
cache:when
示例:
rspec:
script: rspec
cache:
paths:
- rspec/
when: 'always'
无论作业是失败还是成功,此示例都会存储缓存。
cache:policy
要更改缓存的上传和下载行为,请使用 cache:policy
关键字。 默认情况下,作业在作业开始时下载缓存,并在作业结束时将更改上传到缓存。 这是 pull-push
策略(默认)。
要将作业设置为仅在作业开始时下载缓存,但在作业完成时从不上传更改,请使用 cache:policy:pull
。
要将作业设置为仅在作业完成时上传缓存,但在作业开始时从不下载缓存,请使用 cache:policy:push
。
当您有许多使用相同缓存并行执行的作业时,请使用 pull
策略。 此策略可加快作业执行速度并减少缓存服务器上的负载。 您可以使用带有 push
策略的作业来构建缓存。
必须与 cache: path
一起使用,否则不会缓存任何内容。
关键字类型:作业关键字。您只能将其用作作业的一部分或在 default: 部分 中使用。
可能的输入:
pull
push
-
pull-push
(默认)
cache:policy
示例:
prepare-dependencies-job:
stage: build
cache:
key: gems
paths:
- vendor/bundle
policy: push
script:
- echo "This job only downloads dependencies and builds the cache."
- echo "Downloading dependencies..."
faster-test-job:
stage: test
cache:
key: gems
paths:
- vendor/bundle
policy: pull
script:
- echo "This job script uses the cache, but does not update it."
- echo "Running tests..."
dependencies
使用 dependencies
关键字定义要从中获取产物的作业列表。 您还可以设置一个作业以完全不下载任何产物。
如果您不使用 dependencies
,则前一阶段的所有产物都会传递给每个作业。
关键字类型:作业关键字。您只能将其用作作业的一部分。
可能的输入:
- 从中获取产物的作业名称。
- 一个空数组 (
[]
),用于将作业配置为不下载任何产物。
dependencies
示例:
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
在这个例子中,两个作业有产物:build osx
和 build linux
。当执行 test osx
时,build osx
的产物被下载并在构建的上下文中提取。 同样的事情发生在 test linux
和 build linux
的产物上。
由于 stage 优先级,deploy
作业从所有以前的作业下载产物。
额外细节:
- 作业状态无关紧要。如果作业失败或者是未触发的手动作业,则不会发生错误。
- 如果依赖作业的产物是已过期或已删除,则作业失败。
artifacts
使用 artifacts
指定在作业 succeeds, fails, 或 always 时附加到作业的文件和目录列表。
作业完成后,产物将发送到 GitLab。如果大小不大于最大产物大小,它们可以在 GitLab UI 中下载。
默认情况下,后期的作业会自动下载早期作业创建的所有产物。您可以使用 dependencies 控制作业中的产物下载行为。
使用 needs
关键字时,作业只能从 needs
配置中定义的作业下载产物。
默认只收集成功作业的作业产物,产物在缓存后恢复。
阅读有关产物的更多信息。
artifacts:exclude
exclude
可以防止将文件添加到产物存档中。
类似于 artifacts:paths,exclude
路径是相对于项目目录的。您可以使用使用 glob 或 doublestar.PathMatch 模式的通配符。
例如,要将所有文件存储在 binaries/
中,但不存储位于 binaries/
子目录中的 *.o
文件:
artifacts:
paths:
- binaries/
exclude:
- binaries/**/*.o
与 artifacts:paths 不同,exclude
路径不是递归的。要排除目录的所有内容,您可以显式匹配它们而不是匹配目录本身。
例如,要将所有文件存储在 binaries/
中,但不存储在 temp/
子目录中:
artifacts:
paths:
- binaries/
exclude:
- binaries/temp/**/*
与 artifacts:untracked 匹配的文件也可以使用 artifacts:exclude
排除。
artifacts:expire_in
- 引入于 13.0 版本,在功能标志后默认禁用,无论到期时间如何,都会保留最新的作业产物。
- 默认启用于 13.4.
- 引入于 13.8 版本,可以在项目级别禁用保持最新的作业产物。
- 引入于 13.9 版本,可以在实例范围内禁用保持最新的作业产物。
- 引入于 13.12 版本,无论到期时间如何,都会保留最新的流水线产物。
使用 expire_in
指定作业产物在它们过期和被删除之前存储多长时间。expire_in
设置不会影响:
- 来自最新作业的产物,除非保留最新的作业产物:
- 在项目级别禁用。
- 在实例范围禁用。
-
流水线产物。无法为这些指定到期日期:
- 来自最新流水线的流水线产物将永远保留。
- 一周后删除其他流水线产物。
expire_in
的值是以秒为单位的经过时间,除非提供了单位。有效值包括:
'42'
42 seconds
3 mins 4 sec
2 hrs 20 min
2h20min
6 mos 1 day
47 yrs 6 mos and 4d
3 weeks and 2 days
never
要在上传后一周使产物过期:
job:
artifacts:
expire_in: 1 week
当产物上传并存储在极狐GitLab 上时,到期时间段开始。如果未定义到期时间,则默认为实例范围设置(默认为 30 天)。
要覆盖到期日期并保护产物不被自动删除:
- 使用作业页面上的保留按钮。
- 在 13.3 及更高版本中,将
expire_in
的值设置为never
。
过期后,产物默认每小时删除一次(使用 cron 作业),并且不再可访问。
artifacts:expose_as
使用 expose_as
关键字在合并请求 UI 中公开作业产物。
例如,要匹配单个文件:
test:
script: ["echo 'test' > file.txt"]
artifacts:
expose_as: 'artifact 1'
paths: ['file.txt']
通过此配置,极狐GitLab 添加了一个链接 artifact 1 到指向 file1.txt
的相关合并请求。要访问该链接,请选择合并请求概览中流水线图下方的 查看已展示的产物。
匹配整个目录的示例:
test:
script: ["mkdir test && echo 'test' > test/file.txt"]
artifacts:
expose_as: 'artifact 1'
paths: ['test/']
请注意以下事项:
- 使用变量定义
artifacts:paths
时,不会在合并请求 UI 中显示产物。 - 每个合并请求最多可以公开 10 个作业产物。
- 不支持全局模式。
- 如果指定了目录,如果目录中有多个文件,则链接指向作业产物浏览器。
- 对于带有
.html
、.htm
、.txt
、.json
、.xml
和.log
扩展名的公开单个文件产物,如果 GitLab Pages:- 启用,系统自动呈现产物。
- 未启用,文件显示在产物浏览器中。
artifacts:name
使用 name
指令来定义创建的产物存档的名称。您可以为每个存档指定唯一的名称。artifacts:name
变量可以使用任何预定义变量。 默认名称是 artifacts
,下载后会变成 artifacts.zip
。
要使用当前作业的名称创建存档:
job:
artifacts:
name: "$CI_JOB_NAME"
paths:
- binaries/
要使用当前分支或标记的名称创建档案,仅包括二进制目录:
job:
artifacts:
name: "$CI_COMMIT_REF_NAME"
paths:
- binaries/
如果您的分支名称包含正斜杠(例如feature/my-feature
),建议使用 $CI_COMMIT_REF_SLUG
而不是 $CI_COMMIT_REF_NAME
来正确命名产物。
要使用当前作业的名称和当前的分支或标记创建仅包含二进制文件目录的存档:
job:
artifacts:
name: "$CI_JOB_NAME-$CI_COMMIT_REF_NAME"
paths:
- binaries/
要使用当前 stage 和分支名称的名称创建存档:
job:
artifacts:
name: "$CI_JOB_STAGE-$CI_COMMIT_REF_NAME"
paths:
- binaries/
如果您使用 Windows Batch 运行您的 shell 脚本,你需要用 %
替换 $
:
job:
artifacts:
name: "%CI_JOB_STAGE%-%CI_COMMIT_REF_NAME%"
paths:
- binaries/
如果您使用 Windows PowerShell 运行您的 shell 脚本,你需要用 $env:
替换 $
:
job:
artifacts:
name: "$env:CI_JOB_STAGE-$env:CI_COMMIT_REF_NAME"
paths:
- binaries/
artifacts:paths
路径相对于项目目录 ($CI_PROJECT_DIR
),不能直接链接到项目目录之外。您可以使用 glob 模式的通配符和:
- 在 GitLab Runner 13.0 和更高版本,doublestar.Glob。
- 在 GitLab Runner 12.10 和更早版本,filepath.Match。
要限制特定作业从哪些作业获取工件,请参阅 dependencies。
发送 binaries
和 .config
中的所有文件:
artifacts:
paths:
- binaries/
- .config
要禁用产物传递,请使用空 dependencies 定义作业:
job:
stage: build
script: make build
dependencies: []
您可能只想为标签版本创建产物,以避免使用临时构建产物填充构建服务器存储。
仅为标签创建产物(default-job
不创建产物):
default-job:
script:
- mvn test -U
rules:
- if: $CI_COMMIT_BRANCH
release-job:
script:
- mvn package -U
artifacts:
paths:
- target/*.war
rules:
- if: $CI_COMMIT_TAG
您也可以对目录使用通配符。例如,如果您想获取以 xyz
结尾的目录中的所有文件:
job:
artifacts:
paths:
- path/*xyz/*
artifacts:public
- 引入于 13.8 版本
- 部署在功能标志后默认禁用
- 推荐用于生产用途
FLAG: 在自我管理实例上,默认情况下此功能不可用。 要使其可用,请让管理员启用命名为 non_public_artifacts 的功能标志 。在 SaaS 版上,此功能不可用。
使用 artifacts:public
来确定作业产物是否应该公开可用。
artifacts:public
的默认值为 true
,这意味着匿名和访客用户可以下载公共流水线中的产物:
artifacts:
public: true
要拒绝匿名用户和来宾用户对公共流水线中的产物的读取访问权限,请将 artifacts:public
设置为 false
:
artifacts:
public: false
artifacts:reports
使用 artifacts:reports:
- 从作业中收集测试报告、代码质量报告和安全报告。
- 在合并请求、流水线视图和安全仪表盘中公开这些报告。
无论作业结果如何(成功或失败),都会收集测试报告。 您可以使用 artifacts:expire_in 为其产物设置到期日期。
某些 artifacts:reports
类型可以由同一流水线中的多个作业生成,并由每个作业的合并请求或流水线功能使用。
为了能够浏览报告输出文件,请包含 artifacts:paths 关键字。请注意,将上传和存储产物两次。
NOTE: 不支持使用来自子流水线的产物的父流水线的组合报告。
artifacts:reports:accessibility
(FREE)
accessibility
报告使用 pa11y 报告合并请求中引入的更改对可访问性的影响。
极狐GitLab 可以在合并请求可访问性部件中显示一个或多个报告的结果。
artifacts:reports:api_fuzzing
(ULTIMATE)
api_fuzzing
报告收集了 API Fuzzing bug 作为产物。
artifacts:reports:browser_performance
(PREMIUM)
- 名称从
artifacts:reports:performance
改为现名称于 14.0 版本。
browser_performance
报告收集浏览器性能测试指标作为产物。
极狐GitLab 可以在合并请求中显示一份报告的结果。
极狐GitLab 无法显示多个 browser_performance
报告的组合结果。
artifacts:reports:cluster_image_scanning
(ULTIMATE)
- 引入于 14.1 版本。
- 需要 GitLab Runner 14.1 和更高版本。
cluster_image_scanning
报告收集 CLUSTER_IMAGE_SCANNING
漏洞作为产物。
artifacts:reports:cobertura
cobertura
报告收集 Cobertura 覆盖 XML 文件。 收集的 Cobertura 覆盖率报告作为产物上传到极狐GitLab 并显示在合并请求中。
Cobertura 最初是为 Java 开发的,但有许多第三方移植用于其他语言,如 JavaScript、Python、Ruby 等。
artifacts:reports:codequality
codequality
报告收集代码质量问题作为产物。
收集的代码质量报告作为产物上传到极狐GitLab,并在合并请求中汇总。
artifacts:reports:container_scanning
(ULTIMATE)
container_scanning
报告收集容器扫描漏洞作为产物。
收集的容器扫描报告作为产物上传到极狐GitLab,并在合并请求和流水线视图中汇总。它还用于为安全仪表盘提供数据。
artifacts:reports:coverage_fuzzing
(ULTIMATE)
coverage_fuzzing
报告收集 coverage fuzzing bug。 收集到的覆盖模糊报告作为产物上传到极狐GitLab。
artifacts:reports:dast
(ULTIMATE)
dast
报告收集 DAST 漏洞。收集的 DAST 报告作为产物上传到极狐GitLab。
artifacts:reports:dependency_scanning
(ULTIMATE)
dependency_scanning` 报告收集依赖扫描漏洞。 收集到的依赖扫描报告作为产物上传到极狐GitLab。
artifacts:reports:dotenv
收集的变量被注册为作业的运行时创建的变量,这对于作业完成后设置动态环境 URL 很有用。
原始 dotenv 规则 有几个例外:
- 变量键只能包含字母、数字和下划线 (
_
)。 -
.env
文件的最大大小为 5 KB。 - 在 13.5 及更早版本中,最大继承变量数为 10。
- 在 13.6 及更高版本中,最大继承变量数为 20。
- 不支持
.env
文件中的变量替换。 -
.env
文件不能有空行或注释(以#
开头)。 -
env
文件中的键值不能有空格或换行符 (\n
),包括使用单引号或双引号时。 - 不支持在解析过程中引用转义 (
key = 'value'
->{key: "value"}
)。
artifacts:reports:junit
junit
报告收集JUnit 报告格式 XML 文件。 收集到的单元测试报告作为产物上传到极狐GitLab。尽管 JUnit 最初是用 Java 开发的,但也有许多其他语言(如 JavaScript、Python 和 Ruby)的第三方端口。
下面是从 Ruby 的 RSpec 测试工具收集 JUnit 报告格式 XML 文件的示例:
rspec:
stage: test
script:
- bundle install
- rspec --format RspecJunitFormatter --out rspec.xml
artifacts:
reports:
junit: rspec.xml
一些 JUnit 工具导出到多个 XML 文件。您可以在单个作业中指定多个测试报告路径以将它们连接到一个文件中。使用:
- 文件名模式(
junit: rspec-*.xml
)。 - 文件名数组(
junit: [rspec-1.xml, rspec-2.xml, rspec-3.xml]
)。 - 两者的组合(
junit: [rspec.xml, test-results/TEST-*.xml]
)。
artifacts:reports:license_scanning
(ULTIMATE)
许可证合规报告收集许可证。许可证合规报告作为产物上传到极狐GitLab。
artifacts:reports:load_performance
(PREMIUM)
load_performance
报告收集负载性能测试指标作为产物。
该报告作为产物上传到极狐GitLab。
artifacts:reports:metrics
(PREMIUM)
metrics
报告收集 Metrics 作为产物。
收集的指标报告作为产物上传到极狐GitLab。
artifacts:reports:requirements
(ULTIMATE)
requirements
报告收集 requirements.json
文件作为产物。
收集到的需求报告作为产物上传到极狐GitLab,现有的需求被标记为 Satisfied。
artifacts:reports:sast
sast
报告收集 SAST 漏洞作为产物。
收集的 SAST 报告作为产物上传到极狐GitLab,并在合并请求和流水线视图中汇总。它还用于为安全仪表盘提供数据。
artifacts:reports:secret_detection
secret-detection
报告收集检测到的 secret 作为产物。
收集到的 secret 检测报告作为产物上传到极狐GitLab,并在合并请求和流水线视图中汇总。它还用于为安全仪表盘提供数据。
artifacts:reports:terraform
- 引入于 13.0 版本。
- 需要极狐GitLab Runner 11.5 及更高版本。
terraform
报告获取 Terraform tfplan.json
文件。删除凭据所需的 JQ 流程。收集的 Terraform 计划报告作为产物上传到极狐GitLab。
artifacts:untracked
使用 artifacts:untracked
将所有 Git 未跟踪文件添加为产物(以及在 artifacts:paths
中定义的路径)。artifacts:untracked
忽略仓库的 .gitignore
文件中的配置。
发送所有 Git 未跟踪文件:
artifacts:
untracked: true
发送所有 Git 未跟踪文件和 binaries
中的文件:
artifacts:
untracked: true
paths:
- binaries/
发送所有未跟踪的文件,但排除 *.txt
:
artifacts:
untracked: true
exclude:
- "*.txt"
artifacts:when
使用 artifacts:when
在作业失败时上传产物。
artifacts:when
可以设置为以下值之一:
-
on_success
(默认):仅在作业成功时上传产物。 -
on_failure
:仅在作业失败时上传产物。 -
always
:始终上传产物。例如,当需要对失败的测试进行故障排除时,很有用。
例如,仅在作业失败时上传产物:
job:
artifacts:
when: on_failure
coverage
使用带有自定义正则表达式的 coverage
来配置如何从作业输出中提取代码覆盖率。如果作业输出中至少有一行与正则表达式匹配,则覆盖率会显示在 UI 中。
为了提取匹配行中的代码覆盖率值,极狐GitLab 使用以下正则表达式:\d+(\.\d+)?
。
可能的输入:正则表达式。必须以/
开头和结尾。
coverage
示例:
job1:
script: rspec
coverage: '/Code coverage: \d+\.\d+/'
在这个例子中:
- 系统检查作业日志中是否有与正则表达式匹配的行。像
Code coverage: 67.89
这样的行会匹配。 - 然后检查该行以找到与
\d+(\.\d+)?
的匹配项。上面的示例匹配行给出了67.89
的代码覆盖率。
额外细节:
- 如果作业输出中有多个匹配的行,则使用最后一行。
- 如果单行中有多个匹配项,则搜索使用最后一个匹配项。
- 如果在匹配的片段中找到多个覆盖率数字,则使用第一个。
- 删除前导零。
- 子流水线 的覆盖输出未记录或显示。
dast_configuration (ULTIMATE)
引入于 14.1 版本。
使用 dast_configuration
关键字指定要在 CI/CD 配置中使用的站点配置文件和扫描程序配置文件。必须首先在项目中创建这两个配置文件。作业的阶段必须是 dast
。
关键字类型:作业关键字。只能作为作业的一部分使用。
可能的输入:site_profile
和 scanner_profile
各一个。
- 使用
site_profile
指定要在作业中使用的站点配置文件。 - 使用
scanner_profile
指定要在作业中使用的扫描仪配置文件。
dast_configuration
示例:
stages:
- build
- dast
include:
- template: DAST.gitlab-ci.yml
dast:
dast_configuration:
site_profile: "Example Co"
scanner_profile: "Quick Passive Test"
在此示例中,dast
作业扩展了添加了 include:
关键字的 dast
配置,以选择特定的站点配置文件和扫描仪配置文件。
额外细节:
- 站点配置文件或扫描仪配置文件中包含的设置优先于 DAST 模板中包含的设置。
retry
使用 retry
配置作业失败时重试的次数。如果未定义,则默认为 0
并且作业不会重试。
当作业失败时,该作业最多再处理两次,直到成功或达到最大重试次数。
默认情况下,所有失败类型都会导致重试作业。使用 retry:when 选择要重试的失败。
关键字类型:作业关键字。您只能将其用作作业的一部分或在 default: 部分 中使用。
可能的输入:0
(默认)、1
或2
。
retry
示例:
test:
script: rspec
retry: 2
retry:when
使用 retry:when
和 retry:max
仅针对特定的失败情况重试作业。retry:max
是最大重试次数,如 retry,可以是 0
、1
或 2
。
关键字类型:作业关键字。您只能将其用作作业的一部分或在 default: 部分 中使用。
可能的输入:单一故障类型,或一个或多个故障类型的数组:
-
always
:任何失败重试(默认)。 -
unknown_failure
:当失败原因未知时重试。 -
script_failure
:脚本失败时重试。 -
api_failure
:在 API 失败时重试。 -
stuck_or_timeout_failure
:当作业卡住或超时时重试。 -
runner_system_failure
:如果 runner 系统出现故障(例如,作业设置失败),请重试。 -
runner_unsupported
:如果 runner 不受支持,请重试。 -
stale_schedule
:如果无法执行延迟的作业,请重试。 -
job_execution_timeout
:如果脚本超过为作业设置的最大执行时间,请重试。 -
archived_failure
:如果作业已存档且无法运行,请重试。 -
unmet_prerequisites
:如果作业未能完成先决任务,请重试。 -
scheduler_failure
:如果 scheduler 未能将作业分配给 runner,请重试。 -
data_integrity_failure
:如果检测到结构完整性问题,请重试。
retry:when
示例(单一故障型):
test:
script: rspec
retry:
max: 2
when: runner_system_failure
果存在除 runner 系统故障以外的故障,则不会重试作业。
retry:when
示例 (故障类型数组):
test:
script: rspec
retry:
max: 2
when:
- runner_system_failure
- stuck_or_timeout_failure
timeout
使用 timeout
为特定作业配置超时。如果作业运行的时间超过超时时间,作业将失败。
作业级超时可以长于项目级超时。但不能超过 runner 的超时。
关键字类型:作业关键字。您只能将其用作作业的一部分或在 default: 部分中使用。
可能的输入:用自然语言编写的一段时间。例如,以下都是等价的:
3600 seconds
60 minutes
one hour
timeout
示例:
build:
script: build.sh
timeout: 3 hours 30 minutes
test:
script: rspec
timeout: 3h 30m
parallel
使用 parallel
配置并行运行的作业实例数。 该值可以是 2 到 50。
parallel
关键字创建并行运行的同一作业的 N 个实例。 它们从 job_name 1/N
到 job_name N/N
按顺序命名:
关键字类型:作业关键字。您只能将其用作作业的一部分。
可能的输入:从 2
到 50
的数值。
parallel
示例:
test:
script: rspec
parallel: 5
此示例创建了 5 个并行运行的作业,名为 test 1/5
到 test 5/5
。
额外细节:
- 每个并行作业都有一个
CI_NODE_INDEX
和CI_NODE_TOTAL
预定义 CI/CD 变量集。
parallel:matrix
使用 parallel:matrix
在单个流水线中并行运行作业多次,但对于作业的每个实例使用不同的变量值。
必须存在多个 runner,或者必须将单个 runner 配置为同时运行多个作业。
关键字类型:作业关键字。您只能将其用作作业的一部分。
可能的输入:变量哈希数组:
- 变量名只能使用数字、字母和下划线 (
_
)。 - 值必须是字符串或字符串数组。
- 排列数不能超过 50。
parallel:matrix
示例:
deploystacks:
stage: deploy
script:
- bin/deploy
parallel:
matrix:
- PROVIDER: aws
STACK:
- monitoring
- app1
- app2
- PROVIDER: ovh
STACK: [monitoring, backup, app]
- PROVIDER: [gcp, vultr]
STACK: [data, processing]
该示例生成 10 个并行的 deploystacks
作业,每个作业具有不同的 PROVIDER
和 STACK
值:
deploystacks: [aws, monitoring]
deploystacks: [aws, app1]
deploystacks: [aws, app2]
deploystacks: [ovh, monitoring]
deploystacks: [ovh, backup]
deploystacks: [ovh, app]
deploystacks: [gcp, data]
deploystacks: [gcp, processing]
deploystacks: [vultr, data]
deploystacks: [vultr, processing]
trigger
使用 trigger
启动下游流水线:
- 多项目流水线。
- 子流水线。
关键字类型:作业关键字。您只能将其用作作业的一部分。
可能的输入:
- 对于多项目流水线,指向下游项目的路径。
- 对于子流水线,子流水线 CI/CD 配置文件的路径。
多项目流水线的 trigger
示例:
rspec:
stage: test
script: bundle exec rspec
staging:
stage: deploy
trigger: my/deployment
子流水线的 trigger
示例:
trigger_job:
trigger:
include: path/to/child-pipeline.yml
额外细节:
- 带有
trigger
的作业只能使用有限的关键字集。例如,您不能使用 script、before_script 或 after_script 运行命令。 - 您不能使用 API 来启动
when:manual
触发器作业。 - 在 13.5 及更高版本中,您可以在与
trigger
相同的作业中使用 when:manual。 在 13.4 及更早版本中,将它们一起使用会导致错误jobs:#{job-name} when should be on_success, on_failure or always
。 - 在 13.2 及更高版本中,您可以在流水线图中查看哪个作业触发了下游流水线。
- 手动流水线变量和计划流水线变量默认情况下不传递给下游流水线。使用 trigger:forward 将这些变量转发到下游流水线。
trigger:strategy
使用 trigger:strategy
强制 trigger
作业在标记为 success 之前等待下游流水线完成。
此行为与默认行为不同,默认行为是在创建下游流水线后立即将 trigger
作业标记为 success。
此设置使您的流水线执行线性而不是并行。
trigger:strategy
示例:
trigger_job:
trigger:
include: path/to/child-pipeline.yml
strategy: depend
在此示例中,后续阶段的作业在开始之前等待触发的流水线成功完成。
interruptible
如果在作业完成之前新流水线启动时应取消作业,请使用 interruptible
。
如果禁用自动取消冗余流水线,则此关键字无效。启用后,在为同一分支上的新更改启动流水线时,会取消正在运行的具有 interruptible: true
的作业。
在带有 interruptible: false
的作业开始后,您无法取消后续作业。
关键字类型:作业关键字。您只能将其用作作业的一部分或在 default: 部分 中使用。
可能的输入:true
或 false
(默认)。
interruptible
示例:
stages:
- stage1
- stage2
- stage3
step-1:
stage: stage1
script:
- echo "Can be canceled."
interruptible: true
step-2:
stage: stage2
script:
- echo "Can not be canceled."
step-3:
stage: stage3
script:
- echo "Because step-2 can not be canceled, this step can never be canceled, even though it's set as interruptible."
interruptible: true
在这个例子中,一个新的流水线导致一个正在运行的流水线:
- 取消,如果只有
step-1
正在运行或挂起。 - 未取消,在
step-2
开始后。
额外细节:
- 如果作业在开始后可以安全取消,则仅设置
interruptible: true
,例如构建作业。通常不应取消部署作业,以防止部分部署。 - 要完全取消正在运行的流水线,所有作业必须具有
interruptible: true
,或interruptible: false
作业必须尚未启动。
resource_group
使用 resource_group
创建一个资源组,以确保同一项目的不同流水线之间的作业是互斥的。
例如,如果属于同一资源组的多个作业同时排队,则只有其中一个作业启动。其他作业一直等到 resource_group
空闲。
资源组的行为类似于其他编程语言中的信号量。
您可以为每个环境定义多个资源组。例如,在部署到物理设备时,您可能有多个物理设备。 每个设备都可以部署到,但在任何给定时间每个设备只能进行一次部署。
关键字类型:作业关键字。您只能将其用作作业的一部分。
可能的输入:只有字母、数字、-
、_
、/
、$
、{
、}
、.
和空格。不能以/
开头或结尾。
resource_group
示例:
deploy-to-production:
script: deploy
resource_group: production
在这个例子中,两个独立流水线中的两个 deploy-to-production
作业永远不能同时运行。因此,您可以确保并发部署永远不会发生在生产环境中。
release
使用 release
创建一个发布。
发布作业必须有权访问 release-cli
,其必须在 $PATH
中。
关键字类型:作业关键字。您只能将其用作作业的一部分。
可能的输入:release:
子键:
- tag_name
- description
- name(可选)
- ref(可选)
- milestones(可选)
- released_at(可选)
- assets:links(可选)
release
关键字示例:
release_job:
stage: release
image: registry.gitlab.com/gitlab-org/release-cli:latest
rules:
- if: $CI_COMMIT_TAG # Run this job when a tag is created manually
script:
- echo "Running the release job."
release:
tag_name: $CI_COMMIT_TAG
name: 'Release $CI_COMMIT_TAG'
description: 'Release created using the release-cli.'
此示例创建一个版本:
- 当你推送一个 Git 标签时。
- 当您在 仓库 > 标签 的 UI 中添加 Git 标签时。
额外细节:
-
除 trigger 作业外,所有发布作业都必须包含
script
关键字。发布作业可以使用脚本命令的输出。如果不需要脚本,可以使用占位符:script: - echo 'release job'
-
release
部分在script
关键字之后和after_script
之前执行。 -
仅当作业的主脚本成功时才会创建发布。
-
如果发布已经存在,则不会更新并且带有
release
关键字的作业失败。 -
如果你使用 Shell executor 或在注册 runner 的服务器上安装
release-cli
。
release:tag_name
必需的。发布的 Git 标签。
如果项目中尚不存在该标签,则在发布的同时创建该标签。 新标签使用与流水线关联的 SHA。
关键字类型:作业关键字。您只能将其用作作业的一部分。
可能的输入:标签名称。可以使用 CI/CD 流水线。
release:tag_name
示例:
在项目中添加新标签时创建发布:
- 使用
$CI_COMMIT_TAG
CI/CD 变量作为tag_name
。 - 使用 rules:if 或 only: tags 将作业配置为仅针对新标签运行。
job:
script: echo 'Running the release job for the new tag.'
release:
tag_name: $CI_COMMIT_TAG
description: 'Release description'
rules:
- if: $CI_COMMIT_TAG
要同时创建发布和新标签,您的 rules 或 only 应该不应将作业配置为仅针对新标签运行。语义版本控制示例:
job:
script: echo 'Running the release job and creating a new tag.'
release:
tag_name: ${MAJOR}_${MINOR}_${REVISION}
description: 'Release description'
rules:
- if: $CI_PIPELINE_SOURCE == "schedule"
release:name
版本名称。如果省略,则使用 release: tag_name
的值填充。
关键字类型:作业关键字。您只能将其用作作业的一部分。
可能的输入:一个文本字符串。
release:name
示例:
release_job:
stage: release
release:
name: 'Release $CI_COMMIT_TAG'
release:description
发布的详细说明。
关键字类型:作业关键字。您只能将其用作作业的一部分。
可能的输入:
- 带有详细描述的字符串。
- 包含描述的文件的路径。在 13.7 中引入。
- 文件位置必须相对于项目目录 (
$CI_PROJECT_DIR
)。 - 如果文件是一个符号链接,它必须在
$CI_PROJECT_DIR
中。 -
./path/to/file
和文件名不能包含空格。
- 文件位置必须相对于项目目录 (
release:description
示例:
job:
release:
tag_name: ${MAJOR}_${MINOR}_${REVISION}
description: './path/to/CHANGELOG.md'
release:ref
如果 release: tag_name
还不存在,作为发布的 ref
。
关键字类型:作业关键字。您只能将其用作作业的一部分。
可能的输入:
- 提交 SHA、另一个标签名称或分支名称。
release:milestones
与发布相关的每个里程碑的标题。
release:released_at
发布准备就绪的日期和时间。
可能的输入:
- 用引号括起来并以 ISO 8601 格式表示的日期。
release:released_at
示例:
released_at: '2021-03-15T08:00:00Z'
额外细节:
- 如果未定义,则使用当前日期和时间。
release:assets:links
引入于 13.12 版本。
使用 release:assets:links
在发布中包含 assets 链接。
需要 release-cli
版本 v0.4.0 或更高版本。
release:assets:links
示例:
assets:
links:
- name: 'asset1'
url: 'https://example.com/assets/1'
- name: 'asset2'
url: 'https://example.com/assets/2'
filepath: '/pretty/url/1' # optional
link_type: 'other' # optional
secrets (PREMIUM)
引入于 13.4 版本。
使用 secrets
将 CI/CD secret 指定为:
- 从外部 secret 提供商处检索。
- 在作业中作为 CI/CD 变量(file 类型 默认情况下提供)。
此关键字必须与 secrets:vault
一起使用。
secrets:vault
- 引入于 13.4 版本和 GitLab Runner 13.4。
使用 secrets:vault
指定由 HashiCorp Vault 提供的 secret。
关键字类型:作业关键字。您只能将其用作作业的一部分。
可能的输入:
-
engine:name
:secret engine 的名称。 -
engine:path
:secret engine 的路径。 -
path
:secret 的路径。 -
field
:存储密码的字段的名称。
secrets:vault
示例:
要明确指定所有详细信息并使用 KV-V2 secret engine:
job:
secrets:
DATABASE_PASSWORD: # Store the path to the secret in this CI/CD variable
vault: # Translates to secret: `ops/data/production/db`, field: `password`
engine:
name: kv-v2
path: ops
path: production/db
field: password
您可以缩短此语法。 使用简短的语法,engine:name
和 engine:path
都默认为 kv-v2
:
job:
secrets:
DATABASE_PASSWORD: # Store the path to the secret in this CI/CD variable
vault: production/db/password # Translates to secret: `kv-v2/data/production/db`, field: `password`
要以简短的语法指定自定义 secret engine 路径,请添加以 @
开头的后缀:
job:
secrets:
DATABASE_PASSWORD: # Store the path to the secret in this CI/CD variable
vault: production/db/password@ops # Translates to secret: `ops/data/production/db`, field: `password`
secrets:file
引入于 14.1 版本和 GitLab Runner 14.1.
使用 secrets:file
配置 secret 存储为 file
或 variable
类型 CI/CD 变量。
默认情况下,secret 作为 file
类型的 CI/CD 变量传递给作业。Secret 的值存储在文件中,变量包含文件的路径。
如果您的软件不能使用 file
类型的 CI/CD 变量,设置 file: false
将 secret 值直接存储在变量中。
关键字类型:作业关键字。您只能将其用作作业的一部分。
可能的输入:true
(默认)或 false
。
secrets:file
示例:
job:
secrets:
DATABASE_PASSWORD:
vault: production/db/password@ops
file: false
额外细节:
-
file
关键字是 CI/CD 变量的设置,必须嵌套在 CI/CD 变量名称下,而不是在vault
部分。
pages
使用 pages
定义一个 GitLab Pages 作业,将静态内容上传到极狐GitLab,然后将内容发布为网站。
关键字类型:作业名称。
pages
示例:
pages:
stage: deploy
script:
- mkdir .public
- cp -r * .public
- mv .public public
artifacts:
paths:
- public
rules:
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
此示例将所有文件从项目的根目录移动到 public/
目录。 .public
的解决方法是,cp
不会在无限循环中将 public/
复制到自身。
额外细节:
你必须:
- 将任何静态内容放在
public/
目录中。 - 定义 artifacts 和
public/
目录的路径。
inherit
使用inherit:
来控制默认关键字和变量的继承。
inherit:default
使用inherit:default
来控制默认关键字的继承。
关键字类型:作业关键字。您只能将其用作作业的一部分。
可能的输入:
-
true
(默认)或false
启用或禁用所有默认关键字的继承。 - 要继承的特定默认关键字列表。
inherit:default
示例:
default:
retry: 2
image: ruby:3.0
interruptible: true
job1:
script: echo "This job does not inherit any default keywords."
inherit:
default: false
job2:
script: echo "This job inherits only the two listed default keywords. It does not inherit 'interruptible'."
inherit:
default:
- retry
- image
额外细节:
- 您还可以在一行中列出要继承的默认关键字:
default: [keyword1, keyword2]
。
inherit:variables
使用inherit:variables
来控制全局变量关键字的继承。
关键字类型:作业关键字。您只能将其用作作业的一部分。
可能的输入:
-
true
(默认)或false
来启用或禁用所有全局变量的继承。 - 要继承的特定变量的列表。
inherit:variables
示例:
variables:
VARIABLE1: "This is variable 1"
VARIABLE2: "This is variable 2"
VARIABLE3: "This is variable 3"
job1:
script: echo "This job does not inherit any global variables."
inherit:
variables: false
job2:
script: echo "This job inherits only the two listed global variables. It does not inherit 'VARIABLE3'."
inherit:
variables:
- VARIABLE1
- VARIABLE2
额外细节:
- 您还可以在一行中列出要继承的全局变量:
variables: [VARIABLE1, VARIABLE2]
trigger:forward
- 引入于 14.9 版本,功能标志名为
ci_trigger_forward_variables
。默认禁用。- 在 SaaS 版和私有化部署版上启用于 14.10 版本。
- 一般可用于 15.1 版本。功能标志
ci_trigger_forward_variables
删除。
使用 trigger:forward
指定要转发到下游流水线的内容。您可以控制转发到父子流水线和多项目流水线的内容。
可能的输入:
-
yaml_variables
:true
(默认),或false
。当为true
时,触发器作业中定义的变量被传递到下游流水线。 -
pipeline_variables
:true
或false
(默认)。当为true
时,手动流水线变量和计划流水线变量被传递到下游流水线。
trigger:forward
示例:
手动运行此流水线,使用 CI/CD 变量 MYVAR = my value
:
variables: # default variables for each job
VAR: value
# Default behavior:
# - VAR is passed to the child
# - MYVAR is not passed to the child
child1:
trigger:
include: .child-pipeline.yml
# Forward pipeline variables:
# - VAR is passed to the child
# - MYVAR is passed to the child
child2:
trigger:
include: .child-pipeline.yml
forward:
pipeline_variables: true
# Do not forward YAML variables:
# - VAR is not passed to the child
# - MYVAR is not passed to the child
child3:
trigger:
include: .child-pipeline.yml
forward:
yaml_variables: false
variables
CI/CD 变量是传递给作业的可配置值。
使用 variables
创建自定义变量。
变量在 script
、before_script
和 after_script
命令中始终可用。 您还可以在某些作业关键字中使用变量作为输入。
关键字类型:全局和工作关键字。您可以在全局级别使用它,也可以在作业级别使用它。
如果您在全局级别定义 variables
,则在创建流水线时每个变量都会被复制到每个作业配置中。如果作业已经定义了该变量,则作业级变量优先。
可能的输入:变量名和值对:
- 名称只能使用数字、字母和下划线 (
_
)。 - 值必须是字符串。
variables
示例:
variables:
DEPLOY_SITE: "https://example.com/"
deploy_job:
stage: deploy
script:
- deploy-script --url $DEPLOY_SITE --path "/"
deploy_review_job:
stage: deploy
variables:
REVIEW_PATH: "/review"
script:
- deploy-review-script --url $DEPLOY_SITE --path $REVIEW_PATH
额外细节:
- 所有 YAML 定义的变量也设置为任何链接的 Docker 服务容器。
- YAML 定义的变量用于非敏感项目配置。将敏感信息存储在受保护变量或 CI/CD secrets 中。
- 手动流水线变量和计划流水线变量默认情况下不传递给下游流水线。使用 trigger:forward 将这些变量转发到下游流水线。
variables:description
引入于 13.7 版本。
当手动运行流水线时,使用 description
关键字定义预填的流水线级别(全局)变量。
必须与 value
一起使用,用于变量值。
关键字类型:全局关键字。 当您手动运行流水线时,您无法将作业级变量设置为预填充。
可能的输入:一个字符串。
variables:description
示例:
variables:
DEPLOY_ENVIRONMENT:
value: "staging"
description: "The deployment target. Change this variable to 'canary' or 'production' if needed."
废弃的关键字
以下关键字已弃用。
全局定义的 types(已删除)
WARNING: types
已弃用,删除于 15.0 版本。 使用 stages 代替。
作业定义的 type(已删除)
WARNING: type
已弃用,删除于 15.0 版本。 使用 stage 代替。
全局定义的 image, services, cache, before_script, after_script
不推荐在全局范围内定义 image
、services
、cache
、before_script
和 after_script
。可能会从未来的版本中删除支持。文章来源:https://www.toymoban.com/news/detail-492195.html
使用 default: 代替。 例如:文章来源地址https://www.toymoban.com/news/detail-492195.html
default:
image: ruby:3.0
services:
- docker:dind
cache:
paths: [vendor/]
before_script:
- bundle config set path vendor/bundle
- bundle install
after_script:
- rm -rf tmp/
到了这里,关于gitlab-ci.yml 关键字参考 (FREE)的文章就介绍完了。如果您还想了解更多内容,请在右上角搜索TOY模板网以前的文章或继续浏览下面的相关文章,希望大家以后多多支持TOY模板网!