GitLab CI / CD管道配置参考

GitLab CI/CD pipeline configuration reference

使用在每个项目中调用的YAML文件配置GitLab CI / CD 管道.gitlab-ci.yml。

该.gitlab-ci.yml文件定义管道的结构和顺序，并确定：

• 使用GitLab Runner执行什么。
• 遇到特定条件时要做出什么决定。例如，当一个过程成功或失败时。

本主题涵盖CI / CD管道配置。有关其他CI / CD配置信息，请参阅：

• GitLab CI / CD变量，用于配置运行管道的环境。
• GitLab Runner高级配置，用于配置GitLab Runner。

我们有配置管道的完整示例：

• 有关GitLab CI / CD的快速介绍，请遵循我们的快速入门指南。
• 有关示例集合，请参见GitLab CI / CD示例。
• 要查看.gitlab-ci.yml企业中使用的大文件，请参阅的.gitlab-ci.yml文件gitlab。

有关GitLab CI / CD的其他信息：

•  观看CI / CD轻松配置视频。
• 在组织的 网络广播中观看“ 为CI / CD辩护”，以了解CI / CD的好处以及如何衡量CI / CD自动化的结果。
•  了解Verizon如何 使用GitLab 将重建工作从30天减少到8小时以下。

介绍

管道配置从作业开始。作业是.gitlab-ci.yml文件的最基本元素。

工作是：

• 定义了约束，指出应在什么条件下执行它们。
• 具有任意名称的顶级元素，并且必须至少包含script子句。
• 不限制可以定义多少个。

例如：

job1:script: "execute-script-for-job1"

job2:script: "execute-script-for-job2"

上面的示例是具有两个单独作业的最简单的CI / CD配置，其中每个作业执行一个不同的命令。当然，命令可以在存储库中直接执行代码（./configure;make;make install）或运行脚本（test.sh）。

乔布斯被拾起运动员和跑步者的环境中执行。重要的是，每个作业彼此独立运行。

验证 .gitlab-ci.yml

GitLab CI / CD的每个实例都有一个称为Lint的嵌入式调试工具，该工具可以验证.gitlab-ci.yml文件的内容。您可以在ci/lint项目名称空间页面下找到Lint 。例如，https://gitlab.example.com/gitlab-org/project-123/-/ci/lint。

作业名称不可用

每个作业必须具有唯一的名称，但是有一些保留keywords名称不能用作作业名称：

• image
• services
• stages
• types
• before_script
• after_script
• variables
• cache
• include

使用保留关键字

如果使用特定值（例如true或false）时出现验证错误，请尝试执行以下操作：

• 引用他们。
• 将它们更改为其他形式。例如，/bin/true。

配置参数

作业定义为定义作业行为的参数列表。

下表列出了作业的可用参数：

全局参数

必须在全局级别定义一些参数，这会影响管道中的所有作业。

全局默认值

可以使用default:关键字将某些参数全局设置为所有作业的默认设置。然后可以通过特定于作业的配置覆盖默认参数。

可以在default:块内定义以下作业参数：

• image
• services
• before_script
• after_script
• tags
• cache
• artifacts
• retry
• timeout
• interruptible

在以下示例中，该ruby:2.5图像被设置为除rspec 2.6使用该ruby:2.6图像的作业以外的所有作业的默认图像：

default:image: ruby:2.5

rspec:script: bundle exec rspec

rspec 2.6:image: ruby:2.6script: bundle exec rspec

inherit

您可以使用inherit:参数禁用全局定义的默认值和变量的继承。

要启用或禁用全部variables:或default:参数的继承，请使用以下格式：

• default: true 要么 default: false
• variables: true 要么 variables: false

要仅继承default:参数或的子集variables:，请指定要继承的内容，未列出的任何内容均不会被继承。使用以下格式之一：

inherit:default: [parameter1, parameter2]variables: [VARIABLE1, VARIABLE2]

要么：

inherit:default:- parameter1- parameter2variables:- VARIABLE1- VARIABLE2

在以下示例中：

• rubocop：
  • 会继承：没有。
• rspec：
  • 将继承：默认值image和WEBHOOK_URL变量。
  • 会不会继承：默认before_script和DOMAIN变量。
• capybara：
  • 将继承：默认before_script和image。
  • 会不会继承：在DOMAIN和WEBHOOK_URL变量。
