.codechina-ci.yml文件的关键字参考
本文档包含.codechina-ci.yml文件中的配置选项。
当你在编辑.codechina-ci.yml的过程中，你可以通过 CI Lint 工具进行验证。
流水线任务关键字
流水线任务是由一系列定义了流水线任务行为的关键词组成的。
可用于流水线任务的关键字包括：
| 关键字 | 描述 |
|---|---|
after_script |
覆盖在流水线任务后执行的一组命令 |
allow_failure |
允许流水线任务失败，失败的流水线任务不会导致流水线运行失败 |
artifacts |
成功时附加到流水线任务的文件和目录列表 |
before_script |
覆盖在流水线任务之前执行的一组命令 |
cache |
缓存的可用于后续运行的文件列表 |
coverage |
给定流水线任务的代码覆盖率设置 |
dependencies |
通过提供要从中获取artifacts的流水线任务列表来限制将哪些artifacts传递给特定任务 |
environment |
流水线任务部署到的环境的名称 |
except |
控制何时不创建流水线任务 |
extends |
配置当前流水线任务继承自的配置条目 |
image |
使用 Docker 镜像 |
include |
引用外部的 yaml 文件 |
inherit |
选择所有流水线任务继承的全局默认值 |
interruptible |
定义当新的运行变得多余时是否可以取消该流水线任务 |
needs |
在 stage 排序之前执行流水线任务 |
only |
控制何时创建流水线任务 |
pages |
上传流水线任务的结果与 CODE CHINA Pages 一起使用 |
parallel |
并行运行的流水线任务实例数量 |
release |
指导 runner 生成一次发布 |
resource_group |
限制流水线任务的并发 |
retry |
在失败的情况下可以自动重试流水线任务的次数 |
rules |
用于评估和确定流水线任务的选定属性以及它是否已创建的条件列表 |
script |
需要由 Runner 执行的 Shell 脚本 |
secrets |
CI/CD 隐藏流水线任务的 needs
|
services |
使用 Docker 服务镜像 |
stage |
定义流水线任务的阶段 |
tags |
用于选择 runner 的标签列表 |
timeout |
定义优先于项目范围设置的自定义流水线任务超时时间（任务级别） |
trigger |
定义下游流水线的触发器 |
variables |
定义流水线任务级别的变量 |
when |
何时运行流水线任务 |
不可用的流水线任务名称
以下关键词不可用作流水线任务的名称：
imageservicesstagestypesbefore_scriptafter_scriptvariablescacheinclude
自定义默认关键字值
你可以为某些关键字设置全局默认值。未定义一个或多个所列关键字的流水线任务使用default:中定义的值。
以下这些流水线任务关键字可以在default:部分中定义：
以下示例将ruby:3.0镜像设置为流水线中所有流水线任务的默认值，而rspec 2.7流水线任务则不使用默认值，因为它使用特定于流水线任务的image:部分覆盖了默认值：
default:
image: ruby:3.0
rspec:
script: bundle exec rspec
rspec 2.7:
image: ruby:2.7
script: bundle exec rspec全局关键字
某些关键字在流水线任务中未定义，这些关键字控制流水线的行为或者导入额外的流水线配置：
| 关键字 | 描述 |
|---|---|
stages |
流水线阶段的名称和顺序 |
workflow |
控制运行的流水线类型 |
include |
从其他 YAML 文件导入配置 |
stages
使用 stages 来定义该阶段中包含的流水线任务组。stages 是为流水线全局定义的。在流水线任务中使用 stage 以定义流水线任务属于哪个阶段。
stages 的顺序定义了流水线任务的执行顺序：
- 同一阶段的流水线任务并行运行
- 下一阶段的流水线任务在上一阶段的流水线任务成功完成后运行
例如：
stages:
- build
- test
- deploy-
build中所有的流水线任务并行执行。 - 如果
build中的所有流水线任务都成功，则test中的流水线任务并行执行。 - 如果
test中的所有流水线任务都成功，则deploy中的流水线任务并行执行。 - 如果
deploy中的所有流水线任务都成功，则流水线标记为通过。
如果任何流水线任务失败，流水线将被标记为 failed 并且后续阶段的流水线任务不会启动。当前阶段的流水线任务不会停止并继续运行。
如果 .codechina-ci.yml 文件中没有定义 stages，则 build,test和 deploy 是默认的流水线阶段。
如果流水线任务未指定 stage，则将该流水线任务分配至test阶段。
如果定义了一个 stage ，但没有流水线任务使用它，则该阶段在流水线中不可见。这对于合规性流水线配置很有用，因为：
- stage 可以在合规性配置中定义，但如果不使用则保持隐藏。
- 当开发人员在流水线任务定义中使用它们时，定义的 stage 变得可见。
要使流水线任务更早开始并忽略 stage 顺序，请使用needs关键字。
workflow
使用workflow:以确定流水线是否被创建。在顶层定义此关键字，使用rules:类似于rules:在流水线任务中定义的单个关键字。
你可以使用workflow:rules模板导入预配置的workflow: rules条目。
workflow: rules 接受以下这些关键字：
-
if：检查此rules以确定何时运行流水线。 -
when：指定当 ifrules评估为真时要做什么。- 要运行流水线，请设置为 always。
- 要防止流水线运行，请设置为 never。
-
variables: 如果未定义，则使用别处定义的变量。
当没有 rules 评估为真时，流水线不会运行。
workflow: rules的一些示例if条款：
示例 rules
|
描述 |
|---|---|
if: '$CI_PIPELINE_SOURCE == "merge_request_event"' |
控制合并请求流水线何时运行 |
if: '$CI_PIPELINE_SOURCE == "push"' |
控制分支流水线和 Tag 流水线何时运行 |
if: $CI_COMMIT_TAG |
控制 Tag 流水线何时运行 |
if: $CI_COMMIT_BRANCH |
控制分支流水线何时运行 |
有关更多示例，请参阅通用 if rules 条款。
在以下示例中，流水线针对所有 push 事件（对分支和新标签的更改）运行。提交消息中含-draft的推送事件不会运行流水线，因为它们被设置为when: never。计划或合并请求的流水线也不会运行，因为没有 rules 对它们评估为真：
workflow:
rules:
- if: $CI_COMMIT_MESSAGE =~ /-draft$/
when: never
- if: '$CI_PIPELINE_SOURCE == "push"'这个例子有严格的 rules ，流水线不会在其他任何情况下运行。
或者，所有 rules 都可以when: never，并带有最终 when: always rules 。符合when: never rules 的流水线不会运行，所有其他流水线类型运行：
workflow:
rules:
- if: '$CI_PIPELINE_SOURCE == "schedule"'
when: never
- if: '$CI_PIPELINE_SOURCE == "push"'
when: never
- when: always以上示例中，阻止了计划或push（分支和标签）流水线的流水线运行。最终when: always rules 运行所有其他流水线类型，包括合并请求流水线。
如果你的 rules 同时匹配分支流水线和合并请求流水线，则可能会出现重复的流水线。
workflow:rules:variables
你可以在 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"当分支是默认分支时：
-
job1DEPLOY_VARIABLE是job1-deploy-production -
job2DEPLOY_VARIABLE是deploy-production
当分支是feature时：
job1DEPLOY_VARIABLE是job1-default-deploy，IS_A_FEATURE 是true
job2DEPLOY_VARIABLE是default-deploy，IS_A_FEATURE 是true
当分支是其它分支时：
job1DEPLOY_VARIABLE是job1-default-deploy
job2DEPLOY_VARIABLE是default-deploy
workflow:rules 模板
我们为一些常见场景提供了 workflow: rules 设置的模板。这些模板有助于防止重复运行流水线。
Branch-Pipelines 模板可以使你的流水线为分支和 Tags 运行。
分支流水线状态显示在使用分支作为源的合并请求中。但是，这种流水线类型不支持合并请求流水线提供的任何功能 ，例如合并结果流水线或合并列车。此模板有意避免使用这些功能。
可以通过以下方式引用它：
include:
- template: 'Workflows/Branch-Pipelines`.codechina-ci.yml`'MergeRequest-Pipelines 模板可以使你的流水线针对默认分支、Tags 和所有类型的合并请求运行流水线。如果使用任何合并请求功能的流水线，请使用此模板。
可以通过以下方式引用它：
include:
- template: 'Workflows/MergeRequest-Pipelines`.codechina-ci.yml`'在分支流水线和合并请求流水线之间切换
要在创建合并请求后将流水线从分支流水线切换到合并请求流水线，在 .codechina-ci.yml 文件中添加 workflow: rules 部分。
如果同时使用两种流水线类型，则可能会同时运行重复的流水线。为防止重复运行流水线，请使用CI_OPEN_MERGE_REQUESTS变量。
以下示例适用于仅运行分支和合并请求流水线，但不为任何其他情况运行流水线的项目：
- 当分支没有打开合并请求时运行分支流水线
- 当分支的合并请求打开时运行合并请求流水线
workflow:
rules:
- if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
- if: '$CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS'
when: never
- if: '$CI_COMMIT_BRANCH'如果流水线由以下因素触发：
- 合并请求，运行合并请求流水线。例如，合并请求流水线可以通过推送到具有关联打开合并请求的分支来触发。
- 对分支的更改，但该分支的合并请求已打开，请不要运行分支流水线。
- 对分支的更改，但没有任何打开的合并请求，运行分支流水线。
您还可以向现有workflow部分添加 rules ，以便在创建合并请求时从分支流水线切换到合并请求流水线。
将此 rules 添加到该workflow部分的顶部，然后是已经存在的其他 rules ：
workflow:
rules:
- if: $CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS && $CI_PIPELINE_SOURCE == "push"
when: never
- ... # Previously defined workflow rules here在分支上运行的流水线触发器有一个$CI_COMMIT_BRANCH 集合，可能会被类似的 rules 阻止。触发流水线的流水线源为trigger或pipeline，因此&& $CI_PIPELINE_SOURCE == "push"确保 rules 不会阻止触发流水线。
include
用于include在 CI/CD 配置中包含外部 YAML 文件。您可以将一个长的codechina-ci.yml文件分解为多个文件以提高可读性，或减少同一配置在多个位置的重复。
您还可以将模板文件存储在中央存储库中，并通过include将它们存储在项目中。
include要求外部 YAML 文件具有扩展名.yml或.yaml，否则不引用外部文件。
您不能在不同 YAML 文件之间通过使用 YAML 锚点的方式来 include .yaml。您只能引用同一文件中的锚点。要重用来自不同 YAML 文件的配置，请使用!reference 标签 或 extends 关键字。
include 支持以下引用方法：
| 关键词 | 方法 |
|---|---|
local |
引用本地项目存储库中的文件 |
file |
引用来自不同项目存储库的文件 |
remote |
引用来自远程 URL 的文件，必须可以公开访问。 |
template |
引用模板 |
流水线启动时，.codechina-ci.yml会评估所有方法引用的文件配置。配置是一个及时的快照并储存在数据库中。.codechina-ci.yml在下一个流水线启动之前，不会同步对引用文件配置的任何更改。
这些include文件是：
- 与
.codechina-ci.yml文件中的那些深度合并 =.codechina-ci.yml无论include关键字的位置如何，始终首先评估并与文件内容合并。
使用合并本地配置的 CI/CD 配置的方法来自定义和覆盖引用的配置。
.codechina-ci.yml文件中的本地配置会覆盖引用的配置。
include变量
您可以 在文件的部分中使用一些预定义的变量include .codechina-ci.yml：
include:
project: '$CI_PROJECT_PATH'
file: '.compliance-codechina-ci.yml'
include:local
使用include:local引用在同一个存储库中的.codechina-ci.yml文件。使用相对于根目录 (/) 的完整路径。
如果使用include:local，请确保.codechina-ci.yml文件和本地文件位于同一分支上。
您不能通过 Git 子模块路径包含本地文件。
所有嵌套的包含都在同一个项目的范围内执行，因此可以使用本地、项目、远程或模板引用。
例子：
include:
- local: '/templates/.codechina-ci-template.yml'您还可以使用较短的语法来定义路径：
include: '.codechina-ci-production.yml'使用本地引用而不是符号链接。
include:local带通配符文件路径
您可以在include:local中使用通配符路径（*和**）。
例子：
include: 'configs/*.yml'当流水线运行时：
- 将
.yml目录中的所有文件添加configs到流水线配置中。 - 不在
.yml目录的子文件夹中添加文件configs。为此，请添加以下配置：# 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'
include:file
要引用来自另一个私有项目的文件，请使用include:file。你仅可以将include:file与include:project组合使用。使用相对于根目录 (/)的完整路径。
例如：
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
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'
include:remote
include:remote与完整 URL 一起使用，可以引用来自不同位置的文件。因为不支持远程 URL 中的身份验证，远程文件必须可通过 HTTP/HTTPS GET请求公开访问。例如：
include:
- remote: 'https://codechina.csdn.net/example-project/-/raw/main/.codechina-ci.yml'所有嵌套引用都以公共用户身份在没有上下文的情况下执行，因此您只能使用include公共项目或模板。
include:template
使用include:template 引用 .codechina-ci.yml模板。
例如：
# 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所有嵌套引用仅在用户许可的情况下执行，因此可以使用项目、远程或模板引用。
嵌套引用
使用嵌套引用来组成一组引用。最多可以有 100 个引用，但不能有重复的引用，解析所有文件的时间限制为 30 秒。
关键字详情
接下来，我们介绍如何通过关键字来配置 CI/CD 流水线。
image
使用image指定用于流水线任务的 Docker 镜像。
更多：
- 用法示例，请参见
.gitlab-ci.yml文件中的 定义image。 - 详细使用信息，参考 Docker 集成文档。
image:name
一个扩展 Docker 配置选项。
有关更多信息，请参阅 的可用设置image。
image:entrypoint
一个扩展 Docker 配置选项。
有关更多信息，请参阅 的可用设置image。
services
使用services指定 Docker 镜像，链接到指定的基本镜像。
更多：
- 用法示例，请参见
.gitlab-ci.yml文件中的定义services。 - 详细使用信息，参考Docker集成文档。
- 示例服务，请参阅GitLab CI/CD 服务。
services:name
一个扩展 Docker 配置选项。
services:alias
一个扩展 Docker 配置选项。
services:entrypoint
一个扩展 Docker 配置选项。
services:command
一个扩展 Docker 配置选项。
script
使用script为 Runner 指定要执行的 shell 脚本。
除触发器流水线任务外的所有流水线任务都需要一个script关键字。
例如：
job:
script: "bundle exec rspec"你可以使用 YAML 锚点的 script.
script关键字也可以包含一组命令：
job:
script:
- uname -a
- bundle exec rspec有时，script命令必须用单引号或双引号括起来。例如，包含冒号 ( :) 的命令必须用单引号 ( ')括起来。YAML 解析器需要将文本解释为字符串而不是“键：值”对。
例如，此脚本中使用了冒号：
job:
script:
- curl --request POST --header 'Content-Type: application/json' "https://gitlab/api/v4/projects"要被视为有效的 YAML，您必须将整个命令用单引号括起来。如果命令已使用单引号，则应将它们更改为双引号 ( ")：
job:
script:
- 'curl --request POST --header "Content-Type: application/json" "https://gitlab/api/v4/projects"'您可以使用CI Lint工具验证语法是否有效。
使用这些字符时也要小心：
-
{,},[,],,,&,*,#,?,|,-,<,>,=,!,%,@,`
如果任何脚本命令返回零以外的退出代码，则流水线任务失败并且不会执行进一步的命令。将退出代码存储在变量中以避免这种行为：
job:
script:
- false || exit_code=$?
- if [ $exit_code -ne 0 ]; then echo "Previous command failed"; fi;
before_script
使用before_script定义应在每次流水线任务之前运行的命令组，但需要在artifacts恢复后。
你在 before_script 其中指定的脚本与您在 main script 中指定的任何脚本连接在一起。组合后的脚本在单个 shell 中一起执行。
before_script如果在流水线任务中定义它，则可以覆盖全局定义：
default:
before_script:
- echo "Execute this script in all jobs that don't already have a before_script section."
job1:
script:
- echo "This script executes after the global before_script."
job:
before_script:
- echo "Execute this script instead of the global before_script."
script:
- echo "This script executes after the job's `before_script`"可以在before_script中使用 YAML 锚点。
after_script
使用after_script定义每个流水线任务后运行命令组，包括失败的流水线任务。
如果流水线任务超时或被取消，则after_script不会执行。
你指定的after_script脚本在新 shell 中执行，与任何 before_script或script脚本分开 。通过这样：
- 将当前工作目录设置回默认值。
- 无法访问
before_script或script中定义的脚本所做的更改，包括：-
script脚本中导出的命令别名和变量。 - 工作树之外的更改（取决于运行程序执行程序），例如由
before_script或script脚本安装的软件。
-
- 有一个单独的超时，它被硬编码为 5 分钟。
- 不影响流水线任务的退出代码。如果该
script部分成功并且after_script超时或失败，则流水线任务将退出并显示代码0(Job Succeeded)。
default:
after_script:
- echo "Execute this script in all jobs that don't already have an after_script section."
job1:
script:
- echo "This script executes first. When it completes, the global after_script executes."
job:
script:
- echo "This script executes first. When it completes, the job's `after_script` executes."
after_script:
- echo "Execute this script instead of the global after_script."可以在after_script中使用 YAML 锚点。
Script 语法
您可以在script中使用语法来：
- 将长命令拆分为多行命令。
- 使用颜色代码使流水线任务日志更易于查看。
- 创建自定义可折叠部分以简化流水线任务日志输出。
stage
使用stage定义在哪一个阶段运行流水线任务。流水线任务在同一 stage 可以并行执行（某些条件下）。
没有stage条目的流水线任务默认使用test阶段。如果没有在流水线中定义stages ，则可以使用 5 个默认阶段，它们按以下顺序执行：
例如：
stages:
- build
- test
- deploy
job 0:
stage: .pre
script: make something useful before build stage
job 1:
stage: build
script: make build dependencies
job 2:
stage: build
script: make build artifacts
job 3:
stage: test
script: make test
job 4:
stage: deploy
script: make deploy
job 5:
stage: .post
script: make something useful at the end of pipeline使用你自己的 Runner
当你使用自建的 Runner 时，默认情况下每个 Runner 一次仅运行一项流水线任务。如果流水线任务在不同的 Runner 上运行，它们可以并行运行。
如果您只有一个 Runner ，并且 Runner 的 concurrent 设置大于 1，则流水线任务可以并行运行。
.pre 和 .post
将pre和post用于需要在流水线中首先或最后运行的流水线任务。
-
.pre保证始终是流水线中的第一阶段。 -
.post保证始终是流水线中的最后阶段。
用户定义的阶段将在 .pre 之后和 .post 之前执行。
你必须在.pre或.post以外的至少一个阶段有一个流水线任务。
你不能更改 .pre 和 .post 的顺序，即使您在.codechina-ci.yml文件中不按顺序定义它们。例如，以下配置是等效的：
stages:
- .pre
- a
- b
- .poststages:
- a
- .pre
- b
- .poststages:
- a
- b
extends
使用 extends 重用配置部分。它是YAML 锚点的替代品， 并且更加灵活、有更强的可读性。你可以使用extends从引用的配置文件中重用配置。
在以下示例中，rspec 流水线任务使用 .tests 模板流水线任务中的配置。 系统会：
- 根据键执行反向深度合并。
- 将
.tests内容与rspec流水线任务合并。 - 不合并键的值。
.tests:
script: rake test
stage: test
only:
refs:
- branches
rspec:
extends: .tests
script: rake rspec
only:
variables:
- $RSPEC结果 rspec 的流水线任务是：
rspec:
script: rake rspec
stage: test
only:
refs:
- branches
variables:
- $RSPEC.tests 在这个例子中是一个隐藏流水线任务，但也可以从常规流水线任务扩展配置。
extends 支持多级继承。你应该避免使用三个以上的级别，但你仍可以使用多达 11 个级别。以下示例具有两个继承级别：
.tests:
only:
- pushes
.rspec:
extends: .tests
script: rake rspec
rspec 1:
variables:
RSPEC_SUITE: '1'
extends: .rspec
rspec 2:
variables:
RSPEC_SUITE: '2'
extends: .rspec
spinach:
extends: .tests
script: rake spinach你也可以为 extends 设置多个父级。
合并请求详情
你可以将 extends 用于合并散列但不能用于数组。用于合并的算法是“最接近的范围获胜”，因此来自最后一个成员的键值总是覆盖其他级别上定义的任何内容。例如：
.only-important:
variables:
URL: "http://my-url.internal"
IMPORTANT_VAR: "the details"
only:
- main
- stable
tags:
- production
script:
- echo "Hello world!"
.in-docker:
variables:
URL: "http://docker-url.internal"
tags:
- docker
image: alpine
rspec:
variables:
GITLAB: "is-awesome"
extends:
- .only-important
- .in-docker
script:
- rake rspec结果 rspec 的流水线任务是：
rspec:
variables:
URL: "http://docker-url.internal"
IMPORTANT_VAR: "the details"
GITLAB: "is-awesome"
only:
- main
- stable
tags:
- docker
image: alpine
script:
- 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 锚点来合并数组。
extends 和 include 一起使用
要重用来自不同配置文件的配置，你可以将 extends 和 include 结合起来使用。
在以下示例中，script 在included.yml文件中定义了a 。然后，在.codechina-ci.yml文件中，extends引用了以下script内容：
-
included.yml：.template: script: - echo Hello! -
. codechina-ci.yml:include: included.yml useTemplate: image: alpine extends: .template
rules
rules 用于在流水线中添加或排除流水线任务。
rules 按顺序评估，直到第一次匹配。找到匹配项后，会将该流水线任务包含在流水线中或从流水线中排除，取决于具体的配置。流水线任务还可以添加某些属性。
rules 替换 only/except ，并且它们不能在同一个流水线任务中一起使用。如果你在一个流水线任务配置为使用这两个关键字，则 linter 会返回 key may not be used with rules 的错误提示。
Rules attributes
rules 中你可以使用的流水线任务属性是：
-
when: 如果未定义，则默认为when: on_success。- 如果用作
when: delayed，start_in也是必需的。
- 如果用作
-
allow_failure: 如果未定义，则默认为allow_failure: false。 -
variables: 如果未定义，则使用别处定义的变量。
如果 rules 评估为真，并且 when 具有除 never 之外的任何值，则流水线任务将包含在流水线中。
例如：
docker build:
script: docker build -t my-image:$CI_COMMIT_REF_SLUG .
rules:
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
when: delayed
start_in: '3 hours'
allow_failure: true
Rules 条款
可用的Rules 条款有：
| 条款 | 描述 |
|---|---|
if |
通过评估if语句向流水线中添加或排除流水线任务。类似于 only:variables
|
changes |
根据更改的文件从流水线中添加或排除流水线任务。与 only:changes 相同 |
exists |
根据特定文件的存在与否向流水线中添加或排除流水线任务 |
rules 按顺序进行评估，直到找到匹配项。如果找到匹配项，则会检查属性以查看是否应将流水线任务添加到流水线中。如果未定义属性，则默认值为：
when: on_successallow_failure: false
流水线任务被添加到流水线中：
- 如果
rules匹配并且具有when: on_success，when: delayed或when: always - 如果没有
rules匹配，但最后一个子句是when: on_success,when: delayed或when: always（没有rules）
流水线任务未添加到流水线中：
- 如果没有
rules匹配，并且没有独立的when: on_success，when: delayed或when: always - 如果
rules匹配，并且具有when: never作为属性
以下示例用于if严格限制流水线任务何时运行：
job:
script: echo "Hello, Rules!"
rules:
- if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
when: manual
allow_failure: true
- if: '$CI_PIPELINE_SOURCE == "schedule"'- 如果管道用于合并请求，则第一个规则匹配，并且作业将添加到合并请求管道中 ，其属性为：
-
when: manual（手工作业） -
allow_failure: true（即使未运行手动作业，管道也会继续运行）
-
- 如果管道不是用于合并请求，则第一条规则不匹配，并评估第二条规则。
- 如果管道是计划管道，则第二条规则匹配，并将作业添加到计划管道。没有定义属性，因此添加了：
-
when: on_success（默认） -
allow_failure: false（默认）
-
- 在所有其他情况下，没有规则匹配，因此不会将作业添加到任何其他管道。
或者，你可以定义一组在少数情况下排除作业的 rules，但在所有其他情况下运行它们：
job:
script: echo "Hello, Rules!"
rules:
- if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
when: never
- if: '$CI_PIPELINE_SOURCE == "schedule"'
when: never
- when: on_success- 如果管道用于合并请求，则不会将作业添加到管道中。
- 如果管道是计划管道，则不会将作业添加到管道中。
- 在所有其他情况下，作业将添加到管道中，带有
when: on_success。
如果您使用
when:条款作为最终规则（不包括when: never），则可能会同时启动两个管道。推送管道和合并请求管道都可以由同一事件触发（推送到源分支以获取开放合并请求）。
避免重复的流水线
如果作业使用rules，则单个操作（例如将提交推送到分支）可以触发多个管道。你不必为多种类型的管道显式配置规则来意外触发它们。
例如：
job:
script: echo "This job creates double pipelines!"
rules:
- if: '$CUSTOM_VARIABLE == "false"'
when: never
- when: always当$CUSTOM_VARIABLE 是 false时此作业不运行，但它在所有其他管道中运行，包括推（分支）和合并请求两个管道。使用此配置，每次推送到开放合并请求的源分支都会导致重复的管道。
为避免重复管道，您可以：
-
使用
CI_OPEN_MERGE_REQUESTSCI/CD 变量workflow:rules在分支和合并请求管道之间进行切换，而不产生重复的管道。您还可以在单个作业规则中使用此变量。 -
使用
workflow指定只在分支管道或只在合并请求管道中运行。 -
重写规则以仅在非常特定的情况下运行作业，并避免最终的
when:规则：job: script: echo "This job does NOT create double pipelines!" rules: - if: '$CUSTOM_VARIABLE == "true" && $CI_PIPELINE_SOURCE == "merge_request_event"'
您还可以通过更改作业规则来避免重复管道，以避免推送（分支）管道或合并请求管道。但是，如果您使用没有规则 workflow: rules 的 - when: always，系统仍会显示管道警告。
例如，以下不会触发双管道，但不推荐没有workflow: rules：
job:
script: echo "This job does NOT create double pipelines!"
rules:
- if: '$CI_PIPELINE_SOURCE == "push"'
when: never
- when: always您不应在同一作业中同时包含推送和合并请求管道的 workflow:rules，以免防止重复管道：
job:
script: echo "This job creates double pipelines!"
rules:
- if: '$CI_PIPELINE_SOURCE == "push"'
- if: '$CI_PIPELINE_SOURCE == "merge_request_event"'此外，不要将同一管道中的 only/except 作业与 rules 作业混合在一起。它可能不会引起 YAML 错误，但不同的默认行为的 only/except 和 rules 可能会导致一些难以解决的问题：
job-with-no-rules:
script: echo "This job runs in branch pipelines."
job-with-rules:
script: echo "This job runs in merge request pipelines."
rules:
- if: '$CI_PIPELINE_SOURCE == "merge_request_event"'对于推送到分支的每个更改，都会运行重复的管道。一个分支管道运行单个作业 ( job-with-no-rules)，一个合并请求管道运行另一个作业 ( job-with-rules)。没有规则的作业默认为 except: merge_requests，因此 job-with-no-rules 在除合并请求之外的所有情况下都会运行。
rules:if
使用 rules:if 条款指定何时向管道添加作业：
- 如果if语句为真，则将作业添加到管道中。
- 如果某个if语句为真，但与
when: never结合使用，则不会将作业添加到管道中。 - 如果没有任何if语句为真，则不会将作业添加到管道中。
rules:if 与 only:variables 略有不同，它的每个规则只接受一个表达式字符串而不是数组。任何一组要计算的表达式都可以通过使用 && 或 || ，以及变量匹配运算符 (==, !=, =~ 和 !~) 连成一个表达式。
与 script 中的变量不同，规则表达式中的变量始终格式为 $VARIABLE。
if: 条款根据预定义 CI/CD 变量 或自定义 CI/CD 变量的值进行评估。
例如：
job:
script: echo "Hello, Rules!"
rules:
- if: '$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME =~ /^feature/ && $CI_MERGE_REQUEST_TARGET_BRANCH_NAME == $CI_DEFAULT_BRANCH'
when: always
- if: '$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME =~ /^feature/'
when: manual
allow_failure: true
- if: '$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME' # Checking for the presence of a variable is possible有关确定 when 作业的逻辑的一些详细信息：
- 如果提供的规则都不匹配，则作业将设置为
when: never并且不包含在管道中。 - 没有任何条款的规则，例如
when或allow_failure规则没有if或者没有changes，总是匹配，并且总是在符合时使用。 - 如果规则匹配到并且未定义
when，则使用when规则定义的作业，，且未定义的情况下默认为on_success。 - 您可以为每个规则定义一次
when，也可以在作业级别定义一次，这将适用于所有规则。您不能在工作级别when与规则when混合使用。
rules 的通用 if 条款
对于类似于 only/except 关键字的行为，您可以检查 $CI_PIPELINE_SOURCE 变量的值：
| 值 | 描述 |
|---|---|
api |
由 pipelines API 触发的管道 |
chat |
使用 GitLab ChatOps 命令创建的管道 |
external |
当您使用 GitLab 以外的 CI 服务 |
external_pull_request_event |
在 GitHub 上创建或更新外部拉取请求时 |
merge_request_event |
对于在创建或更新合并请求时创建的管道。需要启用合并请求管道、合并结果管道和 merge trains
|
parent_pipeline |
对于由带有 rules 的父/子管道触发的管道。在子管道配置中使用此管道源，以便它可以由父管道触发 |
pipeline |
对于通过使用带有CI_JOB_TOKEN的API创建的多项目管道，或 trigger 关键字 |
push |
对于由“git push”事件触发的管道，包括分支和标签 |
schedule |
计划管道 |
trigger |
对于使用 trigger token 创建的管道 |
web |
对于使用 UI 中的 流水线 按钮创建的管道，来自项目的 Devops > 流水线 部分 |
webide |
对于使用 WebIDE 创建的管道 |
以下示例在计划的管道或推送中将作业作为手动作业运行管道（到分支或标签），带有 when: on_success（默认）。它不会将作业添加到任何其他管道类型。
job:
script: echo "Hello, Rules!"
rules:
- if: '$CI_PIPELINE_SOURCE == "schedule"'
when: manual
allow_failure: true
- if: '$CI_PIPELINE_SOURCE == "push"'以下示例中当 when: on_success 时将在合并请求管道和计划管道运行作业
。它不会在任何其他管道类型中运行。
job:
script: echo "Hello, Rules!"
rules:
- if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
- if: '$CI_PIPELINE_SOURCE == "schedule"'if 条款的其他常用变量：
-
if: $CI_COMMIT_TAG：如果为标签推送更改。 -
if: $CI_COMMIT_BRANCH：如果更改被推送到任何分支。 -
if: '$CI_COMMIT_BRANCH == "main"'：如果更改被推送到main。 -
if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'：如果更改被推送到默认分支。当你想在多个相同的配置中使用具有不同默认分支的项目。 -
if: '$CI_COMMIT_BRANCH =~ /regex-expression/'：如果提交分支匹配正则表达式。 -
if: '$CUSTOM_VARIABLE !~ /regex-expression/': 如果自定义变量CUSTOM_VARIABLE不 匹配正则表达式。 -
if: '$CUSTOM_VARIABLE == "value1"'：如果自定义变量CUSTOM_VARIABLE值 正是value1。
rules:changes
使用 rules:changes 当改特定文件时将作业添加到管道。
rules: changes 的工作方式与 only: changes 和 except: changes 相同。它接受一组路径。你应该只对分支使用 rules: changes
管道或合并请求管道。例如，通常对合并请求管道使用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 用于分支管道而不是合并请求管道，将之前示例中的 if: 子句更改为：
rules:
- if: $CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH要实现类似于 except:changes 的规则，
使用 when: never。
您可以将
rules: changes与其他管道类型一起使用，但不推荐使用。因为当没有 Gitpush事件时，rules: changes总是评估为true。标记管道、计划管道等没有有 Gitpush事件 与他们有关。rules: changes作业始终添加到这些管道中，如果没有if:语句将作业限制为分支或合并请求管道的话。
rules:changes 中的变量
您可以在 rules:changes 表达式中使用 CI/CD 变量来确定何时向管道添加作业：
docker build:
variables:
DOCKERFILES_DIR: 'path/to/files/'
script: docker build -t my-image:$CI_COMMIT_REF_SLUG .
rules:
- changes:
- $DOCKERFILES_DIR/*您可以将 $ 字符用于变量和路径。例如，如果 $DOCKERFILES_DIR 变量存在，它的值被使用。如果不存在，则 $ 被解释为路径的一部分。
rules:exists
当存储库中存在某些文件时，使用 exists 来运行作业。您可以使用一组路径。
在以下示例中，如果存储库中的任何位置存在 Dockerfile，job 就会运行：
job:
script: docker build -t my-image:$CI_COMMIT_REF_SLUG .
rules:
- exists:
- Dockerfileexists 的路径相对于项目目录 ($CI_PROJECT_DIR)，不能直接链接到项目目录之外。
您可以使用 glob 的模式在存储库中匹配任何目录中的多个文件：
job:
script: bundle exec rspec
rules:
- exists:
- spec/**.rbGlob 模式用 Ruby 解释 File.fnmatch 带有标志 File::FNM_PATHNAME | File::FNM_DOTMATCH | File::FNM_EXTGLOB。
出于性能原因，最多匹配 10,000 个 exists 模式。在第 10,000 次检查之后，带有 glob 的规则将始终匹配。
rules:allow_failure
您可以在 rules: 中使用 allow_failure: true 来允许作业失败，或等待一个手动作业的操作，而不停止管道本身。所有使用 rules: 的作业在你没有定义 allow_failure:的情况下默认为 allow_failure: false。
规则级别的 rules:allow_failure 选项覆盖作业级别 allow_failure 选项，仅在特定规则触发作业后进行。
job:
script: echo "Hello, Rules!"
rules:
- if: '$CI_MERGE_REQUEST_TARGET_BRANCH_NAME == $CI_DEFAULT_BRANCH'
when: manual
allow_failure: true在此示例中，如果第一条规则匹配，则作业具有 when: manual 和 allow_failure: true。
rules:variables
在 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"复杂规则条款
要将 if 、 changes 和 exists 条款用 AND 连接起来，并用在同一条规则中。
在以下示例中：
- 如果
Dockerfile文件或/docker/scripts中的任何文件发生了变化，并且$VAR== "string value"，则作业手动运行 - 否则，作业不包含在管道中。
docker build:
script: docker build -t my-image:$CI_COMMIT_REF_SLUG .
rules:
- if: '$VAR == "string value"'
changes: # Include the job and set to when:manual if any of the follow paths match a modified file.
- Dockerfile
- docker/scripts/*
when: manual
# - "when: never" would be redundant here. It is implied any time rules are listed.诸如 branches 或 refs 之类的关键字可用于 only/except，但在 rules 中不可用。
您可以使用括号 [] 和 && 和 || 来构建更复杂的变量表达式。
job1:
script:
- echo This rule uses parentheses.
rules:
if: ($CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH || $CI_COMMIT_BRANCH == "develop") && $MY_VARIABLE
only / except
您可以使用 only 和 except 来控制何时向管道添加作业。
- 使用
only来定义作业何时运行。 - 使用
except定义作业何时 不 运行。
四个关键字可以与 only 和 except 一起使用：
only:refs / except:refs
使用 only:refs 和 except:refs 关键字来控制何时将作业添加到基于分支名称或管道类型的管道。
关键字类型：工作关键字。您只能将其用作工作的一部分。
可能的输入：包含任意数量的数组：
-
分支名称，例如
main或my-feature-branch。 -
正则表达式匹配分支名称，例如
/^feature-.*/。 -
以下关键词：
关键词 说明 api对于由 pipelines API 触发的管道 branches当管道的 Git 引用是分支时 chat对于使用 ChatOps命令创建的管道 external当您使用 GitLab 以外的 CI 服务时 external_pull_requests在 GitHub 上创建或更新外部拉取请求时 merge_request对于在创建或更新合并请求时创建的管道。启用合并请求管道、合并的结果管道 和 merge trainspipelines对于通过使用带有 CI_JOB_TOKEN的API创建的多项目管道，或trigger关键字push对于由“git push”事件触发的管道，包括分支和标签 schedules计划管道 tags当管道的 Git 引用是标签时 triggers对于使用 trigger token创建的管道web对于使用 UI 中的 流水线 按钮创建的管道，来自项目的 DevOps > 流水线 部分
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。比如下面两个job的配置是一样的行为：job1: script: echo only: - branches job2: script: echo only: refs: - branches -
如果作业不使用
only、except或rules，则only默认设置为branches和tag。例如，
job1和job2是等价的：job1: script: echo 'test' job2: script: echo 'test' only: - branches - tags
only:variables / except:variables
使用 only:variables 或 except:variables 关键字来控制何时添加作业
到管道，基于 CI/CD 变量 的状态。
关键字类型：工作关键字。您只能将其用作工作的一部分。
可能的输入：CI/CD 变量表达式 的数组。
only:variables 示例：
deploy:
script: cap staging deploy
only:
variables:
- $RELEASE == "staging"
- $STAGING
only:changes / except:changes
当 Git 推送事件修改文件时，使用 changes 关键字和 only 来运行一个作业，或者使用 except 来跳过一个作业。
在具有以下引用的管道中使用changes：
分支external_pull_requestsmerge_requests
关键字类型：工作关键字。您只能将其用作工作的一部分。
可能的输入：包含任意数量的数组：
- 文件路径。
- 单个目录的通配符路径，例如
path/to/directory/*，或一个目录及其所有子目录，例如path/to/directory/**/*。 - 通配符 (glob) 所有路径具有相同扩展名或多个扩展名的文件，例如
*.md或path/to/directory/*.{rb,py,sh}。 - 根目录或所有目录中文件的通配符路径，用双引号括起来。例如
"*.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}更多细节：
- 如果你使用除
branches、external_pull_requests或merge_requests以外的引用，changes无法确定给定文件是新文件还是旧文件，并且总是返回true。 - 如果您将
only: changes与其他引用一起使用，作业将忽略更改并始终运行。 - 如果您将
except: changes与其他引用一起使用，作业将忽略更改并且
only:kubernetes / except:kubernetes
当 Kubernetes 服务在项目中处于活动状态时，使用 only:kubernetes 或 except:kubernetes 来控制是否将作业添加到管道中。
关键字类型：特定于工作。您只能将其用作工作的一部分。
可能的输入：kubernetes 策略只接受 active 关键字。
only:kubernetes 示例：
deploy:
only:
kubernetes: active在此示例中，deploy 作业仅在 Kubernetes 服务处于活动状态时运行在项目中。
needs
使用 needs: 来乱序执行作业。工作之间的关系可使用 needs 可视化为有向无环图。
您可以忽略阶段排序并运行一些作业，而无需等待其他作业完成。多个阶段的作业可以同时运行。
以下示例创建四个执行路径：
- 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。
linux:build:
stage: build
mac:build:
stage: build
lint:
stage: test
needs: []
linux:rspec:
stage: test
needs: ["linux:build"]
linux:rubocop:
stage: test
needs: ["linux:build"]
mac:rspec:
stage: test
needs: ["mac:build"]
mac:rubocop:
stage: test
needs: ["mac:build"]
production:
stage: deploy要求和限制
- 在 GitLab 13.9 及更早版本中，如果
needs:指的是因only、except或rules等可能不会添加到的作业，则管道可能无法创建。 -
needs:数组中单个作业可以需要的最大作业数是有限的，限制是：50。 - 如果
needs:是指使用parallel关键字的作业，这取决于并行创建的所有工作，而不仅仅是一项工作。它也下载默认情况下来自所有并行作业的artifacts。如果artifacts有相同的名称，它们会相互覆盖，并且只保存最后下载的一个。 -
needs:类似于dependencies:，因为它必须使用先前阶段的作业，这意味着不可能创建循环依赖项。根据工作当前阶段也不可能。 - 必须为所有有关键字
needs:或被其引用的作业明确定义阶段。
使用 needs 下载 artifacts
当作业使用 needs 时，默认情况下它不再下载前一阶段的所有 artifacts，因为具有 medds 的作业可以在早期阶段完成之前开始。当存在 needs 时，你只能从 needs: 配置中列出的作业下载 artifacts。
使用 artifacts: true（默认值）或 artifacts: false 在出现在使用 needs 的作业中来控制何时下载 artifacts。
在以下示例中，rspec 作业下载了 build_job 的 artifacts，但是rubocop 工作不会：
build_job:
stage: build
artifacts:
paths:
- binaries/
rspec:
stage: test
needs:
- job: build_job
artifacts: true
rubocop:
stage: test
needs:
- job: build_job
artifacts: false在以下示例中，rspec 作业从所有三个 build_jobs 中下载 artifacts。其中 artifacts 设置为：
- 对
build_job_1设置为true。 - 对于
build_job_2和build_job_3，默认为true。
rspec:
needs:
- job: build_job_1
artifacts: true
- job: build_job_2
- build_job_3
needs 跨项目下载 artifacts
管道中使用 needs 从最多五个作业下载 artifacts：
- 在同一项目中的其他 ref
- 在不同的项目、组和命名空间中
build_job:
stage: build
script:
- ls -lhR
needs:
- project: namespace/group/project-name
job: build-1
ref: main
artifacts: truebuild_job 从 group/project-name 项目的 main 分支上最新成功的 build-1 作业下载 artifacts。如果项目在
相同的组或命名空间，您可以从 project: 关键字中省略它们。例如，
project: group/project-name 或 project: project-name。
运行管道的用户必须至少具有对组或项目的“报告者”访问权限，或者组/项目必须具有公开可见性。
同一项目中管道之间的工件下载
使用 needs 从当前项目中的不同管道下载工件。
将 project 关键字设置为当前项目的名称，并指定一个引用。
在以下示例中，build_job 下载最新成功的工件
带有 other-ref ref 的 build-1 作业：
构建_作业：
阶段：构建
脚本：
- ls -lhR
需要：
- 项目：组/相同项目名称
工作：build-1
参考：其他参考
文物：真实
``
对 `project:`、`job:` 和 `ref` 的 CI/CD 变量支持[介绍](https://gitlab.com/gitlab-org/gitlab/-/issues/202093)
在 GitLab 13.3 中。[已删除功能标志](https://gitlab.com/gitlab-org/gitlab/-/issues/235761) 在 GitLab 13.4 中。
例如：
```yaml
构建_作业：
阶段：构建
脚本：
- ls -lhR
需要：
- 项目：$CI_PROJECT_PATH
工作：$DEPENDENCY_JOB_NAME
参考：$ARTIFACTS_DOWNLOAD_REF
文物：真实
``
您无法从在 [`parallel:`](#parallel) 中运行的作业下载工件。
要在 [父子管道](../parent_child_pipelines.md) 之间下载工件，
使用 [`needs:pipeline`](#artifact-downloads-to-child-pipelines)。
您不应从与正在运行的管道相同的 ref 下载工件。同时
在同一个 ref 上运行的管道可能会覆盖工件。
##### 工件下载到子管道
> [介绍](https://gitlab.com/gitlab-org/gitlab/-/issues/255983) 在 GitLab v13.7 中。
[子管道](../parent_child_pipelines.md) 可以从作业中下载工件
它的父管道或同一父子管道层次结构中的另一个子管道。
例如，使用以下具有创建一些工件的作业的父管道：
```yaml
创建工件：
阶段：构建
脚本：回显“样本工件”> artifact.txt
文物：
路径：[artifact.txt]
子管道：
阶段：测试
扳机：
包括：child.yml
策略：依赖
变量：
PARENT_PIPELINE_ID：$CI_PIPELINE_ID
``
子管道中的作业可以从“create-artifact”作业中下载工件
父管道：
```yaml
使用神器：
脚本：cat artifact.txt
需要：
- 管道：$PARENT_PIPELINE_ID
工作：创建工件
``
`pipeline` 属性接受一个管道 ID，它必须是一个存在的管道
在给定管道的相同父子管道层次结构中。
`pipeline` 属性不接受当前的管道 ID (`$CI_PIPELINE_ID`)。
要从当前管道中的作业下载工件，请使用 [`needs`](#artifact-downloads-with-needs) 的基本形式。
#### 可选`需要`
> - [介绍](https://gitlab.com/gitlab-org/gitlab/-/issues/30680) 在 GitLab 13.10 中。
> - [已删除功能标志](https://gitlab.com/gitlab-org/gitlab/-/issues/323891) 在 GitLab 14.0 中。
要需要管道中有时不存在的作业，请添加 `optional: true`
到`needs` 配置。如果未定义，`optional: false` 是默认值。
使用 [`rules`](#rules)、[`only` 或 `except`](#only--except) 的作业可能
并不总是存在于管道中。当管道启动时，它会检查“需求”
跑步前的关系。没有`optional: true`，需要的关系
指向不存在的作业会阻止管道启动并导致管道
错误类似于：
- `'job1' 作业需要'job2' 作业，但它没有被添加到管道中`
在这个例子中：
- 当分支为默认分支时，管道中存在`build`作业，`rspec`
作业在开始之前等待它完成。
- 当分支不是默认分支时，管道中不存在 `build` 作业。
`rspec` 作业立即运行（类似于 `needs: []`），因为它的 `needs`
与 `build` 作业的关系是可选的。
```yaml
建造：
阶段：构建
规则：
- 如果：$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
规格：
阶段：测试
需要：
- 工作：构建
可选：真
``
###`标签`
使用 `tags` 从所有跑步者的列表中选择一个特定的跑步者
可用于项目。
当您注册跑步者时，您可以指定跑步者的标签，例如
例如`ruby`、`postgres`、`development`。
在以下示例中，作业由运行程序运行
定义了 `ruby` 和 `postgres` 标签。
```yaml
工作：
标签：
- 红宝石
- postgres
``
您可以使用标签在不同平台上运行不同的作业。为了
例如，如果您有一个带有“osx”标签的 OS X 运行器和一个带有标签的 Windows 运行器
`windows`，你可以在每个平台上运行一个作业：
```yaml
窗口工作：
阶段：
- 建造
标签：
- 窗户
脚本：
- echo 你好，%USERNAME%！
osx 工作：
阶段：
- 建造
标签：
- osx
脚本：
- echo "你好，$USER！"
``
###`allow_failure`
当您想让作业失败而不影响 CI 的其余部分时，请使用 `allow_failure`
套房。默认值为 `false`，除了 [manual](#whenmanual) 使用
`when: manual` 语法。
在使用 [`rules:`](#rules) 的作业中，所有作业默认为 `allow_failure: false`，
*包括*`when：手动`作业。
当 `allow_failure` 设置为 `true` 并且作业失败时，作业会在 UI 中显示橙色警告。
但是，管道的逻辑流将作业视为
成功/通过，并且没有被阻止。
假设所有其他作业都成功，作业的阶段及其管道
显示相同的橙色警告。但是，关联的提交被标记为
“通过”，没有警告。
在以下示例中，`job1` 和 `job2` 并行运行。如果`job1`
失败，它不会停止下一个阶段的运行，因为它被标记为
`allow_failure: true`:
```yaml
工作1：
阶段：测试
脚本：
- execute_script_that_will_fail
allow_failure: 真
工作2：
阶段：测试
脚本：
- execute_script_that_will_succeed
工作3：
阶段：部署
脚本：
- deploy_to_staging
``
#### `allow_failure:exit_codes`
> - [介绍](https://gitlab.com/gitlab-org/gitlab/-/issues/273157) 在 GitLab 13.8 中。
> - [已删除功能标志](https://gitlab.com/gitlab-org/gitlab/-/issues/292024) 在 GitLab 13.9 中。
使用 `allow_failure:exit_codes` 动态控制是否应该允许作业
失败。您可以列出哪些退出代码不被视为失败。作业失败
对于任何其他退出代码：
```yaml
test_job_1：
脚本：
- echo "运行导致退出代码 1 的脚本。此作业失败。"
- 退出 1
允许失败：
退出代码：137
test_job_2：
脚本：
- echo "运行导致退出代码 137 的脚本。允许此作业失败。"
- 退出 137
允许失败：
退出代码：
- 137
- 255
``
###`什么时候`
使用 `when` 来实现在失败或不顾一切情况下运行的作业
失败。
`when` 的有效值为：
1. `on_success`（默认）- 只有在早期阶段的所有作业都成功时才执行作业，
或者被认为是成功的，因为它们有 `allow_failure: true`。
1. `on_failure` - 仅在较早阶段的至少一项作业失败时才执行作业。
1. `always` - 无论早期阶段的作业状态如何，都执行作业。
1. `manual` - [手动](#whenmanual) 执行作业。
1. `delayed` - [延迟作业的执行](#whendelayed) 指定的持续时间。
在 GitLab 11.14 中添加。
1.`从不`：
- 使用作业 [`rules`](#rules)，不要执行作业。
- 使用 [`workflow:rules`](#workflow)，不要运行管道。
在以下示例中，脚本：
1. 只有当`build_job`失败时才执行`cleanup_build_job`。
1. 始终执行`cleanup_job`作为管道的最后一步，不管
成功或失败。
1. 在 GitLab UI 中手动运行时执行 `deploy_job`。
```yaml
阶段：
- 建造
- 清理_构建
- 测试
- 部署
- 清理
构建_作业：
阶段：构建
脚本：
- 进行构建
cleanup_build_job:
阶段：cleanup_build
脚本：
- 失败时清理构建
时间：on_failure
测试工作：
阶段：测试
脚本：
- 进行测试
部署_作业：
阶段：部署
脚本：
- 进行部署
时间：手动
清理工作：
阶段：清理
脚本：
- 工作后的清理
什么时候：总是
``
####`when:manual`
手动作业是一种不会自动执行的作业，必须明确
由用户启动。您可能希望将手动作业用于部署到生产之类的事情。
要制作作业手册，请将 `when: manual` 添加到其配置中。
管道启动时，手动作业显示为已跳过且不会自动运行。
它们可以从管道、作业、[环境](../environments/index.md#configure-manual-deployments)、
和部署视图。
手动作业可以是可选的或阻塞的：
- **可选**：手动作业默认设置为 [`allow_failure: true](#allow_failure)
并且被认为是可选的。可选手工作业的状态没有贡献
到整体管道状态。即使所有手动作业都失败，管道也可以成功。
- **阻塞**：要进行阻塞手动作业，请将 `allow_failure: false` 添加到其配置中。
阻塞手动作业会在以下阶段停止管道的进一步执行
工作被定义。要让管道继续运行，请单击 **{play}** (play) on
阻塞手工作业。
使用 [管道成功时合并](../../user/project/merge_requests/merge_when_pipeline_succeeds.md) 合并项目中的请求
enabled 不能与阻塞的管道合并。阻塞的管道显示状态
**阻止**。
当您使用 [`rules:`](#rules) 时，`allow_failure` 默认为 `false`，包括手动作业。
要触发手动作业，用户必须具有合并到指定分支的权限。
您可以使用 [protected branch](../../user/project/protected_branches.md) 来更严格
[保护手动部署](#protecting-manual-jobs) 不被未经授权的用户运行。
在 [GitLab 13.5](https://gitlab.com/gitlab-org/gitlab/-/issues/201938) 及更高版本中，您
可以在与 [`trigger`](#trigger) 相同的作业中使用 `when:manual`。在 GitLab 13.4 和
早些时候，将它们一起使用会导致错误 `jobs:#{job-name} when should be on_success, on_failure or always`。
##### 保护手工作业 **(PREMIUM)**
使用[受保护的环境](../environments/protected_environments.md)
定义授权运行手动作业的用户列表。您只能授权
与受保护环境关联以触发手动作业的用户，这可以：
- 更精确地限制可以部署到环境的人员。
- 阻止管道，直到获得批准的用户“批准”它。
要保护手动作业：
1. 为作业添加一个 `environment`。例如：
```yaml
deploy_prod:
阶段：部署
脚本：
- echo "部署到生产服务器"
环境：
名称：生产
网址：https://example.com
时间：手动
只要：
- 主要的
``
1.在[受保护的环境设置](../environments/protected_environments.md#protecting-environments)中，
选择环境（本例中为“生产”）并添加用户、角色或组
被授权触发手动作业到 **Allowed to Deploy** 列表。只有那些在
此列表可以触发此手动作业，以及 GitLab 管理员
谁总是能够使用受保护的环境。
您可以使用具有阻止手动作业的受保护环境来获得用户列表
允许批准以后的管道阶段。将 `allow_failure: false` 添加到受保护的
手动作业和管道的下一阶段仅在手动作业被触发后运行
由授权用户。
####`何时：延迟`
> [介绍](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/51352) 在 GitLab 11.4 中。
使用 `when: delay` 在等待期后执行脚本，或者如果你想避免
作业立即进入“待处理”状态。
您可以使用“start_in”关键字设置时间段。`start_in` 的值是以秒为单位的经过时间，除非一个单位是
假如。`start_in` 必须小于或等于 1 周。有效值的示例包括：
- `'5'`
- `5秒`
- `30分钟`
- `1天`
- `1周`
当阶段包含延迟作业时，管道在延迟作业完成之前不会进行。
您可以使用此关键字在不同阶段之间插入延迟。
延迟作业的计时器在前一阶段完成后立即启动。
与其他类型的作业类似，除非前一阶段通过，否则延迟作业的计时器不会启动。
以下示例创建一个名为“timed rollout 10%”的作业，该作业在前一阶段完成 30 分钟后执行：
```yaml
定时推出 10%：
阶段：部署
脚本：echo '推出 10% ...'
时间：延迟
start_in：30 分钟
``
要停止延迟作业的活动计时器，请单击 **{time-out}** (**Unschedule**) 按钮。
无法再安排此作业自动运行。但是，您可以手动执行作业。
要立即开始延迟作业，请单击**播放** 按钮。
很快，GitLab Runner 接手并开始工作。
###`环境`
使用 `environment` 定义作业部署到的 [环境](../environments/index.md)。
例如：
```yaml
部署到生产：
阶段：部署
脚本：git push production HEAD：main
环境：生产
``
您可以使用以下方法为 `environment` 关键字赋值：
- 纯文本，如 `production`。
- 变量，包括 CI/CD 变量、预定义、安全或变量
在`.gitlab-ci.yml` 文件中定义。
您不能使用在 `script` 部分中定义的变量。
如果您指定了一个 `environment` 并且不存在具有该名称的环境，
创造了一个环境。
####`环境：名称`
为 [environment](../environments/index.md) 设置名称。例如：
```yaml
部署到生产：
阶段：部署
脚本：git push production HEAD：main
环境：
名称：生产
``
常见的环境名称是 `qa`、`staging` 和 `production`，但您可以使用任何
你想要的名字。
您可以使用以下命令为 `name` 关键字赋值：
- 纯文本，如`staging`。
- 变量，包括 CI/CD 变量、预定义、安全或变量
在`.gitlab-ci.yml` 文件中定义。
您不能使用在 `script` 部分中定义的变量。
环境 `name` 可以包含：
- 信件
- 数字
- 空间
-`-`
-`_`
-`/`
-`$`
-`{`
-`}`
####`环境：url`
为 [environment](../environments/index.md) 设置 URL。例如：
```yaml
部署到生产：
阶段：部署
脚本：git push production HEAD：main
环境：
名称：生产
网址：https://prod.example.com
``
作业完成后，您可以使用合并请求中的按钮访问 URL，
环境或部署页面。
您可以使用以下方法为 `url` 关键字赋值：
- 纯文本，如`https://prod.example.com`。
- 变量，包括 CI/CD 变量、预定义、安全或变量
在`.gitlab-ci.yml` 文件中定义。
您不能使用在 `script` 部分中定义的变量。
####`环境：on_stop`
关闭（停止）环境可以使用 `on_stop` 关键字来实现
在“环境”下定义。它声明了一个不同的工作来关闭
环境。
阅读“environment:action”部分的示例。
####`环境：动作`
使用 `action` 关键字来指定准备、启动或停止环境的作业。
| **价值** | **说明** |
|-----------|------------------------------------ -------------------------------------------------- -------------------------------------------------- ---------------|
| `开始` | 默认值。表示作业启动环境。部署是在作业启动后创建的 |
| `准备` | 表示作业只准备环境。它不会触发部署。[阅读有关准备环境的更多信息](../environments/index.md#prepare-an-environment-without-creating-a-deployment) |
| `停止` | 表示作业停止部署。请参阅下面的示例 |
举个例子：
```yaml
评论应用：
阶段：部署
脚本：制作部署应用程序
环境：
名称：评论/$CI_COMMIT_REF_NAME
网址：https://$CI_ENVIRONMENT_SLUG.example.com
on_stop：stop_review_app
stop_review_app:
阶段：部署
变量：
GIT_STRATEGY：无
脚本：make delete-app
时间：手动
环境：
名称：评论/$CI_COMMIT_REF_NAME
行动：停止
``
在上面的例子中，`review_app` 作业部署到 `review`
环境。在“on_stop”下列出了一个新的“stop_review_app”作业。
在“review_app”作业完成后，它会触发
`stop_review_app` 作业基于 `when` 下定义的内容。在这种情况下，
它被设置为 `manual`，所以它需要一个 [manual action](#whenmanual) from
要运行的 GitLab UI。
同样在示例中，`GIT_STRATEGY` 设置为 `none`。如果
`stop_review_app` 作业是[自动触发](../environments/index.md#stopping-an-environment)，
删除分支后，运行程序不会尝试检查代码。
该示例还覆盖了全局变量。如果您的“停止”“环境”工作取决于
在全局变量上，在设置 `GIT_STRATEGY` 时使用 [anchor variables](#yaml-anchors-for-variables)
在不覆盖全局变量的情况下更改作业。
`stop_review_app` 作业**需要**定义以下关键字：
- `when`，定义于：
- [工作级别](#when)。
- [在规则子句中](#rules)。如果你使用 `rules:` 和 `when: manual`，你应该
还设置 [`allow_failure: true`](#allow_failure) 以便管道可以完成
即使作业没有运行。
-`环境：名称`
-`环境：动作`
此外，两个工作都应该有匹配的 [`rules`](#only--except)
或 [`only/except`](#only--except) 配置。
在上面的示例中，如果配置不相同：
- `stop_review_app` 作业可能不会包含在包含 `review_app` 作业的所有管道中。
- 无法触发 `action: stop` 来自动停止环境。
####`环境：auto_stop_in`
> [介绍](https://gitlab.com/gitlab-org/gitlab/-/issues/20956) 在 GitLab 12.8 中。
`auto_stop_in` 关键字用于指定环境的生命周期，
当过期时，GitLab 会自动停止它们。
例如，
```yaml
评论应用：
脚本：deploy-review-app
环境：
名称：评论/$CI_COMMIT_REF_NAME
auto_stop_in：1 天
``
当为“review_app”创建环境时，环境的生命周期设置为“1 天”。
每次部署审查应用程序时，该生命周期也会重置为“1 天”。
有关更多信息，请参阅
[环境自动停止文档](../environments/index.md#stop-an-environment-after-a-certain-time-period)
####`环境：kubernetes`
> [介绍](https://gitlab.com/gitlab-org/gitlab/-/issues/27630) 在 GitLab 12.6 中。
使用 `kubernetes` 关键字将部署配置为
[Kubernetes cluster](../../user/project/clusters/index.md) 与您的项目相关联。
例如：
```yaml
部署：
阶段：部署
脚本：制作部署应用程序
环境：
名称：生产
Kubernetes：
命名空间：生产
``
此配置设置了 `deploy` 作业以部署到 `production`
环境，使用 `production`
[Kubernetes 命名空间](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/)。
有关更多信息，请参阅
[`kubernetes` 的可用设置](../environments/index.md#configure-kubernetes-deployments)。
笔记：
Kubernetes 集群不支持 Kubernetes 配置
[由 GitLab 管理](../../user/project/clusters/index.md#gitlab-managed-clusters)。
要了解对 GitLab 管理的集群的支持进展，请参阅
[相关问题](https://gitlab.com/gitlab-org/gitlab/-/issues/38054)。
####`环境：deployment_tier`
> [介绍](https://gitlab.com/gitlab-org/gitlab/-/issues/300741) 在 GitLab 13.10 中。
使用 `deployment_tier` 关键字指定部署环境的层级：
```yaml
部署：
脚本：回声
环境：
名称：客户门户
部署层：生产
``
想要查询更多的信息，
请参阅[环境的部署层](../environments/index.md#deployment-tier-of-environments)。
#### 动态环境
使用 CI/CD [variables](../variables/README.md) 动态命名环境。
例如：
```yaml
部署为审查应用程序：
阶段：部署
脚本：进行部署
环境：
名称：评论/$CI_COMMIT_REF_NAME
网址：https://$CI_ENVIRONMENT_SLUG.example.com/
``
`deploy as review app` 作业被标记为动态部署
创建 `review/$CI_COMMIT_REF_NAME` 环境。`$CI_COMMIT_REF_NAME`
是由跑步者设置的 [CI/CD 变量](../variables/README.md)。这
`$CI_ENVIRONMENT_SLUG` 变量基于环境名称，但适用
用于包含在 URL 中。如果 `deploy as review app` 作业在名为的分支中运行
`pow`，这个环境可以通过像 `https://review-pow.example.com/` 这样的 URL 访问。
常见的用例是为分支创建动态环境并使用它们
作为审查应用程序。您可以在以下位置查看使用 Review Apps 的示例
<https://gitlab.com/gitlab-examples/review-apps-nginx/>。
###`缓存`
使用 `cache` 指定要使用的文件和目录列表
作业之间的缓存。您只能使用本地工作副本中的路径。
如果在作业范围之外定义了 `cache`，则设置它
全局和所有作业都使用该配置。
缓存在管道和作业之间共享。缓存在 [artifacts](#artifacts) 之前恢复。
阅读缓存的工作原理并在
[缓存依赖文档](../caching/index.md)。
####`缓存：路径`
使用 `paths` 指令选择要缓存的文件或目录。路径
相对于项目目录 (`$CI_PROJECT_DIR`)，不能直接链接到项目目录之外。
您可以使用使用 [glob](https://en.wikipedia.org/wiki/Glob_(programming)) 的通配符
模式和：
- 在 [GitLab Runner 13.0](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/2620) 及更高版本中，
[`doublestar.Glob`](https://pkg.go.dev/github.com/bmatcuk/doublestar@v1.2.2?tab=doc#Match)。
- 在 GitLab Runner 12.10 及更早版本中，
[`filepath.Match`](https://pkg.go.dev/path/filepath#Match)。
缓存`binaries`中以`.apk`和`.config`文件结尾的所有文件：
```yaml
规格：
脚本：测试
缓存：
路径：
- 二进制文件/*.apk
- .config
``
本地定义的缓存覆盖全局定义的选项。以下`rspec`
作业只缓存 `binaries/`：
```yaml
缓存：
路径：
- 我的文件
规格：
脚本：测试
缓存：
关键：rspec
路径：
- 二进制文件/
``
缓存在作业之间共享，因此如果您使用不同的
不同作业的路径，您还应该设置不同的 `cache:key`。
否则缓存内容可能会被覆盖。
####`缓存：密钥`
`key` 关键字定义了作业之间缓存的亲和性。
您可以为所有作业使用一个缓存，每个作业缓存，每个分支缓存，
或任何其他适合您工作流程的方式。您可以微调缓存，
包括在不同作业甚至不同分支之间缓存数据。
`cache:key` 变量可以使用任何
[预定义变量](../variables/README.md)。默认键，如果不是
设置，只是字面上的“默认”，这意味着一切都在之间共享
默认情况下管道和作业。
例如，要启用每个分支缓存：
```yaml
缓存：
键：“$CI_COMMIT_REF_SLUG”
路径：
- 二进制文件/
``
如果您使用 **Windows Batch** 运行您的 shell 脚本，则需要替换
`$` 和 `%`：
```yaml
缓存：
键：“%CI_COMMIT_REF_SLUG%”
路径：
- 二进制文件/
``
`cache:key` 变量不能包含 `/` 字符或等效字符
URI 编码的“%2F”。也禁止仅由点（`.`、`%2E`）组成的值。
如果未找到指定的 `cache:key`，您可以指定 [fallback cache key](#fallback-cache-key) 使用。
#####多个缓存
> - [介绍](https://gitlab.com/gitlab-org/gitlab/-/issues/32814) 在 GitLab 13.10 中。
> - [功能标记已删除](https://gitlab.com/gitlab-org/gitlab/-/issues/321877)，在 GitLab 13.12 中。
您最多可以有四个缓存：
```yaml
测试工作：
阶段：构建
缓存：
- 钥匙：
文件：
- Gemfile.lock
路径：
- 供应商/红宝石
- 钥匙：
文件：
- 纱线锁
路径：
- .纱线缓存/
脚本：
- 捆绑安装 --path=vendor
- 纱线安装 --cache-folder .yarn-cache
- 回声运行测试...
``
如果多个缓存与一个 [Fallback 缓存键](#fallback-cache-key) 组合在一起，
如果未找到多个缓存，则多次获取回退。
#### 回退缓存键
> [介绍](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/1534) 在 GitLab Runner 13.4 中。
你可以使用`$CI_COMMIT_REF_SLUG` [variable](#variables) 来指定你的[`cache:key`](#cachekey)。
例如，如果你的 `$CI_COMMIT_REF_SLUG` 是 `test` 你可以设置一个作业
下载标有“test”的缓存。
如果没有找到带有这个标签的缓存，你可以使用`CACHE_FALLBACK_KEY`来
指定缓存不存在时使用。
在以下示例中，如果未找到 `$CI_COMMIT_REF_SLUG`，则作业使用定义的键
通过`CACHE_FALLBACK_KEY`变量：
```yaml
变量：
CACHE_FALLBACK_KEY：回退键
缓存：
键：“$CI_COMMIT_REF_SLUG”
路径：
- 二进制文件/
``
#####`缓存：密钥：文件`
> [介绍](https://gitlab.com/gitlab-org/gitlab/-/issues/18986) 在 GitLab v12.5 中。
`cache:key:files` 关键字扩展了 `cache:key` 功能，使其更容易
重用一些缓存，并减少重建它们的频率，从而加快后续管道
运行。
当您包含 `cache:key:files` 时，您还必须列出用于生成密钥的项目文件，最多两个文件。
缓存“key”是根据最近提交计算的 SHA 校验和（最多两个，如果列出了两个文件）
改变了给定的文件。如果在任何提交中都没有更改任何文件，
后备键是`default`。
```yaml
缓存：
钥匙：
文件：
- Gemfile.lock
- 包.json
路径：
- 供应商/红宝石
- 节点模块
``
此示例为 Ruby 和 Node.js 依赖项创建缓存
与当前版本的 `Gemfile.lock` 和 `package.json` 文件相关联。每当其中之一
这些文件发生变化，计算新的缓存键并创建新的缓存。任何未来
作业运行使用相同的 `Gemfile.lock` 和 `package.json` 和 `cache:key:files`
使用新的缓存，而不是重建依赖项。
#####`缓存：键：前缀`
> [介绍](https://gitlab.com/gitlab-org/gitlab/-/issues/18986) 在 GitLab v12.5 中。
当您想将前缀与为 `cache:key:files` 计算的 SHA 结合起来时，
将 `prefix` 关键字与 `key:files` 一起使用。
例如，如果添加 `test` 的 `prefix`，结果键为：`test-feef9576d21ee9b6a32e30c5c79d0a0ceb68d1e5`。
如果在任何提交中都没有更改任何文件，则将前缀添加到 `default`，因此
示例中的关键是“test-default”。
像`cache:key`一样，`prefix`可以使用任何[预定义变量](../variables/README.md)，
但不能包括：
- `/` 字符（或等效的 URI 编码的 `%2F`）
- 仅由 `.` 组成的值（或等效的 URI 编码的 `%2E`）
```yaml
缓存：
钥匙：
文件：
- Gemfile.lock
前缀：${CI_JOB_NAME}
路径：
- 供应商/红宝石
规格：
脚本：
- 捆绑执行 rspec
``
例如，添加`$CI_JOB_NAME`的`prefix`
导致密钥看起来像：`rspec-feef9576d21ee9b6a32e30c5c79d0a0ceb68d1e5`和
作业缓存在不同的分支之间共享。如果分支发生变化
`Gemfile.lock`，该分支对 `cache:key:files` 有一个新的 SHA 校验和。一个新的缓存键
生成，并为该键创建一个新的缓存。
如果没有找到`Gemfile.lock`，则将前缀添加到
`default`，因此示例中的键是 `rspec-default`。
####`缓存：未跟踪`
设置 `untracked: true` 以缓存 Git 中未跟踪的所有文件
存储库：
```yaml
规格：
脚本：测试
缓存：
未追踪：真实
``
缓存所有 Git 未跟踪文件和 `binaries` 中的文件：
```yaml
规格：
脚本：测试
缓存：
未追踪：真实
路径：
- 二进制文件/
``
####`缓存：当`
> [介绍](https://gitlab.com/gitlab-org/gitlab/-/issues/18969) 在 GitLab 13.5 和 GitLab Runner v13.5.0 中。
`cache:when` 根据作业的状态定义何时保存缓存。你可以
将 `cache:when` 设置为：
- `on_success`（默认）：仅在作业成功时保存缓存。
- `on_failure`：仅在作业失败时保存缓存。
- `always`：始终保存缓存。
例如，无论作业是否成功，都要存储缓存：
```yaml
规格：
脚本：rspec
缓存：
路径：
- rspec/
什么时候：'总是'
``
####`缓存：策略`
缓存作业的默认行为是在开始时下载文件
执行，并在最后重新上传它们。任何更改
作业将保留以供将来运行。这种行为被称为`pull-push`缓存
政策。
如果您知道该作业不会更改缓存文件，则可以跳过上传步骤
通过在作业规范中设置`policy: pull`。可以添加普通缓存
作业在较早的阶段以确保缓存不时更新：
```yaml
阶段：
- 设置
- 测试
准备：
阶段：设置
缓存：
关键：宝石
路径：
- 供应商/捆绑
脚本：
- 捆绑安装 --deployment
规格：
阶段：测试
缓存：
关键：宝石
路径：
- 供应商/捆绑
政策：拉
脚本：
- 捆绑执行 rspec ...
``
当您有许多使用缓存并行执行的作业时，请使用 `pull` 策略。这
策略加速作业执行并减少缓存服务器上的负载。
如果您的作业无条件地重新创建缓存
参考之前的内容，可以跳过下载步骤。
为此，请将 `policy: push` 添加到作业中。
###`神器`
使用 `artifacts` 指定文件和目录列表
当它[成功、失败或总是](#artifactswhen) 时附加到作业。
作业完成后，工件将发送到 GitLab。他们是
如果大小不合适，可以在 GitLab UI 中下载
大于 [最大工件大小](../../user/gitlab_com/index.md#gitlab-cicd)。
默认情况下，后期的作业会自动下载所有创建的工件
通过早期阶段的工作。您可以使用以下命令控制作业中的工件下载行为
[`dependencies`](#dependencies)。
使用 [`needs`](#artifact-downloads-with-needs) 关键字时，作业只能下载
来自在 `needs` 配置中定义的作业的工件。
默认情况下，仅为成功的作业收集作业工件，并且
在 [caches](#cache) 之后恢复工件。
[阅读有关工件的更多信息](../pipelines/job_artifacts.md)。
####`依赖关系`
默认情况下，前一阶段的所有“工件”
传递给每个作业。但是，您可以使用 `dependencies` 关键字来
定义要从中获取工件的有限作业列表。您还可以设置一个作业来完全不下载任何工件。
要使用此功能，请在作业上下文中定义 `dependencies` 并通过
应从中下载工件的所有先前作业的列表。
您可以从在当前阶段之前执行的阶段定义作业。
如果您从当前或即将到来的阶段定义作业，则会发生错误。
要防止作业下载工件，请定义一个空数组。
当你使用 `dependencies` 时，不会考虑上一个作业的状态。
如果作业失败或者是未触发的手动作业，则不会发生错误。
以下示例定义了两个带有工件的作业：`build:osx` 和
`构建：linux`。当 `test:osx` 执行时，`build:osx` 中的工件
在构建的上下文中下载和提取。同样的事情发生
用于 `test:linux` 和来自 `build:linux` 的工件。
作业 `deploy` 下载所有先前作业的工件，因为
[stage](#stages) 优先级：
```yaml
构建：OSX：
阶段：构建
脚本：make build:osx
文物：
路径：
- 二进制文件/
构建：Linux：
阶段：构建
脚本：make build：linux
文物：
路径：
- 二进制文件/
测试：OSX：
阶段：测试
脚本：进行测试：osx
依赖：
- 构建：OSX
测试：Linux：
阶段：测试
脚本：进行测试：linux
依赖：
- 构建：linux
部署：
阶段：部署
脚本：进行部署
``
##### 依赖作业失败时
> 在 GitLab 10.3 中引入。
如果设置为依赖项的作业工件是
[过期](#artifactsexpire_in) 或
[删除](../pipelines/job_artifacts.md#delete-job-artifacts)，然后
依赖作业失败。
####`工件：排除`
> - [介绍](https://gitlab.com/gitlab-org/gitlab/-/issues/15122) 在 GitLab 13.1
> - 需要 GitLab Runner 13.1
`exclude` 可以防止将文件添加到工件中
档案。
类似于 [`artifacts:paths`](#artifactspaths)，`exclude` 路径是相对的
到项目目录。您可以使用通配符
[glob](https://en.wikipedia.org/wiki/Glob_(programming)) 或
[`doublestar.PathMatch`](https://pkg.go.dev/github.com/bmatcuk/doublestar@v1.2.2?tab=doc#PathMatch) 模式。
例如，要将所有文件存储在 `binaries/` 中，而不是将 `*.o` 文件存储在
`binaries/` 的子目录：
```yaml
文物：
路径：
- 二进制文件/
排除：
- 二进制文件/**/*.o
``
与 [`artifacts:paths`](#artifactspaths) 不同，`exclude` 路径不是递归的。要排除目录的所有内容，您可以显式匹配它们而不是匹配目录本身。
例如，要将所有文件存储在 `binaries/` 中，但没有位于 `temp/` 子目录中：
```yaml
文物：
路径：
- 二进制文件/
排除：
- 二进制文件/临时文件/**/*
``
与 [`artifacts:untracked`](#artifactsuntracked) 匹配的文件可以使用
`artifacts:exclude` 也是。
####`artifacts:expire_in`
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16267) 在 GitLab 13.0 中的禁用功能标志后面，无论到期时间如何，都会保留最新的作业工件。
> - [在 GitLab 13.4 中设置默认行为](https://gitlab.com/gitlab-org/gitlab/-/issues/229936)。
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/241026) 在 GitLab 13.8 中，可以在项目级别禁用保持最新的工作工件。
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/276583) 在 GitLab 13.9 中，可以在实例范围内禁用保持最新的作业工件。
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/321323) 在 GitLab 13.12 中，无论过期时间如何，都会保留最新的管道工件。
使用 `expire_in` 指定 [job artifacts](../pipelines/job_artifacts.md) 之前存储多长时间
它们过期并被删除。`expire_in` 设置不会影响：
- 来自最新工作的工件，除非保留最新的工作工件是：
- [在项目级别禁用](../pipelines/job_artifacts.md#keep-artifacts-from-most-recent-successful-jobs)。
- [禁用实例范围](../../user/admin_area/settings/continuous_integration.md#keep-the-latest-artifacts-for-all-jobs-in-the-latest-successful-pipelines)。
- [管道工件](../pipelines/pipeline_artifacts.md)。无法指定一个
这些的到期日期：
- 来自最新管道的管道工件将永远保留。
- 一周后删除其他管道工件。
`expire_in` 的值是以秒为单位的经过时间，除非提供了单位。有效值
包括：
- `'42'`
- `42 秒`
- `3 分 4 秒`
- `2 小时 20 分钟`
- `2h20min`
- `6 月 1 天`
- `47 岁 6 mos 和 4d`
- `3 周零 2 天`
-`从不`
要在上传后一周使工件过期：
```yaml
工作：
文物：
expire_in: 1 周
``
当工件上传并存储在 GitLab 上时，到期时间段开始。如果到期
时间未定义，默认为
[实例范围设置](../../user/admin_area/settings/continuous_integration.md#default-artifacts-expiration)
（默认 30 天）。
要覆盖到期日期并保护工件不被自动删除：
- 使用职位页面上的**保留**按钮。
- [在 GitLab 13.3 及更高版本中](https://gitlab.com/gitlab-org/gitlab/-/issues/22761)，设置值
`expire_in` 到 `never`。
过期后，工件默认每小时删除一次（使用 cron 作业），并且不会
可以访问了。
####`工件：expose_as`
> [介绍](https://gitlab.com/gitlab-org/gitlab/-/issues/15018) 在 GitLab 12.5 中。
使用 `expose_as` 关键字公开 [job artifacts](../pipelines/job_artifacts.md)
在 [合并请求](../../user/project/merge_requests/index.md) UI 中。
例如，要匹配单个文件：
```yaml
测试：
脚本：[“回声‘测试’> file.txt”]
文物：
暴露_作为：'工件1'
路径：['file.txt']
``
有了这个配置，GitLab 添加了一个链接 **artifact 1** 到相关的合并请求
指向`file1.txt`。要访问链接，请选择**查看暴露的工件**
在合并请求概述中的管道图下方。
匹配整个目录的示例：
```yaml
测试：
脚本：["mkdir test && echo 'test' > test/file.txt"]
文物：
暴露_作为：'工件1'
路径：['测试/']
``
请注意以下事项：
- 使用变量定义`artifacts:paths` 时，不会在合并请求 UI 中显示工件。
- 每个合并请求最多可以公开 10 个作业工件。
- 不支持全局模式。
- 如果指定了目录，则链接到作业 [工件浏览器](../pipelines/job_artifacts.md#download-job-artifacts) 如果超过
目录中的一个文件。
- 对于带有`.html`、`.htm`、`.txt`、`.json`、`.xml`、
和 `.log` 扩展名，如果 [GitLab Pages](../../administration/pages/index.md) 是：
- 启用，GitLab 自动呈现工件。
- 未启用，文件显示在工件浏览器中。
####`工件：名称`
使用 `name` 指令定义创建的工件的名称
档案。您可以为每个存档指定唯一的名称。`artifacts:name`
变量可以使用任何[预定义变量](../variables/README.md)。
默认名称是`artifacts`，下载后会变成`artifacts.zip`。
要使用当前作业的名称创建存档：
```yaml
工作：
文物：
名称：“$CI_JOB_NAME”
路径：
- 二进制文件/
``
使用当前分支或标记的名称创建存档，仅包括
二进制文件目录：
```yaml
工作：
文物：
名称：“$CI_COMMIT_REF_NAME”
路径：
- 二进制文件/
``
如果您的分支名称包含正斜杠
（例如`feature/my-feature`）建议使用`$CI_COMMIT_REF_SLUG`
而不是`$CI_COMMIT_REF_NAME` 来正确命名工件。
使用当前作业和当前分支的名称创建存档或
标记仅包含二进制文件目录：
```yaml
工作：
文物：
名称：“$CI_JOB_NAME-$CI_COMMIT_REF_NAME”
路径：
- 二进制文件/
``
要使用当前 [stage](#stages) 和分支名称的名称创建存档：
```yaml
工作：
文物：
名称：“$CI_JOB_STAGE-$CI_COMMIT_REF_NAME”
路径：
- 二进制文件/
``
---
如果您使用 **Windows Batch** 运行您的 shell 脚本，则需要替换
`$` 和 `%`：
```yaml
工作：
文物：
名称：“%CI_JOB_STAGE%-%CI_COMMIT_REF_NAME%”
路径：
- 二进制文件/
``
如果您使用 **Windows PowerShell** 运行您的 shell 脚本，则需要替换
`$` 和 `$env:`：
```yaml
工作：
文物：
名称：“$env:CI_JOB_STAGE-$env:CI_COMMIT_REF_NAME”
路径：
- 二进制文件/
``
####`工件：路径`
路径是相对于项目目录（`$CI_PROJECT_DIR`），不能直接
它外面的链接。您可以使用使用 [glob](https://en.wikipedia.org/wiki/Glob_(programming)) 的通配符
模式和：
- 在 [GitLab Runner 13.0](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/2620) 及更高版本中，
[`doublestar.Glob`](https://pkg.go.dev/github.com/bmatcuk/doublestar@v1.2.2?tab=doc#Match)。
- 在 GitLab Runner 12.10 及更早版本中，
[`filepath.Match`](https://pkg.go.dev/path/filepath#Match)。
要限制特定作业从哪些作业获取工件，请参阅 [dependencies](#dependencies)。
发送 `binaries` 和 `.config` 中的所有文件：
```yaml
文物：
路径：
- 二进制文件/
- .config
``
要禁用工件传递，请使用空 [dependencies](#dependencies) 定义作业：
```yaml
工作：
阶段：构建
脚本：进行构建
依赖项：[]
``
您可能只想为标记的发布创建工件以避免填充
使用临时构建工件构建服务器存储。
仅为标签创建工件（`default-job` 不创建工件）：
```yaml
默认作业：
脚本：
- mvn 测试 -U
除了：
- 标签
发布工作：
脚本：
- mvn 包 -U
文物：
路径：
- 目标/*.war
只要：
- 标签
``
您也可以对目录使用通配符。例如，如果您想获取以 `xyz` 结尾的目录中的所有文件：
```yaml
工作：
文物：
路径：
- 路径/*xyz/*
``
####`工件：公共`
> - [介绍](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49775) 在 GitLab 13.8
> - 它[部署在功能标志后面](../../user/feature_flags.md)，默认情况下禁用。
> - 它已在 GitLab.com 上启用。
> - 推荐用于生产。
使用 `artifacts:public` 来确定作业工件是否应该
公开可用。
`artifacts:public` 的默认值为 `true`，这意味着
匿名和访客用户可以下载公共管道：
```yaml
文物：
公众：真实
``
拒绝匿名用户和访客用户对公共工件的读取访问
管道，将 `artifacts:public` 设置为 `false`：
```yaml
文物：
公众：假
``
####`工件：报告`
> - [介绍](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/20390) 在 GitLab 11.2 中。
> - 需要 GitLab Runner 11.2 及更高版本。
使用 [`artifacts:reports`](#artifactsreports)
从作业中收集测试报告、代码质量报告和安全报告。
它还在 GitLab UI 中公开这些报告（合并请求、管道视图和安全仪表板）。
无论作业结果如何（成功或失败），都会收集测试报告。
您可以使用 [`artifacts:expire_in`](#artifactsexpire_in) 来设置过期时间
他们的文物的日期。
如果您还希望能够浏览报告输出文件，请包括
[`artifacts:paths`](#artifactspaths) 关键字。
##### `artifacts:reports:api_fuzzing` **（终极）**
> - 在 GitLab 13.4 中引入。
> - 需要 GitLab Runner 13.4 或更高版本。
`api_fuzzing` 报告收集了 [API Fuzzing bug](../../user/application_security/api_fuzzing/index.md)
作为文物。
收集的 API Fuzzing 报告作为工件上传到 GitLab 并在合并中汇总
请求和管道视图。它还用于为安全仪表板提供数据。
#####`artifacts:reports:cobertura`
> - [介绍](https://gitlab.com/gitlab-org/gitlab/-/issues/3708) 在 GitLab 12.9 中。
> - 需要 [GitLab Runner](https://docs.gitlab.com/runner/) 11.5 及更高版本。
`cobertura` 报告收集 [Cobertura 覆盖 XML 文件](../../user/project/merge_requests/test_coverage_visualization.md)。
收集的 Cobertura 覆盖率报告作为工件上传到 GitLab
并显示在合并请求中。
Cobertura 最初是为 Java 开发的，但也有很多
其他语言（如 JavaScript、Python、Ruby 等）的第三方端口。
##### `artifacts:reports:codequality`
> - 在 GitLab 11.5 中引入。
> - [移动](https://gitlab.com/gitlab-org/gitlab/-/issues/212499) 在 13.2 中免费使用 GitLab。
> - 需要 GitLab Runner 11.5 及更高版本。
`codequality` 报告收集[代码质量问题](../../user/project/merge_requests/code_quality.md)
作为文物。
收集的代码质量报告作为工件上传到 GitLab，并在合并请求中汇总。
##### `artifacts:reports:container_scanning` **（终极）**
> - 在 GitLab 11.5 中引入。
> - 需要 GitLab Runner 11.5 及更高版本。
`container_scanning` 报告收集[容器扫描漏洞](../../user/application_security/container_scanning/index.md)
作为文物。
收集到的容器扫描报告作为工件上传到 GitLab
汇总在合并请求和管道视图中。它还用于提供数据以确保安全
仪表板。
##### `artifacts:reports:coverage_fuzzing` **（终极）**
> - 在 GitLab 13.4 中引入。
> - 需要 GitLab Runner 13.4 或更高版本。
`coverage_fuzzing` 报告收集 [coverage fuzzing bug](../../user/application_security/coverage_fuzzing/index.md)
作为文物。
收集到的覆盖模糊报告作为工件上传到 GitLab 并在合并中汇总
请求和管道视图。它还用于为安全仪表板提供数据。
##### `artifacts:reports:dast` **（终极）**
> - 在 GitLab 11.5 中引入。
> - 需要 GitLab Runner 11.5 及更高版本。
`dast` 报告收集 [DAST 漏洞](../../user/application_security/dast/index.md)
作为文物。
收集的 DAST 报告作为工件上传到 GitLab，并在合并请求和管道视图中汇总。它还用于提供数据以确保安全
仪表板。
##### `artifacts:reports:dependency_scanning` **（终极）**
> - 在 GitLab 11.5 中引入。
> - 需要 GitLab Runner 11.5 及更高版本。
`dependency_scanning` 报告收集[依赖扫描漏洞](../../user/application_security/dependency_scanning/index.md)
作为文物。
收集到的依赖扫描报告作为工件上传到 GitLab，并在合并请求和管道视图中汇总。它还用于提供数据以确保安全
仪表板。
##### `artifacts:reports:dotenv`
> - [介绍](https://gitlab.com/gitlab-org/gitlab/-/issues/17066) 在 GitLab 12.9 中。
> - 需要 GitLab Runner 11.5 及更高版本。
`dotenv` 报告收集一组环境变量作为工件。
收集的变量被注册为作业的运行时创建的变量，
这对于[在作业完成后设置动态环境 URL](../environments/index.md#set-dynamic-environment-urls-after-a-job-finishes) 很有用。
[原始 dotenv 规则](https://github.com/motdotla/dotenv#rules) 有几个例外：
- 变量键只能包含字母、数字和下划线 (`_`)。
- `.env` 文件的最大大小为 5 KB。
- 在 GitLab 13.5 及更早版本中，最大继承变量数为 10。
- 在 [GitLab 13.6 及更高版本](https://gitlab.com/gitlab-org/gitlab/-/issues/247913) 中，
最大继承变量数为 20。
- 不支持`.env` 文件中的变量替换。
- `.env` 文件不能有空行或注释（以 `#` 开头）。
- `env` 文件中的键值不能有空格或换行符 (`\n`)，包括使用单引号或双引号时。
- 不支持在解析过程中引用转义 (`key = 'value'` -> `{key: "value"}`)。
#####`artifacts:reports:junit`
> - [介绍](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/20390) 在 GitLab 11.2 中。
> - 需要 GitLab Runner 11.2 及更高版本。
`junit` 报告收集[JUnit 报告格式 XML 文件](https://www.ibm.com/support/knowledgecenter/en/SSQ2R2_14.1.0/com.ibm.rsar.analysis.codereview.cobol.doc/topics/ cac_useresults_junit.html)
作为文物。虽然 JUnit 最初是用 Java 开发的，但有很多
第三方端口用于其他
JavaScript、Python、Ruby 等语言。
有关更多详细信息和示例，请参阅 [单元测试报告](../unit_test_reports.md)。
下面是从 Ruby 的 RSpec 测试工具收集 JUnit 报告格式 XML 文件的示例：
```yaml
规格：
阶段：测试
脚本：
- 捆绑安装
- rspec --format RspecJunitFormatter --out rspec.xml
文物：
报告：
junit：rspec.xml
``
收集到的单元测试报告作为工件上传到 GitLab 并显示在合并请求中。
如果您使用的 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_management` **（终极）**
> - 在 GitLab 11.5 中引入。
> - 需要 GitLab Runner 11.5 及更高版本。
警告：
此工件仍然有效，但**已弃用**以支持
[artifacts:reports:license_scanning](#artifactsreportslicense_scanning)
在 GitLab 12.8 中引入。
`license_management` 报告收集 [Licenses](../../user/compliance/license_compliance/index.md)
作为文物。
收集的许可证合规性报告作为工件上传到 GitLab，并在合并请求和管道视图中汇总。它还用于提供数据以确保安全
仪表板。
##### `artifacts:reports:license_scanning` **（终极）**
> - 在 GitLab 12.8 中引入。
> - 需要 GitLab Runner 11.5 及更高版本。
`license_scanning` 报告收集 [Licenses](../../user/compliance/license_compliance/index.md)
作为文物。
许可证合规性报告作为工件上传到 GitLab 并自动显示在合并请求和管道视图中，并提供安全数据
仪表板。
##### `artifacts:reports:load_performance` **(PREMIUM)**
> - 在 [GitLab 13.2](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/35260) 中引入 [GitLab Premium](https://about.gitlab.com/pricing/) 13.2。
> - 需要 GitLab Runner 11.5 及更高版本。
`load_performance` 报告收集 [负载性能测试指标](../../user/project/merge_requests/load_performance_testing.md)
作为文物。
该报告作为工件上传到 GitLab，并且
自动显示在合并请求中。
##### `artifacts:reports:metrics` **(PREMIUM)**
> 在 GitLab 11.10 中引入。
`metrics` 报告收集 [Metrics](../metrics_reports.md)
作为文物。
收集的指标报告作为工件上传到 GitLab 并显示在合并请求中。
##### `artifacts:reports:performance` **(PREMIUM)**
> - 在 GitLab 11.5 中引入。
> - 需要 GitLab Runner 11.5 及更高版本。
`performance` 报告收集 [浏览器性能测试指标](../../user/project/merge_requests/browser_performance_testing.md)
作为文物。
收集的浏览器性能报告作为工件上传到 GitLab 并显示在合并请求中。
##### `artifacts:reports:requirements` **（终极）**
> - [介绍](https://gitlab.com/groups/gitlab-org/-/epics/2859) 在 GitLab 13.1 中。
> - 需要 GitLab Runner 11.5 及更高版本。
`requirements` 报告收集 `requirements.json` 文件作为工件。
收集到的需求报告作为工件上传到 GitLab
现有的 [需求](../../user/project/requirements/index.md) 是
标记为满意。
#####`artifacts:reports:sast`
> - 在 GitLab 11.5 中引入。
> - 在 GitLab 13.3 中[在所有层级可用](https://gitlab.com/groups/gitlab-org/-/epics/2098)。
> - 需要 GitLab Runner 11.5 及更高版本。
`sast` 报告收集 [SAST 漏洞](../../user/application_security/sast/index.md)
作为文物。
收集到的 SAST 报告作为工件上传到 GitLab 并进行汇总
在合并请求和管道视图中。它还用于提供数据以确保安全
仪表板。
#####`artifacts:reports:secret_detection`
> - 在 GitLab 13.1 中引入。
> - 在 GitLab 中[在所有层级可用](https://gitlab.com/gitlab-org/gitlab/-/issues/222788)
13.3.
> - 需要 GitLab Runner 11.5 及更高版本。
`secret-detection` 报告收集 [检测到的机密](../../user/application_security/secret_detection/index.md)
作为文物。
收集到的 Secret Detection 报告作为工件上传到 GitLab 并汇总
在合并请求和管道视图中。它还用于提供数据以确保安全
仪表板。
##### `artifacts:reports:terraform`
> - [介绍](https://gitlab.com/gitlab-org/gitlab/-/issues/207528) 在 GitLab 13.0 中。
> - 需要 [GitLab Runner](https://docs.gitlab.com/runner/) 11.5 及更高版本。
`terraform` 报告获取 Terraform `tfplan.json` 文件。[删除凭据所需的 JQ 处理](../../user/infrastructure/mr_integration.md#setup)。收集到的地形
计划报告作为工件上传到 GitLab 并显示
在合并请求中。有关更多信息，请参阅
[将 `terraform plan` 信息输出到合并请求中](../../user/infrastructure/mr_integration.md)。
#### `artifacts:untracked`
使用 `artifacts:untracked` 将所有 Git 未跟踪文件添加为工件（以及
使用 `artifacts:paths` 中定义的路径）。`artifacts:untracked` 忽略配置
在存储库的`.gitignore` 文件中。
发送所有 Git 未跟踪文件：
```yaml
文物：
未追踪：真实
``
发送所有 Git 未跟踪文件和“二进制文件”中的文件：
```yaml
文物：
未追踪：真实
路径：
- 二进制文件/
``
发送所有未跟踪的文件，但 [排除](#artifactsexclude) `*.txt`：
```yaml
文物：
未追踪：真实
排除：
- “*。文本文件”
``
####`工件：何时`
使用 `artifacts:when` 在作业失败时上传工件或尽管
失败。
`artifacts:when` 可以设置为以下值之一：
1. `on_success`（默认）：仅在作业成功时上传工件。
1. `on_failure`：仅在作业失败时上传工件。
1. `always`：始终上传工件。很有用，例如，当
[上传工件](../unit_test_reports.md#viewing-junit-screenshots-on-gitlab) 需要
对失败的测试进行故障排除。
例如，仅在作业失败时上传工件：
```yaml
工作：
文物：
时间：on_failure
``
###`覆盖范围`
使用 `coverage` 配置如何从
作业输出。
正则表达式是此处预期的唯一有效值。所以，使用
围绕 `/` 是强制性的，以一致且明确地表示
一个正则表达式字符串。如果你想，你必须转义特殊字符
从字面上匹配它们。
例如：
```yaml
工作1：
脚本：rspec
覆盖率：'/代码覆盖率：\d+\.\d+/'
``
如果作业输出中至少有一行与正则表达式匹配，则覆盖率会显示在 UI 中。
如果作业输出中有多个匹配的行，则使用最后一行。
对于匹配的行，第一次出现 `\d+(\.\d+)?` 是代码覆盖率。
前导零被删除。
[子管道](../parent_child_pipelines.md) 的覆盖率输出未记录
或显示。检查[相关问题](https://gitlab.com/gitlab-org/gitlab/-/issues/280818)
更多细节。
###`重试`
> [介绍](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/3515) 在 GitLab 11.5 中，您可以控制重试哪些故障。
使用 `retry` 配置一个作业的重试次数
失败的情况。
当一个作业失败时，该作业被重新处理，
直到达到由 `retry` 关键字指定的限制。
如果 `retry` 设置为 `2`，并且作业在第二次运行（第一次重试）中成功，则不会重试。
`retry` 值必须是一个正整数，从 `0` 到 `2`
（最多重试两次，总共运行三次）。
以下示例重试所有失败情况：
```yaml
测试：
脚本：rspec
重试：2
``
默认情况下，在所有失败情况下都会重试作业。为了更好地控制
对于重试失败，“重试”可以是具有以下键的散列：
- `max`：最大重试次数。
- `when`：要重试的失败案例。
仅重试运行器系统故障最多两次：
```yaml
测试：
脚本：rspec
重试：
最大：2
时间：runner_system_failure
``
如果除了流道系统故障之外还有其他故障，作业
不重试。
要重试多个失败案例，`when` 也可以是一个失败数组：
```yaml
测试：
脚本：rspec
重试：
最大：2
什么时候：
- runner_system_failure
- 卡住_or_timeout_failure
``
`when` 的可能值为：
<!--
如果您更改以下任何值，请确保更新 `RETRY_WHEN_IN_DOCUMENTATION`
`spec/lib/gitlab/ci/config/entry/retry_spec.rb` 中的数组。
那里的测试确保所有记录在案
值作为配置选项有效，因此应始终
与本文档保持同步。
-->
- `always`：在任何失败时重试（默认）。
- `unknown_failure`：失败原因未知时重试。
- `script_failure`：脚本失败时重试。
- `api_failure`：API 失败时重试。
- `stuck_or_timeout_failure`：当作业卡住或超时时重试。
- `runner_system_failure`：如果存在运行器系统故障（例如，作业设置失败），则重试。
- `missing_dependency_failure`：如果缺少依赖项，请重试。
- `runner_unsupported`：如果跑步者不受支持，则重试。
- `stale_schedule`：如果无法执行延迟的作业，请重试。
- `job_execution_timeout`：如果脚本超过为作业设置的最大执行时间，则重试。
- `archived_failure`：如果作业已存档且无法运行，请重试。
- `unmet_prerequisites`：如果作业未能完成先决任务，则重试。
- `scheduler_failure`：如果调度程序未能将作业分配给运行程序，则重试。
- `data_integrity_failure`：如果检测到结构完整性问题，请重试。
您可以使用变量指定[特定作业执行阶段的重试次数](../runners/README.md#job-stages-attempts)。
###`超时`
> [介绍](https://gitlab.com/gitlab-org/gitlab/-/issues/14887) 在 GitLab 12.3 中。
使用 `timeout` 为特定作业配置超时。例如：
```yaml
建造：
脚本：build.sh
超时：3小时30分钟
测试：
脚本：rspec
超时时间：3h 30m
``
作业级超时可以超过
[项目级超时](../pipelines/settings.md#timeout) 但不能
超过跑步者特定的超时时间。
###`平行`
> [介绍](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/21480) 在 GitLab 11.5 中。
使用 `parallel` 配置要并行运行的作业实例的数量。
该值可以是 2 到 50。
`parallel` 关键字创建并行运行的同一作业的 N 个实例。
它们的命名顺序是从 `job_name 1/N` 到 `job_name N/N`：
```yaml
测试：
脚本：rspec
平行：5
``
每个并行作业都有一个“CI_NODE_INDEX”和“CI_NODE_TOTAL”
[预定义 CI/CD 变量](../variables/README.md#predefined-cicd-variables) 设置。
不同的语言和测试套件有不同的方法来实现并行化。
例如，使用 [Semaphore Test Boosters](https://github.com/renderedtext/test-boosters)
和 RSpec 并行运行 Ruby 测试：
```红宝石
# 宝石文件
来源“https://rubygems.org”
宝石'rspec'
gem 'semaphore_test_boosters'
``
```yaml
测试：
并行：3
脚本：
- 捆
- 捆绑执行 rspec_booster --job $CI_NODE_INDEX/$CI_NODE_TOTAL
``
警告：
Test Boosters 向作者报告使用统计数据。
然后，您可以导航到新管道构建的 **Jobs** 选项卡并查看您的 RSpec
工作分为三个独立的工作。
#### 并行`矩阵`作业
> - [介绍](https://gitlab.com/gitlab-org/gitlab/-/issues/15356) 在 GitLab 13.3 中。
使用 `matrix:` 在单个管道中并行运行作业多次，
但每个作业实例都有不同的变量值。
可以有 2 到 50 个工作岗位。
作业只有在有多个跑步者或单个跑步者时才能并行运行
[配置为同时运行多个作业](#use-your-own-runners)。
每个作业都获得相同的 `CI_NODE_TOTAL` [CI/CD 变量](../variables/README.md#predefined-cicd-variables) 值和唯一的 `CI_NODE_INDEX` 值。
```yaml
部署堆栈：
阶段：部署
脚本：
- 垃圾箱/部署
平行：
矩阵：
- 供应商：aws
堆：
- 监控
- 应用程序1
- 应用程序2
- 提供者：ovh
堆栈：[监控、备份、应用程序]
- 提供者：[gcp，vultr]
堆栈：[数据，处理]
``
以下示例生成 10 个并行的 `deploystacks` 作业，每个作业具有不同的值
对于 `PROVIDER` 和 `STACK`：
```明文
deploystacks：[aws，监控]
部署堆栈：[aws，app1]
部署堆栈：[aws，app2]
deploystacks: [ovh, 监控]
部署堆栈：[ovh，备份]
部署堆栈：[ovh，应用程序]
部署堆栈：[gcp，数据]
部署堆栈：[gcp，处理]
部署堆栈：[vultr，数据]
部署堆栈：[vultr，处理]
``
作业命名风格[在 GitLab 13.4 中改进](https://gitlab.com/gitlab-org/gitlab/-/issues/230452)。
#####一维`矩阵`作业
> [介绍](https://gitlab.com/gitlab-org/gitlab/-/issues/26362) 在 GitLab 13.5 中。
您还可以在单个作业中使用一维矩阵：
```yaml
部署堆栈：
阶段：部署
脚本：
- 垃圾箱/部署
平行：
矩阵：
- 提供商：[aws、ovh、gcp、vultr]
``
##### 并行`matrix` 触发作业
> [介绍](https://gitlab.com/gitlab-org/gitlab/-/issues/270957) 在 GitLab 13.10 中。
使用 `matrix:` 在单个管道中多次并行运行 [trigger](#trigger) 作业，
但每个作业实例都有不同的变量值。
```yaml
部署堆栈：
阶段：部署
扳机：
包括：path/to/child-pipeline.yml
平行：
矩阵：
- 供应商：aws
堆栈：[监控，app1]
- 提供者：ovh
堆栈：[监控、备份]
- 提供者：[gcp，vultr]
堆栈：[数据]
``
此示例生成 6 个并行的 `deploystacks` 触发器作业，每个作业具有不同的值
对于 `PROVIDER` 和 `STACK`，它们使用这些变量创建了 6 个不同的子管道。
```明文
deploystacks：[aws，监控]
部署堆栈：[aws，app1]
deploystacks: [ovh, 监控]
部署堆栈：[ovh，备份]
部署堆栈：[gcp，数据]
部署堆栈：[vultr，数据]
``
###`触发器`
> - [介绍](https://gitlab.com/gitlab-org/gitlab/-/issues/8997) 在 [GitLab Premium](https://about.gitlab.com/pricing/) 11.8。
> - [移动](https://gitlab.com/gitlab-org/gitlab/-/issues/199224) 在 12.8 中免费使用 GitLab。
使用 `trigger` 定义下游管道触发器。当 GitLab 开始一个 `trigger` 作业时，
创建下游管道。
带有`trigger` 的作业只能使用[有限的关键字集](../multi_project_pipelines.md#limitations)。
例如，你不能用 [`script`](#script), [`before_script`](#before_script),
或 [`after_script`](#after_script)。
您可以使用此关键字创建两种不同类型的下游管道：
- [多项目管道](../multi_project_pipelines.md#creating-multi-project-pipelines-from-gitlab-ciyml)
- [子管道](../parent_child_pipelines.md)
[在 GitLab 13.2](https://gitlab.com/gitlab-org/gitlab/-/issues/197140/) 及更高版本，您可以
查看哪个作业触发了下游管道。在[管道图](../pipelines/index.md#visualize-pipelines)中，
将鼠标悬停在下游管道作业上。
在 [GitLab 13.5](https://gitlab.com/gitlab-org/gitlab/-/issues/201938) 及更高版本中，您
可以在与 `trigger` 相同的作业中使用 [`when:manual`](#whenmanual)。在 GitLab 13.4 和
早些时候，将它们一起使用会导致错误 `jobs:#{job-name} when should be on_success, on_failure or always`。
您[无法使用 API 启动`手动`触发器作业](https://gitlab.com/gitlab-org/gitlab/-/issues/284086)。
#### 多项目管道的基本`trigger` 语法
您可以使用 `trigger` 关键字配置下游触发器
下游项目的完整路径：
```yaml
规格：
阶段：测试
脚本：bundle exec rspec
分期：
阶段：部署
触发器：我的/部署
``
#### 多项目管道的复杂`trigger` 语法
你可以配置一个 GitLab 用来创建的分支名称
具有以下功能的下游管道：
```yaml
规格：
阶段：测试
脚本：bundle exec rspec
分期：
阶段：部署
扳机：
项目：我的/部署
分支：稳定
``
要从触发的管道镜像状态：
```yaml
trigger_job:
扳机：
项目：我的/项目
策略：依赖
``
要从上游管道镜像状态：
```yaml
上游桥：
阶段：测试
需要：
管道：其他/项目
``
#### 子管道的`trigger` 语法
> [介绍](https://gitlab.com/gitlab-org/gitlab/-/issues/16094) 在 GitLab 12.7 中。
要创建 [子管道](../parent_child_pipelines.md)，请指定路径
包含子管道配置的 YAML 文件：
```yaml
trigger_job:
扳机：
包括：path/to/child-pipeline.yml
``
类似于[多项目管道](../multi_project_pipelines.md#mirroring-status-from-triggered-pipeline)，
可以从触发的管道中镜像状态：
```yaml
trigger_job:
扳机：
包括：
- 本地：path/to/child-pipeline.yml
策略：依赖
``
##### 使用生成的配置文件触发子管道
> [介绍](https://gitlab.com/gitlab-org/gitlab/-/issues/35632) 在 GitLab 12.9 中。
您还可以从 [动态生成的配置文件](../parent_child_pipelines.md#dynamic-child-pipelines) 触发子管道：
```yaml
生成配置：
阶段：构建
脚本：生成-ci-config > 生成-config.yml
文物：
路径：
- 生成的 config.yml
子管道：
阶段：测试
扳机：
包括：
- 工件：生成的 config.yml
工作：生成配置
``
`generated-config.yml` 从工件中提取并用作配置
用于触发子管道。
##### 使用来自另一个项目的文件触发子管道
> [介绍](https://gitlab.com/gitlab-org/gitlab/-/issues/205157) 在 GitLab 13.5 中。
使用来自同一私有项目的文件触发子管道
GitLab 实例，使用 [`include:file`](#includefile)：
```yaml
子管道：
扳机：
包括：
- 项目：'我的组/我的管道库'
参考：'主要'
文件：'/path/to/child-pipeline.yml'
``
#### 使用 `trigger:strategy` 链接管道
默认情况下，`trigger` 作业以 `success` 状态完成
一旦创建了下游管道。
要强制 `trigger` 作业等待下游（多项目或子）管道完成，请使用
`策略：依赖`。此设置使触发作业以“正在运行”状态等待，直到触发
管道完成。此时，`trigger` 作业完成并显示与
下游作业。
此设置有助于保持管道执行的线性。在以下示例中，作业来自
后续阶段等待触发的管道成功完成之前
开始，这减少了并行化。
```yaml
trigger_job:
扳机：
包括：path/to/child-pipeline.yml
策略：依赖
``
#### 通过 API 调用触发管道
要强制重建特定分支、标记或提交，您可以使用 API 调用
带有触发令牌。
触发标记不同于 [`trigger`](#trigger) 关键字。
[在触发器文档中阅读更多内容。](../triggers/README.md)
###`可中断`
> [介绍](https://gitlab.com/gitlab-org/gitlab/-/issues/32022) 在 GitLab 12.3 中。
使用 `interruptible` 表示如果新的管道运行变得多余，则应取消正在运行的作业。
默认为`false`（不可中断）。尚未开始（待处理）的作业被认为是可中断的
并且可以安全取消。
此值仅在 [自动取消冗余管道功能](../pipelines/settings.md#auto-cancel-redundant-pipelines) 时使用
已启用。
启用后，如果以下任一情况为真，则在同一分支上启动新管道时会立即取消管道：
- 管道中的所有作业都设置为可中断的。
- 任何不间断的工作尚未开始。
将作业设置为可以在启动后安全取消的可中断作业（例如，构建作业）。
在以下示例中，新管道运行会导致现有运行管道变为：
- 取消，如果只有 `step-1` 正在运行或未决。
- 不会取消，一旦 `step-2` 开始运行。
不间断作业开始运行后，管道无法取消。
```yaml
阶段：
- 阶段1
- 阶段2
- 第三阶段
步骤1：
阶段：stage1
脚本：
- echo "可以取消。"
可中断：真
第2步：
阶段：阶段2
脚本：
- echo "不能取消。"
第 3 步：
阶段：stage3
脚本：
- echo "因为第 2 步不能取消，所以这一步永远不能取消，即使它被设置为可中断。"
可中断：真
``
###`resource_group`
> [介绍](https://gitlab.com/gitlab-org/gitlab/-/issues/15536) 在 GitLab 12.7 中。
有时在一个环境中同时运行多个作业或管道
可能会导致部署过程中出现错误。
为避免这些错误，请使用 `resource_group` 属性来确保
跑步者不会同时运行某些作业。资源组的行为相似
到其他编程语言中的信号量。
当在 `.gitlab-ci.yml` 文件中为作业定义了 `resource_group` 关键字时，
同一项目的不同管道中的作业执行是相互排斥的。
如果属于同一资源组的多个作业同时入队，
跑步者只选择其中一项工作。其他工作等到
`resource_group` 是免费的。
例如：
```yaml
部署到生产：
脚本：部署
资源组：生产
``
在这种情况下，两个独立管道中的两个“部署到生产”作业永远不能同时运行。因此，
您可以确保并发部署永远不会发生在生产环境中。
您可以为每个环境定义多个资源组。例如，
部署到物理设备时，您可能有多个物理设备。每台设备
可以部署到，但在任何给定时间每个设备只能有一个部署。
`resource_group` 值只能包含字母、数字、`-`、`_`、`/`、`$`、`{`、`}`、`.` 和空格。
它不能以`/`开头或结尾。
有关更多信息，请参阅 [部署安全](../environments/deployment_safety.md)。
#### 具有跨项目/父子管道的管道级并发控制
> [介绍](https://gitlab.com/gitlab-org/gitlab/-/issues/39057) 在 GitLab 13.9 中。
您可以为对并发敏感的下游管道定义`resource_group`
处决。[`trigger` 关键字](#trigger) 可以触发下游管道。这
[`resource_group` 关键字](#resource_group) 可以与它共存。这有助于控制
部署管道的并发性，同时运行非敏感作业。
以下示例在一个项目中有两个管道配置。当管道开始运行时，
非敏感作业首先执行，不受其他并发执行的影响
管道。但是，GitLab 确保之前没有其他部署管道在运行
触发部署（子）管道。如果其他部署管道正在运行，GitLab 等待
直到这些管道完成，然后再运行另一个。
```yaml
# .gitlab-ci.yml（父管道）
建造：
阶段：构建
脚本：回声“建筑...”
测试：
阶段：测试
脚本：回声“测试...”
部署：
阶段：部署
扳机：
包括：deploy.gitlab-ci.yml
策略：依赖
资源组：AWS 生产
``
```yaml
# deploy.gitlab-ci.yml（子管道）
阶段：
- 条款
- 部署
条款：
阶段：准备
脚本：回声“供应...”
部署：
阶段：部署
脚本：echo“正在部署...”
``
您必须定义 [`strategy:depend`](#linking-pipelines-with-triggerstrategy)
使用`trigger` 关键字。这确保在下游管道之前不会释放锁
完成。
###`发布`
> [介绍](https://gitlab.com/gitlab-org/gitlab/merge_requests/19298) 在 GitLab 13.2 中。
使用 `release` 创建一个 [release](../../user/project/releases/index.md)。
需要 [`release-cli`](https://gitlab.com/gitlab-org/release-cli/-/tree/master/docs)
在您的 GitLab Runner Docker 或 shell 执行器中可用。
支持这些关键字：
- [`tag_name`](#releasetag_name)
- [`描述`](#releasedescription)
- [`name`](#releasename)（可选）
- [`ref`](#releaseref)（可选）
- [`里程碑`](#releasemilestones)（可选）
- [`released_at`](#releasereleased_at)（可选）
- [`assets:links`](#releaseassetslinks)（可选）
仅当作业处理没有错误时才会创建发布。如果 Rails API
在发布创建期间返回错误，`release` 作业失败。
#### `release-cli` Docker 镜像
您必须指定用于 `release-cli` 的 Docker 镜像：
```yaml
图片：registry.gitlab.com/gitlab-org/release-cli:latest
``
#### shell 执行程序的`release-cli`
> [介绍](https://gitlab.com/gitlab-org/release-cli/-/issues/21) 在 GitLab 13.8 中。
对于 GitLab Runner shell 执行程序，您可以为您的 [支持的操作系统和架构] (https://release-cli-downloads.s3.amazonaws.com/latest/index.html) 手动下载并安装 `release-cli`。
安装后，您应该可以使用`release` 关键字。
**在 Unix/Linux 上安装**
1. 下载适用于您系统的二进制文件，以下示例适用于 amd64 系统：
```壳
curl --location --output /usr/local/bin/release-cli "https://release-cli-downloads.s3.amazonaws.com/latest/release-cli-linux-amd64"
``
1. 赋予其执行权限：
```壳
须藤 chmod +x /usr/local/bin/release-cli
``
1. 验证`release-cli` 是否可用：
```壳
$ release-cli -v
发布 cli 版本 0.6.0
``
**在 Windows PowerShell 上安装**
1. 在你系统的某处创建一个文件夹，例如`C:\GitLab\Release-CLI\bin`
```壳
New-Item -Path 'C:\GitLab\Release-CLI\bin' -ItemType 目录
``
1.下载可执行文件：
```壳
PS C:\> Invoke-WebRequest -Uri "https://release-cli-downloads.s3.amazonaws.com/latest/release-cli-windows-amd64.exe" -OutFile "C:\GitLab\Release-CLI \bin\release-cli.exe”
目录：C:\GitLab\Release-CLI
模式 LastWriteTime 长度 名称
---- ------------- ------ ----
d----- 3/16/2021 4:17 AM
``
1. 将目录添加到您的 `$env:PATH`：
```壳
$env:PATH += ";C:\GitLab\Release-CLI\bin"
``
1. 验证`release-cli` 是否可用：
```壳
PS C:\> release-cli -v
发布 cli 版本 0.6.0
``
#### 使用自定义 SSL CA 证书颁发机构
您可以使用 `ADDITIONAL_CA_CERT_BUNDLE` CI/CD 变量来配置自定义 SSL CA 证书颁发机构，
当`release-cli`使用带有自定义证书的HTTPS通过API创建发布时，它用于验证对等点。
`ADDITIONAL_CA_CERT_BUNDLE` 值应包含
[X.509 PEM 公钥证书的文本表示](https://tools.ietf.org/html/rfc7468#section-5.1)
或包含证书颁发机构的`path/to/file`。
例如，要在 `.gitlab-ci.yml` 文件中配置此值，请使用以下命令：
```yaml
释放：
变量：
ADDITIONAL_CA_CERT_BUNDLE: |
-----开始认证-----
MIIGqTCCBJGgAwIBAgIQI7AVxxVwg2kch4d56XNdDjANBgkqhkiG9w0BAQsFADCB
...
jWgmPqF3vUbZE0EySetPJquRFRKIesyJuBFMAs=
-----结束证书-----
脚本：
- 回声“创建发布”
释放：
名称：'我很棒的版本'
tag_name: '$CI_COMMIT_TAG'
``
`ADDITIONAL_CA_CERT_BUNDLE` 值也可以配置为
[UI 中的自定义变量](../variables/README.md#custom-cicd-variables),
要么作为一个`file`，它需要证书的路径，或者作为一个变量，
这需要证书的文本表示。
####`脚本`
除 [trigger](#trigger) 作业之外的所有作业都必须具有 `script` 关键字。一个`发布`
作业可以使用脚本命令的输出，但如果出现以下情况，您可以使用占位符脚本
不需要脚本：
```yaml
脚本：
- echo '发布工作'
``
[问题](https://gitlab.com/gitlab-org/gitlab/-/issues/223856) 存在以在即将发布的 GitLab 版本中删除此要求。
一个管道可以有多个“发布”作业，例如：
```yaml
ios-发布：
脚本：
- echo 'iOS 发布工作'
释放：
标签名称：v1.0.0-ios
描述：'iOS 发布 v1.0.0'
安卓发布：
脚本：
- echo 'Android 发布工作'
释放：
标签名称：v1.0.0-android
描述：'Android 发布 v1.0.0'
``
####`release:tag_name`
您必须为发布指定一个 `tag_name`。该标签可以引用现有的 Git 标签或
您可以指定一个新标签。
当存储库中不存在指定的标签时，将从管道的关联 SHA 创建一个新标签。
例如，从 Git 标签创建发布时：
```yaml
工作：
释放：
标签名称：$CI_COMMIT_TAG
description: '发布说明'
``
也可以创建任何唯一的标签，在这种情况下，`only: tags` 不是强制性的。
语义版本控制示例：
```yaml
工作：
释放：
标签名称：${MAJOR}_${MINOR}_${REVISION}
description: '发布说明'
``
- 只有当作业的主脚本成功时才会创建发布。
- 如果发布已经存在，则不会更新并且带有`release` 关键字的作业失败。
- `release` 部分在 `script` 标签之后和 `after_script` 之前执行。
####`发布：名称`
版本名称。如果省略，则使用 `release: tag_name` 的值填充。
####`发布：描述`
指定发布的详细描述。您还可以指定一个包含
描述。
##### 从文件中读取描述
> [介绍](https://gitlab.com/gitlab-org/release-cli/-/merge_requests/67) 在 GitLab 13.7 中。
你可以在 `$CI_PROJECT_DIR` 中指定一个包含描述的文件。该文件必须是相对的
到项目目录（`$CI_PROJECT_DIR`），如果文件是一个符号链接，它就不能驻留
在 `$CI_PROJECT_DIR` 之外。`./path/to/file` 和文件名不能包含空格。
```yaml
工作：
释放：
标签名称：${MAJOR}_${MINOR}_${REVISION}
描述：'./path/to/CHANGELOG.md'
``
####`发布：参考`
如果 `release: tag_name` 还不存在，则从 `ref` 创建发布。
`ref` 可以是提交 SHA、另一个标签名称或分支名称。
####`发布：里程碑`
与发布相关的每个里程碑的标题。
####`release:released_at`
发布准备就绪的日期和时间。如果不是，则默认为当前日期和时间
定义。应该用引号引起来并以 ISO 8601 格式表示。
```json
发布时间：'2021-03-15T08:00:00Z'
``
####`发布：资产：链接`
> [介绍](https://gitlab.com/gitlab-org/gitlab/-/issues/271454) 在 GitLab 13.12 中。
在发布中包含 [资产链接](../../user/project/releases/index.md#release-assets)。
笔记：
需要 `release-cli` 版本 v0.4.0 或更高版本。
```yaml
资产：
链接：
- 名称：'资产1'
网址：'https://example.com/assets/1'
- 名称：'资产2'
网址：'https://example.com/assets/2'
文件路径：'/pretty/url/1' # 可选
link_type: 'other' # 可选
``
#### `release` 的完整示例
如果你结合之前的 `release` 例子，你会得到两个选项，这取决于你如何生成
标签。您不能同时使用这些选项，因此请选择一个：
- 在推送 Git 标签或添加 Git 标签时创建发布
通过转到 **Repository > Tags** 在 UI 中：
```yaml
发布工作：
阶段：发布
图片：registry.gitlab.com/gitlab-org/release-cli:latest
规则：
- if: $CI_COMMIT_TAG # 手动创建标签时运行此作业
脚本：
- echo '正在运行 release_job'
释放：
name: '发布 $CI_COMMIT_TAG'
描述：'使用 release-cli $EXTRA_DESCRIPTION 创建' # $EXTRA_DESCRIPTION 必须被定义
tag_name: '$CI_COMMIT_TAG' # 管道中的其他地方。
参考：'$CI_COMMIT_TAG'
里程碑：
- 'm1'
- 'm2'
- 'm3'
released_at: '2020-07-15T08:00:00Z' # 可选，如果未定义则自动生成，或者可以使用变量。
assets: # 可选，多个资产链接
链接：
- 名称：'资产1'
网址：'https://example.com/assets/1'
- 名称：'资产2'
网址：'https://example.com/assets/2'
文件路径：'/pretty/url/1' # 可选
link_type: 'other' # 可选
``
- 要在提交推送或合并到默认分支时自动创建发布，
使用一个用变量定义的新 Git 标签：
笔记：
在 `before_script` 或 `script` 中设置的环境变量不可用于扩展
在同一份工作中。阅读更多关于
[可能使变量可用于扩展](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/6400)。
```yaml
准备工作：
stage: prepare # 这个阶段必须在发布阶段之前运行
规则：
- 如果：$CI_COMMIT_TAG
when: never # 手动创建标签时不要运行此作业
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH # 当提交被推送或合并到默认分支时运行这个作业
脚本：
- echo "EXTRA_DESCRIPTION=some message" >> variables.env # 生成 EXTRA_DESCRIPTION 和 TAG 环境变量
- echo "TAG=v$(cat VERSION)" >> variables.env # 并附加到 variables.env 文件
文物：
报告：
dotenv: variables.env # 使用 artifacts:reports:dotenv 将变量暴露给其他作业
发布工作：
阶段：发布
图片：registry.gitlab.com/gitlab-org/release-cli:latest
需要：
- 工作：prepare_job
文物：真实
规则：
- 如果：$CI_COMMIT_TAG
when: never # 手动创建标签时不要运行此作业
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH # 当提交被推送或合并到默认分支时运行这个作业
脚本：
- echo '为 $TAG 运行 release_job'
释放：
name: '发布 $TAG'
描述：“使用 release-cli $EXTRA_DESCRIPTION 创建”# $EXTRA_DESCRIPTION 和 $TAG
tag_name: '$TAG' # 变量必须在别处定义
ref: '$CI_COMMIT_SHA' # 在管道中。例如，在
里程碑：# prepare_job
- 'm1'
- 'm2'
- 'm3'
released_at: '2020-07-15T08:00:00Z' # 可选，如果未定义则自动生成，或者可以使用变量。
资产：
链接：
- 名称：'资产1'
网址：'https://example.com/assets/1'
- 名称：'资产2'
网址：'https://example.com/assets/2'
文件路径：'/pretty/url/1' # 可选
link_type: 'other' # 可选
``
#### 将资产发布为通用包
您可以使用 [通用包](../../user/packages/generic_packages/) 来托管您的发布资产。
一个完整的例子，请参见 [Release assets as Generic packages](https://gitlab.com/gitlab-org/release-cli/-/tree/master/docs/examples/release-assets-as-generic-package /)
项目。
#### `release-cli` 命令行
`release` 节点下的条目被转换为 `bash` 命令行并发送
到 Docker 容器，其中包含 [release-cli](https://gitlab.com/gitlab-org/release-cli)。
你也可以直接从 `script` 条目调用 `release-cli`。
例如，如果您使用前面描述的 YAML：
```壳
release-cli create --name "Release $CI_COMMIT_SHA" --description "使用 release-cli $EXTRA_DESCRIPTION 创建" --tag-name "v${MAJOR}.${MINOR}.${REVISION}" --ref "$CI_COMMIT_SHA" --released-at "2020-07-15T08:00:00Z" --milestone "m1" --milestone "m2" --milestone "m3" --assets-link "{\"name\" :\"asset1\",\"url\":\"https://example.com/assets/1\",\"link_type\":\"other\"}
``
###`秘密`
> [介绍](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/33014) 在 GitLab 13.4 中。
使用 `secrets` 指定作业需要的 [CI/CD Secrets](../secrets/index.md)。它应该是一个哈希，
键应该是可供作业使用的变量的名称。
每个秘密的值都保存在一个临时文件中。这个文件的路径存储在这些
变量。
#### `secrets:vault` **(PREMIUM)**
> [介绍](https://gitlab.com/gitlab-org/gitlab/-/issues/28321) 在 GitLab 13.4 中。
使用 `vault` 指定 [Hashicorp's Vault](https://www.vaultproject.io/) 提供的机密。
这种语法有多种形式。最短的形式假定使用
[KV-V2](https://www.vaultproject.io/docs/secrets/kv/kv-v2) 秘密引擎，
安装在默认路径 `kv-v2` 上。秘密路径的最后一部分是
字段来获取值：
```yaml
工作：
秘密：
数据库密码：
vault: production/db/password # 转换为秘密 `kv-v2/data/production/db`，字段 `password`
``
您可以通过添加以 `@` 开头的后缀来指定自定义机密引擎路径：
```yaml
工作：
秘密：
数据库密码：
vault: production/db/password@ops # 转换为秘密 `ops/data/production/db`，字段 `password`
``
在语法的详细形式中，您可以明确指定所有详细信息：
```yaml
工作：
秘密：
DATABASE_PASSWORD: # 转换为秘密 `ops/data/production/db`，字段 `password`
保险库：
引擎：
名称： kv-v2
路径：ops
路径：生产/数据库
字段：密码
``
###`页面`
使用 `pages` 将静态内容上传到 GitLab。内容
然后作为网站发布。你必须：
- 将任何静态内容放在 `public/` 目录中。
- 定义 [`artifacts`](#artifacts) 和 `public/` 目录的路径。
以下示例将所有文件从项目的根目录移动到
`public/` 目录。`.public` 解决 `cp` 也不会复制
`public/` 在无限循环中传递给自身：
```yaml
页数：
阶段：部署
脚本：
- mkdir .public
- cp -r * .public
- mv .public 公共
文物：
路径：
- 上市
只要：
- 主要的
``
查看 [GitLab Pages 用户文档](../.project/pages/index.md)。
###`继承`
> [介绍](https://gitlab.com/gitlaitlab/-/issues/207484) 在 GitLab 12.9 中。
使用 `inherit:` 来控制全局定义继承
和变量。
要启用或禁用所有 `default:` 或 `vs:` 关键字的继承，请使用：
- `default: true` 或 `default: fa
- `变量：真`或`变量：假`
要仅继承 `default:` 关键字或 `var` 的子集，请指定
你想继承。任何未列出的都是**不*用
以下格式之一：
```yaml
继承：
默认值：[关键字 1，关键字 2]
变量：[VARIABLE1, VARIABLE2]
``
或者：
```yaml
继承：
默认：
- 关键字 1
- 关键字 2
变量：
- 变量 1
- 变量 2
``
在以下示例中：
-`rubocop`：
- 继承：没有。
- `rspec`：
- 继承：默认的`image` 和`WEBHOO变量。
- **不** 继承：默认的`before_sc和`DOMAIN` 变量。
-`水豚`：
- 继承：默认的`before_script` `。
- **不** 继承：`DOMAIN` 和`WEBH` 变量。
-`业力`：
- 继承：默认的`image` 和`before`，以及`DOMAIN` 变量。
- **不** 继承：`WEBHOOK_URL`
```yaml
默认：
图像：'红宝石：2.4'
之前_脚本：
- 回声你好世界
变量：
域：example.com
WEBHOOK_URL: https://my-webhooke.com
防暴警察：
继承：
默认值：假
变量：假
脚本：捆绑执行 rubocop
规格：
继承：
默认值：[图像]
变量：[WEBHOOK_URL]
脚本：bundle exec rspec
水豚：
继承：
变量：假
脚本：捆绑执行水豚
业力：
继承：
默认值：真
变量：[域]
剧本：业力
``
##`变量`
> 在 GitLab Runner v0.5.0 中引入。
[CI/CD 变量](../variables/README.传递给作业的可配置值。
它们可以在全局和每个作业中设置。
有两种类型的变量。
- [自定义变量](../variables/READMstom-cicd-variables):
您可以在 GitLab UI 中的 `.gitlal` 文件中定义它们的值，
或通过使用 API。您还可以在 GitL中输入变量
[手动运行管道](../pipelines/indun-a-pipeline-manually)。
- [预定义变量](../variables/predeariables.md):
这些值由跑步者自己设置。
一个例子是`CI_COMMIT_REF_NAME项目构建的分支或标签。
定义变量后，您可以在所有执行的中使用它。
变量用于非敏感项目配置，例如：
```yaml
变量：
DEPLOY_SITE: "https://example.c
部署_作业：
阶段：部署
脚本：
- 部署脚本 --url $DEPLOY_SITE "/"
deploy_review_job:
阶段：部署
变量：
REVIEW_PATH: "/review"
脚本：
- deploy-review-script --url _SITE --path $REVIEW_PATH
``
变量的名称和值只能使用整数和字
如果在 `gitlab-ci.yml` 文件的顶个变量，它是全局的，
这意味着它适用于所有工作。如果定义变量，则它可用
只到那个工作。
如果为特定作业全局定义了同名变
[特定于作业的变量覆盖全局变量](..les/README.md#cicd-variable-precedence)。
所有 YAML 定义的变量也设置为任何
[Docker 服务容器](../services/ind
您可以使用 [YAML 变量锚点](#yaml-or-variables)。
### 在手动管道中预填充变量
> [引入](https://gitlab.com/gitlalab/-/issues/30101) GitLab 13.7。
使用 `value` 和 `description` 预先填充的管道级（全局）变量](../pipelines/index.md#prefill-variables-in-manuapipe
当[手动运行管道](../pipelines/ind-a-pipeline-manually)：
```yaml
变量：
部署环境：
value: "staging" # 默认部署到
描述：“部署目标。如果需要，为‘canary’或‘production’。”
``
当您手动运行管道时，您无法将作预填充。
### 使用变量配置跑步者行为
您可以使用 [CI/CD variables](../vREADME.md) 来配置运行程序如何处理 Git 请求：
- [`GIT_STRATEGY`](../runners/REAt-strategy)
- [`GIT_SUBMODULE_STRATEGY`](../rADME.md#git-submodule-strategy)
- [`GIT_CHECKOUT`](../runners/REAt-checkout)
- [`GIT_CLEAN_FLAGS`](../runners/#git-clean-flags)
- [`GIT_FETCH_EXTRA_FLAGS`](../ruDME.md#git-fetch-extra-flags)
- [`GIT_DEPTH`](../runners/READMEow-cloning)（浅克隆）
- [`GIT_CLONE_PATH`](../runners/Rcustom-build-directories)（自定义构建目录）
- [`TRANSFER_METER_FREQUENCY`](..README.md#artifact-and-cache-settings)（工件/缓存表更新频率）
- [`ARTIFACT_COMPRESSION_LEVEL`](s/README.md#artifact-and-cache-settings)（工件存档器压缩级别）
- [`CACHE_COMPRESSION_LEVEL`](../EADME.md#artifact-and-cache-settings)（缓存归档压缩级别）
您还可以使用变量来配置跑步者的次数
[尝试作业执行的某些阶段](../runne.md#job-stages-attempts)。
## YAML 特定的功能
在你的 `.gitlab-ci.yml` 文件中AML 特定的特性，比如锚点（`&`）、别名（`*`）、
和地图合并（`<<`）。使用这些功
`.gitlab-ci.yml` 文件中的代码。
阅读有关各种 [YAML 功能](https://minutes.com/docs/yaml/) 的更多信息。
在大多数情况下，[`extends` 关键字s) 对用户更友好，您应该
尽可能使用它。
您可以使用 YAML 锚点来合并 YAML 。
### 锚
YAML 有一个叫做“锚点”的功能，你制
整个文档的内容。
使用锚点复制或继承属性。将锚点与作](#hide-jobs) 结合使用
为您的工作提供模板。当有重复的键
基于键执行反向深度合并。
使用 [`include`](#include) 时，文件使用 YAML 锚点
关键词。锚只在定义它们的文件中置
从不同的 YAML 文件，使用 [`!refer签](#reference-tags) 或
[`extends` 关键字](#extends)。
以下示例使用锚点和地图合并。它，
`test1` 和 `test2`，继承了 `.job_ 配置，每个
定义了自己的自定义“脚本”：
```yaml
.job_template: &job_configuration # 隐藏的 yaml 配置，它定义了一个名为“job_configuration”的锚点
图片：红宝石：2.6
服务：
- postgres
- Redis
测试1：
<<: *job_configuration # 合并'job_configuration'别名的内容
脚本：
- test1 项目
测试2：
<<: *job_configuration # 合并'job_configuration'别名的内容
脚本：
- 测试2项目
``
`&` 设置锚点的名称（`job_configuration`），`<<` 表示“合并
给定散列到当前的散列中，”并且 `*` 包括命名锚
（再次`job_configuration`）。这个例子的扩展版本是：
```yaml
.job_template：
图片：红宝石：2.6
服务：
- postgres
- Redis
测试1：
图片：红宝石：2.6
服务：
- postgres
- Redis
脚本：
- test1 项目
测试2：
图片：红宝石：2.6
服务：
- postgres
- Redis
脚本：
- 测试2项目
``
您可以使用锚点来定义两组服务。例如，`test:postgres`
和 `test:mysql` 共享 `.job_template` 中定义的 `script`，但使用不同的
`services`，在 `.postgres_services` 和 `.mysql_services` 中定义：
```yaml
.job_template: &job_configuration
脚本：
- 测试项目
标签：
- 开发
.postgres_services:
服务：&postgres_configuration
- postgres
- 红宝石
.mysql_services:
服务：&mysql_configuration
- mysql
- 红宝石
测试：postgres：
<<: *job_configuration
服务：*postgres_configuration
标签：
- postgres
测试：mysql：
<<: *job_configuration
服务：*mysql_configuration
``
扩展版本是：
```yaml
.job_template：
脚本：
- 测试项目
标签：
- 开发
.postgres_services:
服务：
- postgres
- 红宝石
.mysql_services:
服务：
- mysql
- 红宝石
测试：postgres：
脚本：
- 测试项目
服务：
- postgres
- 红宝石
标签：
- postgres
测试：mysql：
脚本：
- 测试项目
服务：
- mysql
- 红宝石
标签：
- 开发
``
您可以看到隐藏的作业可以方便地用作模板，并且
`tags: [postgres]` 覆盖 `tags: [dev]`。
#### 脚本的 YAML 锚点
> [介绍](https://gitlab.com/gitlab-org/gitlab/-/issues/23005) 在 GitLab 12.5 中。
您可以将 [YAML 锚点](#anchors) 与 [script](#script)、[`before_script`](#before_script)、
和 [`after_script`](#after_script) 在多个作业中使用预定义的命令：
```yaml
.some-script-before: &some-script-before
- echo "先执行这个脚本"
.some-script: &some-script
- echo "第二次执行这个脚本"
- echo "也执行这个脚本"
.some-script-after: &some-script-after
- echo "最后执行这个脚本"
工作1：
之前_脚本：
- *some-script-before
脚本：
- *一些脚本
- echo "执行某事，仅针对这项工作"
后脚本：
- *some-script-after
工作2：
脚本：
- *some-script-before
- *一些脚本
- echo "执行其他操作，仅针对此工作"
- *some-script-after
``
#### 变量的 YAML 锚点
使用 [YAML 锚点](#anchors) 和 `variables` 重复赋值
跨多个作业的变量。您还可以在作业时使用 YAML 锚点
需要一个特定的 `variables` 块，否则会覆盖全局变量。
以下示例显示如何在不影响的情况下覆盖 `GIT_STRATEGY` 变量
`SAMPLE_VARIABLE` 变量的使用：
```yaml
# 全局变量
变量：&全局变量
SAMPLE_VARIABLE：sample_variable_value
ANOTHER_SAMPLE_VARIABLE：another_sample_variable_value
# 一个必须设置 GIT_STRATEGY 变量但依赖于全局变量的作业
job_no_git_strategy:
阶段：清理
变量：
<<: *全局变量
GIT_STRATEGY：无
脚本：echo $SAMPLE_VARIABLE
``
### 隐藏工作
如果你想暂时禁用一个作业，而不是注释掉所有的
定义作业的行：
```yaml
# hidden_job:
＃ 脚本：
# - 运行测试
``
相反，你可以用一个点（`.`）开始它的名字，它不会被处理
亚搏体育应用 CI/CD。在下面的例子中，`.hidden_job` 被忽略：
```yaml
.hidden_job：
脚本：
- 运行测试
``
使用此功能忽略作业，或使用
[YAML-specific features](#yaml-specific-features) 并转换隐藏作业
成模板。
### `!reference` 标签
> - [介绍](https://gitlab.com/gitlab-org/gitlab/-/issues/266173) 在 GitLab 13.9 中。
使用 `!reference` 自定义 YAML 标签从其他作业中选择关键字配置
部分并在当前部分中重用它。与 [YAML 锚点](#anchors) 不同，您可以
使用 `!reference` 标签重用 [included](#include) 配置中的配置
文件也是如此。
在以下示例中，来自两个不同位置的 `script` 和一个 `after_script` 是
在 `test` 作业中重用：
- `setup.yml`：
```yaml
。设置：
脚本：
- echo 创建环境
``
-`.gitlab-ci.yml`：
```yaml
包括：
- 本地：setup.yml
。拆除：
后脚本：
- echo 删除环境
测试：
脚本：
- !reference [.setup, script]
- echo 运行我自己的命令
后脚本：
- !reference [.teardown, after_script]
``
在下面的例子中，`test-vars-1` 重用了 `.vars` 中的所有变量，而 `test-vars-2`
选择一个特定的变量并将其作为新的“MY_VAR”变量重用。
```yaml
.vars：
变量：
网址：“http://my-url.internal”
IMPORTANT_VAR：“详细信息”
测试变量-1：
变量：!reference [.vars, variables]
脚本：
- 打印环境
测试变量 2：
变量：
MY_VAR: !reference [.vars, variables, IMPORTANT_VAR]
脚本：
- 打印环境
``
您不能重复使用已经包含 `!reference` 标签的部分。只有一层
支持嵌套。
## 跳过管道
要在不触发管道的情况下推送提交，请添加 `[ci skip]` 或 `[skip ci]`，使用任何
大写，到您的提交消息。
或者，如果您使用 Git 2.10 或更高版本，请使用 `ci.skip` [Git push option](../../user/project/push_options.md#push-options-for-gitlab-cicd)。
`ci.skip` 推送选项不会跳过合并请求
管道。
## 处理 Git 推送
GitLab 在以下情况下最多创建四个分支和标记管道
在单个 `git push` 调用中推送多个更改。
此限制不会影响任何更新的合并请求管道。
所有更新的合并请求都在使用时创建了一个管道
[合并请求的管道](../merge_request_pipelines/index.md)。
## 弃用的关键字
以下关键字已弃用。
### 全局定义的`types`
警告：
`types` 已弃用，可能会在未来版本中删除。
使用 [`stages`](#stages) 代替。
### 作业定义的`type`
警告：
`type` 已弃用，可能会在未来版本之一中删除。
使用 [`stage`](#stage) 代替。
### 全局定义的`image`、`services`、`cache`、`before_script`、`after_script`
定义 `image`、`services`、`cache`、`before_script` 和
全局不推荐使用 `after_script`。可以删除支持
从未来的版本。
使用 [`default:`](#custom-default-keyword-values) 代替。例如：
```yaml
默认：
图像：红宝石：3.0
服务：
- 码头工人：dind
缓存：
路径：[供应商/]
之前_脚本：
- 捆绑配置设置路径供应商/捆绑
- 捆绑安装
后脚本：
- rm -rf tmp