• karma：
  • 将继承：默认值image和before_script，以及DOMAIN变量。
  • 会不会继承：WEBHOOK_URL变量。

default:image: 'ruby:2.4'before_script:- echo Hello World

variables:DOMAIN: example.comWEBHOOK_URL: https://my-webhook.example.com

rubocop:inherit:default: falsevariables: falsescript: bundle exec rubocop

rspec:inherit:default: [image]variables: [WEBHOOK_URL]script: bundle exec rspec

capybara:inherit:variables: falsescript: bundle exec capybara

karma:inherit:default: truevariables: [DOMAIN]script: karma

stages

stages 用于定义包含作业的阶段，并为管道全局定义。

的规范stages允许具有灵活的多级管道。中的元素顺序stages定义了作业执行的顺序：

1. 同一阶段的作业并行运行。
2. 前一阶段的作业成功完成后，将运行下一阶段的作业。

让我们考虑以下示例，该示例定义了3个阶段：

stages:- build- test- deploy

1. 首先，的所有作业build并行执行。
2. 如果所有作业均build成功，则这些test作业将并行执行。
3. 如果所有作业均test成功，则这些deploy作业将并行执行。
4. 如果所有作业均deploy成功，则将提交标记为passed。
5. 如果先前的任何作业失败，则将提交标记为，failed并且不执行后续作业。

还有两个边缘情况值得一提：

1. 如果没有stages被定义.gitlab-ci.yml，那么build，test和deploy允许被用作默认作业的阶段。
2. 如果作业未指定stage，则为该作业分配test阶段。

workflow:rules

顶级workflow:密钥适用于整个管道，并将确定是否创建管道。当前，它接受与作业中定义的rules:操作类似的单个密钥，从而可以动态配置管道。 rules:

如果您不熟悉GitLab CI / CD和workflow: rules，您可能会发现workflow:rules模板有用。

要定义自己的workflow: rules，当前可用的配置选项为：

• if：定义规则。
• when：可以设置为always或never仅设置。如果未提供，则默认值为always。

如果管道尝试运行但不匹配任何规则，则将其删除并且无法运行。

例如，下面的配置，管道的所有运行push事件（改变分支和新的标签），只要它们不具有-wip在提交信息。预定管道和合并请求管道不会运行，因为没有规则允许它们。

workflow:rules:- if: $CI_COMMIT_REF_NAME =~ /-wip$/when: never- if: '$CI_PIPELINE_SOURCE == "push"'

这个例子有严格的规则，没有其他管道可以运行。

或者，您可以只使用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（分支和标签）管道的管道，但是在所有其他情况下都允许管道，包括合并请求管道。

与rules在job中定义的一样，请注意不要使用允许合并请求管道和分支管道同时运行的配置，否则您可能会有重复的管道。

有用的工作流程规则条款：

workflow:rules 范本

我们提供了可与您的管道配合使用的预制模板，这些模板workflow: rules 针对常见情况进行了设置。使用这些将使事情变得容易，并防止重复的管道运行。

该Branch-Pipelines模板 使您的管道针对分支和标签运行。

分支管道状态将显示在使用该分支作为源的合并请求中，但是此管道类型不支持“ 合并请求管道”提供的任何功能，例如“合并结果管道” 或“ 合并训练”。如果您有意避免使用这些功能，请使用此模板。

它包括以下内容：

include:- template: 'Workflows/Branch-Pipelines.gitlab-ci.yml'

该MergeRequest-Pipelines模板 使您的管道针对默认分支（通常是master），标签和所有类型的合并请求管道运行。如上所述，如果您使用任何“ 合并请求管道”功能，请使用此模板。

它包括以下内容：

include:- template: 'Workflows/MergeRequest-Pipelines.gitlab-ci.yml'

include

使用include关键字允许包含外部YAML文件。这有助于将CI / CD配置分解为多个文件，并提高了长配置文件的可读性。也可以将模板文件存储在中央存储库中，并且项目包括其配置文件。这有助于避免重复配置，例如，所有项目的全局默认变量。

include要求外部YAML文件具有扩展名.yml或.yaml，否则将不包含外部文件。

include 支持以下包含方法：

该include方法不支持变量扩展。

定义的文件include为：

• 与那些深深的合并.gitlab-ci.yml。
• .gitlab-ci.yml无论include关键字的位置如何，始终首先评估并与的内容合并。

include:local

include:local包含与相同存储库中的文件.gitlab-ci.yml。使用相对于根目录（/）的完整路径进行引用。

您只能在配置文件所在的同一分支上使用Git当前跟踪的文件。换句话说，当使用时include:local，请确保它们.gitlab-ci.yml和本地文件都在同一分支上。

所有嵌套的包含将在同一项目的范围内执行，因此可以使用本地，项目，远程或模板包含。

例：

include:- local: '/templates/.gitlab-ci-template.yml'

可以将其定义为简短的本地包含：

include: '.gitlab-ci-production.yml'

include:file

要在同一GitLab实例下包含来自另一个私有项目的文件，请使用include:file。使用相对于根目录（/）的完整路径引用此文件。例如：

include:- project: 'my-group/my-project'file: '/templates/.gitlab-ci-template.yml'

您还可以指定ref，默认为HEAD项目的：

include:- project: 'my-group/my-project'ref: masterfile: '/templates/.gitlab-ci-template.yml'
- project: 'my-group/my-project'ref: v1.0.0file: '/templates/.gitlab-ci-template.yml'
- project: 'my-group/my-project'ref: 787123b47f14b552955ca2786bc9542ae66fee5b # Git SHAfile: '/templates/.gitlab-ci-template.yml'

所有嵌套的包含将在目标项目的范围内执行，因此可以使用本地（相对于目标项目），项目，远程或模板包含。

include:remote

include:remote可以用于通过HTTP / HTTPS包含来自其他位置的文件，并使用完整URL进行引用。远程文件必须可以通过简单的GET请求公开访问，因为不支持远程URL中的身份验证模式。例如：

include:- remote: 'https://gitlab.com/awesome-project/raw/master/.gitlab-ci-template.yml'

所有嵌套的include将在没有上下文的情况下作为公共用户执行，因此仅允许另一个远程或公共项目或模板。

include:template

include:template可用于包括GitLab随附的.gitlab-ci.yml模板。

例如：

# File sourced from GitLab's 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个include，但是重复的include被视为配置错误。

从GitLab 12.4开始，解析所有文件的时间限制为30秒。

其他includes例子

有可用的其他includes示例列表。

参数详细

以下是用于配置CI / CD管道的参数的详细说明。

image

用于指定要用于作业的Docker映像。

对于：

• 简单的定义示例，请参见Define imageand servicesfrom.gitlab-ci.yml。
• 详细的使用信息，请参阅Docker集成文档。

image:name

一个扩展泊坞窗配置选项。

有关更多信息，请参见的可用设置image。

image:entrypoint

一个扩展泊坞窗配置选项。

有关更多信息，请参见的可用设置image。

services

用于指定服务Docker映像，该映像链接到中指定的基本映像image。

对于：

• 简单的定义示例，请参见Define imageand servicesfrom.gitlab-ci.yml。
• 详细的使用信息，请参阅Docker集成文档。
• 有关示例服务，请参见GitLab CI / CD服务。

services:name

一个扩展泊坞窗配置选项。

有关更多信息，请参见的可用设置services。

services:alias

一个扩展泊坞窗配置选项。

有关更多信息，请参见的可用设置services。

services:entrypoint

一个扩展泊坞窗配置选项。

有关更多信息，请参见的可用设置services。

services:command

一个扩展泊坞窗配置选项。

有关更多信息，请参见的可用设置services。

script

script是工作所需的唯一必需关键字。这是一个由Runner执行的shell脚本。例如：

job:script: "bundle exec rspec"

脚本的YAML锚可用。

此参数还可以包含使用数组的多个命令：

job:script:- uname -a- bundle exec rspec

如果任何脚本命令返回的退出代码都不为零，则该作业将失败，并且其他命令将不再执行。通过将退出代码存储在变量中，可以避免此行为：

job:script:- false || exit_code=$?- if [ $exit_code -ne 0 ]; then echo "Previous command failed"; fi;

before_script 和 after_script

before_script用于定义一个命令，该命令应在每个作业（包括部署作业）之前，但在还原所有工件之后运行。这必须是一个数组。

中指定的before_script脚本与main中指定的任何脚本串联在一起script，并在单个shell中一起执行。

after_script用于定义将在每个作业（包括失败的作业）之后运行的命令。这必须是一个数组。

指定的脚本在after_script新的Shell中执行，与任何脚本before_script或script脚本分开。结果，他们：

• 将当前工作目录设置回默认目录。
• 无法访问由before_script或定义的脚本所做的更改script，包括：
  • 在script脚本中导出的命令别名和变量。
  • 在工作树之外进行更改（取决于Runner执行程序），例如由before_script或script脚本安装的软件。
• 有一个单独的超时，硬编码为5分钟。有关详细信息，请参见相关问题。
• 不要影响作业的退出代码。如果该script部分成功并且after_script超时或失败，则作业将以代码0（Job Succeeded）退出。

可能会覆盖全局定义的内容，before_script或者after_script 如果您按作业设置它，则可以：

default:before_script:- global before script

job:before_script:- execute this instead of global before scriptscript:- my commandafter_script:- execute this after my script

YAML锚before_script和after_script可用。

着色脚本输出

脚本输出可以使用ANSI转义码或运行输出ANSI转义码的命令或程序来着色。

例如，使用带有颜色代码的Bash：

job:script:- echo -e "\e[31mThis text is red,\e[0m but this text isn't\e[31m however this text is red again."

您可以在Shell变量甚至自定义环境变量中定义颜色代码，这使命令更易于阅读和重用。

例如，使用与上述相同的示例，并在中定义变量before_script：

job:before_script:- TXT_RED="\e[31m" && TXT_CLEAR="\e[0m"script:- echo -e "${TXT_RED}This text is red,${TXT_CLEAR} but this part isn't${TXT_RED} however this part is again."- echo "This text is not colored"

或使用PowerShell颜色代码：

job:before_script:- $esc="$([char]27)"; $TXT_RED="$esc[31m"; $TXT_CLEAR="$esc[0m"script:- Write-Host $TXT_RED"This text is red,"$TXT_CLEAR" but this text isn't"$TXT_RED" however this text is red again."- Write-Host "This text is not colored"

多行命令

您可以使用|（文字）和>（折叠）YAML多行块标量指示器将长命令分成多行命令以提高可读性。

您可以使用|（文字上的）YAML多行块标量指示器在script作业描述部分的多行上编写命令。每行都被视为一个单独的命令。在作业日志中仅重复第一个命令，但仍执行其他命令：

job:script:- |echo "First command line."echo "Second command line."echo "Third command line."

上面的示例在作业日志中呈现为：

$ echo First command line # collapsed multi-line command
First command line
Second command line.
Third command line.

的>（折叠的）YAML多块标量指示器对待部分作为新的命令的开始之间的空行：

job:script:- >echo "First command lineis split over two lines."
echo "Second command line."

这与编写没有>或|标量指示符的多行命令的行为类似：

job:script:- echo "First command lineis split over two lines."
echo "Second command line."

上面的两个示例在作业日志中均显示为：

$ echo First command line is split over two lines. # collapsed multi-line command
First command line is split over two lines.
Second command line.

当省略>或|块标量指示符时，GitLab将通过连接非空行来形成命令，因此请确保在连接时行可以运行。

此处的 Shell 文件也可与|和>运算符一起使用。下面的示例将小写字母音译为大写字母：

job:script:- |tr a-z A-Z << END_TEXTone two threefour five sixEND_TEXT

结果是：

$ tr a-z A-Z << END_TEXT # collapsed multi-line commandONE TWO THREEFOUR FIVE SIX

stage

stage是按职位定义的，并依赖于stages全局定义的职位。它允许将作业分为不同的阶段，并且相同的作业stage可以并行执行（取决于特定条件）。例如：

stages:- build- test- deploy

job 0:stage: .prescript: make something useful before build stage

job 1:stage: buildscript: make build dependencies

job 2:stage: buildscript: make build artifacts

job 3:stage: testscript: make test

job 4:stage: deployscript: make deploy

job 5:stage: .postscript: make something useful at the end of pipeline

使用自己的跑步者

当使用自己的Runners时，默认情况下，GitLab Runner一次仅运行一个作业（ 有关更多信息，请参见Runner全局设置中的concurrent标志）。

仅在以下情况下，作业将在您自己的跑步者上并行运行：

• 在不同的跑步者上运行。
• 跑步者的concurrent设置已更改。

.pre 和 .post

每个管道均可使用以下阶段：

• .pre，这确保始终是管道的第一阶段。
• .post，确保始终是管道的最后阶段。

用户定义的阶段在.pre之前和之后执行.post。

的顺序.pre和.post也不能更改，即使在中乱序定义也是如此.gitlab-ci.yml。例如，以下是等效配置：

• 按顺序配置：

  stages:- .pre- a- b- .post
  

• 配置乱序：

  stages:- a- .pre- b- .post
  

• 未明确配置：

  stages:- a- b
  

extends

extends定义要使用的作业extends要继承的条目名称。

它是使用YAML锚点的替代方法，并且更具灵活性和可读性：

.tests:script: rake teststage: testonly:refs:- branches

rspec:extends: .testsscript: rake rspeconly:variables:- $RSPEC

在上面的示例中，该rspec作业继承自.tests模板作业。GitLab将基于密钥执行反向深度合并。GitLab将：

• 将rspec内容.tests递归合并。
• 不合并键的值。

这将导致以下rspec工作：

rspec:script: rake rspecstage: testonly:refs:- branchesvariables:- $RSPEC

如果确实要包含rake test，请参阅before_script和after_script。

.tests在此示例中，是一个隐藏的作业，但是也可以从常规作业中继承。

extends支持多级继承，但是不建议使用三个以上级别。支持的最大嵌套级别为10。以下示例具有两个继承级别：

.tests:only:- pushes

.rspec:extends: .testsscript: rake rspec

rspec 1:variables:RSPEC_SUITE: '1'extends: .rspec

rspec 2:variables:RSPEC_SUITE: '2'extends: .rspec

spinach:extends: .testsscript: rake spinach

在GitLab 12.0和更高版本中，还可以对使用多个父对象extends。

合并细节

extends能够合并哈希，但不能合并数组。用于合并的算法是“最近的范围获胜”，因此来自最后一个成员的键将始终覆盖在其他级别定义的任何内容。例如：

.only-important:variables:URL: "http://my-url.internal"IMPORTANT_VAR: "the details"only:- master- stabletags:- productionscript:- echo "Hello world!"

.in-docker:variables:URL: "http://docker-url.internal"tags:- dockerimage: alpine

rspec:variables:GITLAB: "is-awesome"extends:- .only-important- .in-dockerscript:- rake rspec

这将导致以下rspec工作：

rspec:variables:URL: "http://docker-url.internal"IMPORTANT_VAR: "the details"GITLAB: "is-awesome"only:- master- stabletags:- dockerimage: alpinescript:- rake rspec

请注意，在上面的示例中：

• variables部分已合并，但URL: "http://my-url.internal" 已被覆盖URL: "http://docker-url.internal"。
• tags: ['production']已被覆盖tags: ['docker']。
• script尚未合并，但script: ['echo "Hello world!"']已被覆盖script: ['rake rspec']。可以使用YAML锚点合并数组。

使用extends和include在一起

extends与结合使用时可跨配置文件使用include。

例如，如果您有本地included.yml文件：

.template:script:- echo Hello!

然后，.gitlab-ci.yml您可以像这样使用它：

include: included.yml

useTemplate:image: alpineextends: .template

这将运行一个名为作业的作业，该作业按照作业中的定义useTemplate运行，并使用本地作业中定义的Docker映像。 echo Hello!.templatealpine

rules

该rules关键字可用于包括或管道排除作业。

规则将按顺序评估，直到第一个匹配为止。匹配后，根据配置将作业包括在管道中或从管道中排除。如果包含，则作业还会 添加某些属性。

规则属性

允许的作业属性rules为：

• when：如果未定义，则默认为when: on_success。
  • 如果用作when: delayed，start_in则也是必需的。
• allow_failure：如果未定义，则默认为allow_failure: false。

如果规则评估为true，并且when除以外的其他任何值never，则该作业将包含在管道中。

例如：

docker build:script: docker build -t my-image:$CI_COMMIT_REF_SLUG .rules:- if: '$CI_COMMIT_BRANCH == "master"'when: delayedstart_in: '3 hours'allow_failure: true

将来可能会将其他作业配置添加到规则中。如果没有有用的东西，请打开一个问题。

规则条款

可用的规则子句为：

顺序评估规则，直到找到匹配项。如果找到匹配项，则检查属性以查看是否应将作业添加到管道。如果未定义任何属性，则默认值为：

• when: on_success
• allow_failure: false

作业已添加到管道中：

• 如果规则相匹配，并且具有when: on_success，when: delayed或when: always。
• 如果没有规则匹配，但最后一句是when: on_success，when: delayed 或when: always（无规则）。

作业未添加到管道：

• 如果没有规则匹配，并没有独立的when: on_success，when: delayed或when: always。
• 如果规则匹配，并具有when: never作为属性。

例如，使用if子句严格限制作业运行的时间：

job:script: "echo Hello, Rules!"rules:- if: '$CI_PIPELINE_SOURCE == "merge_request_event"'when: manualallow_failure: true- if: '$CI_PIPELINE_SOURCE == "schedule"'

在此示例中：

• 如果管道用于合并请求，则第一个规则匹配，并且作业将添加到合并请求管道 ，其属性为：
  • when: manual （体力劳动）
  • allow_failure: true （即使未运行手动作业，也允许管道继续运行）
• 如果管道不是用于合并请求的，则第一条规则不匹配，并且第二条规则被评估。
• 如果管道是计划的管道，则第二条规则匹配，并将作业添加到计划的管道。由于未定义任何属性，因此添加了：
  • when: on_success （默认）
  • allow_failure: false （默认）
• 在所有其他情况下，没有规则匹配，因此该作业不会添加到任何其他管道。

另外，您可以定义一组规则以在某些情况下排除作业，但在所有其他情况下运行它们：

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。

rules和only/ 之间的差异except

only/except默认情况下，使用定义的作业不会触发合并请求管道。您必须明确添加only: merge_requests。

用定义的作业rules可以触发所有类型的管道。您不必显式配置每种类型。

例如：

job:script: "echo This creates double pipelines!"rules:- if: '$CUSTOM_VARIABLE == "false"'when: never- when: always

当此作业不运行$CUSTOM_VARIABLE是假的，但它确实在运行的所有 其他管线，包括两个推（分支）和合并请求管道。使用此配置，每次推送到打开的合并请求的源分支都会导致重复的管道。明确允许在同一作业中同时使用推送和合并请求管道可能具有相同的效果。

我们建议使用workflow: rules来限制允许的管道类型。仅允许合并请求管道，或仅允许分支管道，可以消除重复的管道。或者，您可以使用避免最终重写规则更严格，或when（always，on_success或delayed）。

另外，我们不建议将only/except作业与rules同一管道中的作业混合使用。它可能不会引起YAML错误，但调试确切的执行行为可以是不同的默认行为复杂，因为only/except和rules。

rules:if

rules:if子句通过评估简单if语句来确定是否将作业添加到管道。如果该if语句为true，则将作业包括在管道中或从管道中排除。用简单的英语来说，if规则可以解释为以下之一：

• “如果此规则评估为true，则添加作业”（默认值）。
• “如果该规则评估为true，则不要添加作业”（通过添加when: never）。

rules:if与only:variables每个规则只接受一个表达式字符串而不是它们的数组稍有不同。可以 使用或将任何要求值的表达式集组合为一个表达式，并使用变量匹配语法。 &&||

if:子句基于预定义环境变量 或自定义环境变量的值进行评估。

例如：

job:script: "echo Hello, Rules!"rules:- if: '$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME =~ /^feature/ && $CI_MERGE_REQUEST_TARGET_BRANCH_NAME == "master"'when: always- if: '$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME =~ /^feature/'when: manualallow_failure: true- if: '$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME' # Checking for the presence of a variable is possible

有关确定when工作逻辑的一些细节：

• 如果提供的规则均不匹配，则将作业设置when: never为且不包含在管道中。
• 不带任何条件子句的规则（例如 不带或的whenor allow_failure规则）始终匹配，并且在达到条件时始终使用。 ifchanges
• 如果规则匹配且未when定义，则该规则使用when 作业的定义，on_success如果未定义，则默认为。
• 您可以为when每个规则定义一次，也可以在作业级别定义一次，这适用于所有规则。您不能when在工作级别使用whenin规则。

通用if条款rules

对于与only/ except关键字类似的行为，您可以检查$CI_PIPELINE_SOURCE变量的值：

例如：

job:script: "echo Hello, Rules!"rules:- if: '$CI_PIPELINE_SOURCE == "schedule"'when: manualallow_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"'

本示例将作业作为合并请求管道 和计划管道中的when: on_success作业运行。它不能在任何其他管道类型中运行。

if子句的其他常用变量：

• if: $CI_COMMIT_TAG：如果为标签推送更改。
• if: $CI_COMMIT_BRANCH：如果将更改推送到任何分支。
• if: '$CI_COMMIT_BRANCH == "master"'：如果将更改推送到master。
• if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'：如果将更改推送到默认分支（通常为master）。如果在可能具有不同默认分支的多个项目中重用同一配置，则很有用。
• if: '$CI_COMMIT_BRANCH =~ /regex-expression/'：如果commit分支与正则表达式匹配。
• if: '$CUSTOM_VARIABLE !~ /regex-expression/'：如果自定义变量 CUSTOM_VARIABLE并没有匹配的正则表达式。
• if: '$CUSTOM_VARIABLE == "value1"'：如果自定义变量CUSTOM_VARIABLE是value1。

为了避免在创建分支而未进行任何更改时运行管道，请检查的值$CI_COMMIT_BEFORE_SHA。其值为0000000000000000000000000000000000000000：

• 在没有提交的分支中。
• 在标记管道和计划管道中。如果您不想跳过这些规则，则应将其定义得非常狭窄。

要跳过所有空分支上的管道，还要跳过标签和时间表：

rules:- if: $CI_COMMIT_BEFORE_SHA == '0000000000000000000000000000000000000000'when: never

要在分支为空时跳过分支管道：

rules:- if: $CI_COMMIT_BRANCH && $CI_COMMIT_BEFORE_SHA != '0000000000000000000000000000000000000000'

rules:changes

为了确定是否应将作业添加到管道，rules: changes子句会检查由Git push事件更改的文件。

rules: changes的工作方式与only: changes和except: changes完全相同，接受路径数组。同样，如果没有Git推送事件，则始终返回true。它仅应用于分支管道或合并请求管道。

例如：

workflow:rules:- if: '$CI_PIPELINE_SOURCE == "merge_request_event"'

docker build:script: docker build -t my-image:$CI_COMMIT_REF_SLUG .rules:- changes:- Dockerfilewhen: manualallow_failure: true

在此示例中：

• workflow: rules 仅允许管道用于所有作业的合并请求。
• 如果Dockerfile已更改，则将该作业作为手动作业添加到管道中，并允许管道继续运行，即使未触发该作业（allow_failure: true）。
• 如果Dockerfile尚未更改，请不要将作业添加到任何管道（与相同when: never）。

rules:exists

exists 接受路径数组，如果其中任何一个路径作为存储库中的文件存在，则将匹配。

例如：

job:script: docker build -t my-image:$CI_COMMIT_REF_SLUG .rules:- exists:- Dockerfile

您还可以使用全局模式来匹配存储库中任何目录中的多个文件。

例如：

job:script: bundle exec rspecrules:- exists:- spec/**.rb

rules:allow_failure

您可以allow_failure: true在rules:不停止管道本身的情况下使用来允许作业失败或手动作业等待操作。未定义使用rules:默认为allow_failure: false if的所有作业allow_failure:。

规则级rules:allow_failure选项将覆盖作业级allow_failure选项，并且仅在作业由特定规则触发时才应用。

job:script: "echo Hello, Rules!"rules:- if: '$CI_MERGE_REQUEST_TARGET_BRANCH_NAME == "master"'when: manualallow_failure: true

在此示例中，如果第一个规则匹配，则作业将具有when: manual和allow_failure: true。

复杂规则条款

要合相if，changes以及exists与AND子句，在相同的规则中使用它们。

在以下示例中：

• 如果Dockerfile或中的任何文件docker/scripts/ 更改了AND，我们将手动运行该作业$VAR == "string value"。
• 否则，该作业将不会包含在管道中。

docker build:script: docker build -t my-image:$CI_COMMIT_REF_SLUG .rules:- if: '$VAR == "string value"'changes: # Will 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, this is implied any time rules are listed.

诸如branches或之refs类的当前可用于only/的关键字except尚不可用，rules因为在这种情况下，它们的用法和行为正在被单独考虑。我们的史诗rules中正在讨论未来的关键字改进，以改进，任何人都可以添加建议或请求。

only/ except（基本）

only和except是两个参数，用于设置作业策略以限制创建作业的时间：

1. only 定义将为其运行作业的分支和标签的名称。
2. except定义将不运行作业的分支和标签的名称。

有一些适用于作业策略的规则：

• only并且except具有包容性。如果作业规范中同时定义了only和except，则ref将由only和过滤except。
• only并except允许使用正则表达式（受支持的regexp语法）。
• only并except允许指定存储库路径以过滤派生作业。

另外，only并except允许使用特殊关键字：

在以下示例中，job将仅对以开头的引用运行issue-，而所有分支都将被跳过：

job:# use regexponly:- /^issue-.*$/# use special keywordexcept:- branches

模式匹配默认情况下区分大小写。使用i标志修饰符，例如/pattern/i使模式不区分大小写：

job:# use regexponly:- /^issue-.*$/i# use special keywordexcept:- branches

在此示例中，job将仅对带标签的引用运行，或者通过API触发器或管道时间表显式请求构建时运行：

job:# use special keywordsonly:- tags- triggers- schedules

存储库路径可用于仅对父存储库执行作业，而不能用于派生：

job:only:- branches@gitlab-org/gitlabexcept:- master@gitlab-org/gitlab- /^release/.*$/@gitlab-org/gitlab

上面的示例将在上job的所有分支上运行gitlab-org/gitlab，但master名称以开头的分支除外release/。

如果作业没有only规则，only: ['branches', 'tags']则默认设置。如果没有except规则，则为空。

例如，

job:script: echo 'test'

转换为：

job:script: echo 'test'only: ['branches', 'tags']

常用表达

因为@用于表示ref的存储库路径的开头，所以匹配包含@正则表达式中字符的ref名称需要使用十六进制字符代码match \x40。

正则表达式只能匹配标签或分支名称。如果给定存储库路径，则始终在字面上匹配。

如果将使用正则表达式匹配标记或分支名称，则模式的整个ref名称部分必须是正则表达式，并且必须用包围/。（在结束符后附加正则表达式标志/。）因此issue-/.*/无法匹配以开头的所有标记名或分支名issue-。

支持only/正则except表达式语法

在GitLab 11.9.4中，GitLab开始在内部将用于only和except参数的regexp转换为RE2。

这意味着仅 支持Ruby Regexp提供的功能子集。由于计算复杂性，RE2限制了所提供的功能集，这意味着某些功能在GitLab 11.9.4中变得不可用。例如，负面的前瞻。

对于从11.9.7到GitLab 12.0的GitLab版本，GitLab提供了一个功能标记，管理员可以启用它，从而允许用户使用不安全的regexp语法。这带来了与以前允许的语法版本的兼容性，并允许用户正常迁移到新语法。

Feature.enable(:allow_unsafe_ruby_regexp)

only/ except（高级）

GitLab支持简单策略和复杂策略，因此可以使用数组和哈希配置方案。

有四个键可用：

• refs
• variables
• changes
• kubernetes

如果在only或下使用多个键except，则这些键将作为单个联合表达式求值。那是：

• only: 表示“如果所有条件都匹配，则包括此作业”。
• except: 表示“如果满足任何条件，则排除此工作”。

使用only，各个键在逻辑上由AND连接：

（任何参考）AND（任何变量）AND（任何变化）AND（如果Kubernetes是活动的）

在以下示例中，当满足以下所有条件时，test将only创建作业：

• 管道已预定 或正在运行master。
• 该variables关键字匹配。
• 该kubernetes服务在项目上处于活动状态。

test:script: npm run testonly:refs:- master- schedulesvariables:- $CI_COMMIT_MESSAGE =~ /run-end-to-end-tests/kubernetes: active

except 被实现为对此完整表达式的否定：

NOT（（任何参考）AND（任何变量）AND（任何变化）AND（如果Kubernetes处于活动状态））

这意味着将键视为由OR联接。这种关系可以描述为：

（任何参考）或（任何变量）或（任何变化）或（如果Kubernetes处于活动状态）

在以下示例中，如果满足以下任一条件，test则不会创建作业：

• 管道运行在master。
• README.md存储库的根目录中的文件已更改。

test:script: npm run testexcept:refs:- masterchanges:- "README.md"

only:refs/except:refs

该refs策略可以采用与简化的唯一/例外配置相同的值。

在下面的示例中，deploy仅在为分支计划了管道或为管道运行时才创建作业master：

deploy:only:refs:- master- schedules

only:kubernetes/except:kubernetes