GitLab CI / CD管道配置参考 .gitlab-ci.yml文件定义字段

﹏ヽ暗。殇╰゛Y 2023-03-03 11:18 19阅读 0赞

*  亚搏体育app文件
 *  亚搏体育app CI / CD
 *  GitLab CI / CD管道配置参考

# 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 1]，用于配置GitLab Runner。

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

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

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

**注意：** 如果您有一个 从GitLab提取镜像的存储库 ，则可能需要在项目的 **“设置”>“存储库”>“从远程存储库中提取”>“触发管道以进行镜像更新”中** 启用管道触发 。

## 介绍 ##

管道配置从作业开始。作业是`.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`。

## 配置参数 ##

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

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

<table> 
 <thead> 
  <tr> 
   <th>关键词 </th> 
   <th>描述 </th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td><a rel="nofollow"><code>script</code></a> </td> 
   <td>由Runner执行的Shell脚本。 </td> 
  </tr> 
  <tr> 
   <td><a rel="nofollow"><code>image</code></a> </td> 
   <td>使用Docker映像 也可用：<code>image:name</code>和<code>image:entrypoint</code>。 </td> 
  </tr> 
  <tr> 
   <td><a rel="nofollow"><code>services</code></a> </td> 
   <td>使用Docker服务映像。也可用：<code>services:name</code>，<code>services:alias</code>，<code>services:entrypoint</code>，和<code>services:command</code>。 </td> 
  </tr> 
  <tr> 
   <td><a rel="nofollow"><code>before_script</code></a> </td> 
   <td>覆盖作业之前执行的一组命令。 </td> 
  </tr> 
  <tr> 
   <td><a rel="nofollow"><code>after_script</code></a> </td> 
   <td>覆盖作业后执行的一组命令。 </td> 
  </tr> 
  <tr> 
   <td><a rel="nofollow"><code>stage</code></a> </td> 
   <td>定义一个作业阶段（默认值：）<code>test</code>。 </td> 
  </tr> 
  <tr> 
   <td><a rel="nofollow"><code>only</code></a> </td> 
   <td>限制创建作业的时间。也可用：<a rel="nofollow"><code>only:refs</code>，<code>only:kubernetes</code>，<code>only:variables</code>，和<code>only:changes</code></a>。 </td> 
  </tr> 
  <tr> 
   <td><a rel="nofollow"><code>except</code></a> </td> 
   <td>限制未创建作业的时间。也可用：<a rel="nofollow"><code>except:refs</code>，<code>except:kubernetes</code>，<code>except:variables</code>，和<code>except:changes</code></a>。 </td> 
  </tr> 
  <tr> 
   <td><a rel="nofollow"><code>rules</code></a> </td> 
   <td>评估和确定作业的选定属性以及是否创建作业的条件列表。不能与<code>only</code>/ 一起使用<code>except</code>。 </td> 
  </tr> 
  <tr> 
   <td><a rel="nofollow"><code>tags</code></a> </td> 
   <td>用于选择Runner的标签列表。 </td> 
  </tr> 
  <tr> 
   <td><a rel="nofollow"><code>allow_failure</code></a> </td> 
   <td>允许作业失败。失败的作业不会影响提交状态。 </td> 
  </tr> 
  <tr> 
   <td><a rel="nofollow"><code>when</code></a> </td> 
   <td>什么时候开始工作。也可用：<code>when:manual</code>和<code>when:delayed</code>。 </td> 
  </tr> 
  <tr> 
   <td><a rel="nofollow"><code>environment</code></a> </td> 
   <td>作业部署到的环境的名称。也可用：<code>environment:name</code>，<code>environment:url</code>，<code>environment:on_stop</code>，<code>environment:auto_stop_in</code>和<code>environment:action</code>。 </td> 
  </tr> 
  <tr> 
   <td><a rel="nofollow"><code>cache</code></a> </td> 
   <td>在后续运行之间应缓存的文件列表。也可用：<code>cache:paths</code>，<code>cache:key</code>，<code>cache:untracked</code>，和<code>cache:policy</code>。 </td> 
  </tr> 
  <tr> 
   <td><a rel="nofollow"><code>artifacts</code></a> </td> 
   <td>成功时附加到作业的文件和目录列表。也可用：<code>artifacts:paths</code>，<code>artifacts:exclude</code>，<code>artifacts:expose_as</code>，<code>artifacts:name</code>，<code>artifacts:untracked</code>，<code>artifacts:when</code>，<code>artifacts:expire_in</code>，<code>artifacts:reports</code>，<code>artifacts:reports:codequality</code>，<code>artifacts:reports:junit</code>，<code>artifacts:reports:cobertura</code>，和<code>artifacts:reports:terraform</code>。<br><br>在GitLab <a href="https://about.gitlab.com/pricing/" rel="nofollow">企业版</a>，这些都是可供选择：<code>artifacts:reports:sast</code>，<code>artifacts:reports:dependency_scanning</code>，<code>artifacts:reports:container_scanning</code>，<code>artifacts:reports:dast</code>，<code>artifacts:reports:license_scanning</code>，<code>artifacts:reports:license_management</code>（在GitLab 13.0删除）， ，<code>artifacts:reports:performance</code>，<code>artifacts:reports:load_performance</code>和<code>artifacts:reports:metrics</code>。 </td> 
  </tr> 
  <tr> 
   <td><a rel="nofollow"><code>dependencies</code></a> </td> 
   <td>通过提供要从中获取工件的作业列表，限制将哪些工件传递给特定作业。 </td> 
  </tr> 
  <tr> 
   <td><a rel="nofollow"><code>coverage</code></a> </td> 
   <td>给定作业的代码覆盖率设置。 </td> 
  </tr> 
  <tr> 
   <td><a rel="nofollow"><code>retry</code></a> </td> 
   <td>发生故障时可以自动重试作业的时间和次数。 </td> 
  </tr> 
  <tr> 
   <td><a rel="nofollow"><code>timeout</code></a> </td> 
   <td>定义优先于项目范围设置的自定义作业级别超时。 </td> 
  </tr> 
  <tr> 
   <td><a rel="nofollow"><code>parallel</code></a> </td> 
   <td>多少个作业实例应并行运行。 </td> 
  </tr> 
  <tr> 
   <td><a rel="nofollow"><code>trigger</code></a> </td> 
   <td>定义下游管道触发器。 </td> 
  </tr> 
  <tr> 
   <td><a rel="nofollow"><code>include</code></a> </td> 
   <td>允许此作业包括外部YAML文件。也可用：<code>include:local</code>，<code>include:file</code>，<code>include:template</code>，和<code>include:remote</code>。 </td> 
  </tr> 
  <tr> 
   <td><a rel="nofollow"><code>extends</code></a> </td> 
   <td>该作业将要继承的配置条目。 </td> 
  </tr> 
  <tr> 
   <td><a rel="nofollow"><code>pages</code></a> </td> 
   <td>上载作业结果以用于GitLab页面。 </td> 
  </tr> 
  <tr> 
   <td><a rel="nofollow"><code>variables</code></a> </td> 
   <td>在作业级别上定义作业变量。 </td> 
  </tr> 
  <tr> 
   <td><a rel="nofollow"><code>interruptible</code></a> </td> 
   <td>定义在通过新的运行使其冗余时是否可以取消作业。 </td> 
  </tr> 
  <tr> 
   <td><a rel="nofollow"><code>resource_group</code></a> </td> 
   <td>限制作业并发。 </td> 
  </tr> 
  <tr> 
   <td><a rel="nofollow"><code>release</code></a> </td> 
   <td>指示Runner生成<a rel="nofollow">Release</a>对象。 </td> 
  </tr> 
 </tbody> 
</table>

**注：** 参数 `types` 和 `type` 被 弃用 。

## 全局参数 ##

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

### 全局默认值 ###

可以使用`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.6
      script: bundle exec rspec

#### `inherit` ####

在GitLab 12.9中[引入][Link 2]。

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

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

*  `default: true` 要么 `default: false`
 *  `variables: true` 要么 `variables: false`

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

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

要么：

inherit:
      default:
        - parameter1
        - parameter2
      variables:
        - 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.com
      WEBHOOK_URL: https://my-webhook.example.com
    
    rubocop:
      inherit:
        default: false
        variables: false
      script: bundle exec rubocop
    
    rspec:
      inherit:
        default: [image]
        variables: [WEBHOOK_URL]
      script: bundle exec rspec
    
    capybara:
      inherit:
        variables: false
      script: bundle exec capybara
    
    karma:
      inherit:
        default: true
        variables: [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` ###

在GitLab 12.5中 [引入][Link 3]

顶级`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中定义的一样，请注意不要使用允许合并请求管道和分支管道同时运行的配置，否则您可能会有重复的管道。

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

<table> 
 <thead> 
  <tr> 
   <th>条款 </th> 
   <th>细节 </th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td><code>if: '$CI_PIPELINE_SOURCE == "merge_request_event"'</code> </td> 
   <td>允许或阻止合并请求管道。 </td> 
  </tr> 
  <tr> 
   <td><code>if: '$CI_PIPELINE_SOURCE == "push"'</code> </td> 
   <td>允许或阻止分支管道和标记管道。 </td> 
  </tr> 
  <tr> 
   <td><code>if: '$CI_COMMIT_BEFORE_SHA == '0000000000000000000000000000000000000000'</code> </td> 
   <td>在没有提交的情况下创建或推送新分支时，允许或阻止管道创建。这还将跳过标记和计划的管道。有关如何更严格定义这些规则的示例，请参见<a rel="nofollow">常见<code>rules:if</code>条款</a>。 </td> 
  </tr> 
 </tbody> 
</table>

#### `workflow:rules` 范本 ####

在GitLab 13.0中[引入][Link 4]。

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

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

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

它包括以下内容：

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

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

它包括以下内容：

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

### `include` ###

版本历史

*  Introduced in [GitLab Premium][] 10.5.
 *  Available for Starter, Premium and Ultimate since 10.6.
 *  [Moved][] to GitLab Core in 11.4.

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

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

`include` 支持以下包含方法：

<table> 
 <thead> 
  <tr> 
   <th>方法 </th> 
   <th>描述 </th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td><a rel="nofollow"><code>local</code></a> </td> 
   <td>包括来自本地项目存储库的文件。 </td> 
  </tr> 
  <tr> 
   <td><a rel="nofollow"><code>file</code></a> </td> 
   <td>包括来自其他项目存储库的文件。 </td> 
  </tr> 
  <tr> 
   <td><a rel="nofollow"><code>remote</code></a> </td> 
   <td>包括来自远程URL的文件。必须公开可用。 </td> 
  </tr> 
  <tr> 
   <td><a rel="nofollow"><code>template</code></a> </td> 
   <td>包括由GitLab提供的模板。 </td> 
  </tr> 
 </tbody> 
</table>

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

**注意：** `.gitlab-ci.yml` 所有方法包括的配置都是在管道创建时评估的。该配置是及时的快照，并保留在数据库中。 `.gitlab-ci.yml` 在创建下一个管道之前，对引用配置的任何更改都不会反映在GitLab中。

定义的文件`include`为：

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

**提示：** 使用合并功能可以自定义和覆盖包含本地定义的CI / CD配置。中的本地定义 `.gitlab-ci.yml` 将覆盖包含的定义。

**注意：** 不支持在来源不同的YAML文件之间 使用 YAML锚 `include` 。您只能引用同一文件中的锚。您可以使用 `extends`关键字 而不是使用YAML锚。

#### `include:local` ####

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

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

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

**注意：** 不支持通过Git子模块路径包含本地文件。

例：

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

**提示：** 本地包含可以代替未遵循的符号链接。

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

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

#### `include:file` ####

在GitLab 11.7中[引入][Link 5]。

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

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

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

include:
      - project: 'my-group/my-project'
        ref: master
        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:remote` ####

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

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

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

#### `include:template` ####

在GitLab 11.7中[引入][Link 6]。

`include:template`可用于包括[GitLab随附的][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

所有嵌套的包含将仅在用户许可下执行，因此可以使用项目，远程或模板包含。

#### 嵌套包含 ####

在GitLab 11.9中[引入][Link 7]。

嵌套包含可让您组成一组包含。

总共允许100个include，但是重复的include被视为配置错误。

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

#### 其他`includes`例子 ####

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

## 参数详细 ##

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

### `image` ###

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

对于：

*  简单的定义示例，请参见Define `image`and `services`from`.gitlab-ci.yml`。
 *  详细的使用信息，请参阅Docker集成文档。

#### `image:name` ####

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

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

#### `image:entrypoint` ####

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

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

#### `services` ####

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

对于：

*  简单的定义示例，请参见Define `image`and `services`from`.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

**注意：** 有时， `script` 命令将需要用单引号或双引号引起来。例如，包含冒号（ `:` ）的命令需要用引号引起来，以便YAML解析器知道将整个内容解释为字符串而不是“键：值”对。使用特殊字符时要小心： `:` ， `{` ， `}` ， `[` ， `]` ， `,` ， `&` ， `*` ， `#` ， `?` ， `|` ， `-` ， `<` ， `>` ， `=` ， `!` ， `%` ， `@` ， `` ` `` 。

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

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

#### `before_script` 和 `after_script` ####

在GitLab 8.7中引入，需要GitLab Runner v1.2。

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

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

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

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

*  将当前工作目录设置回默认目录。
 *  无法访问由`before_script`或定义的脚本所做的更改`script`，包括：
    
     *  在`script`脚本中导出的命令别名和变量。
     *  在工作树之外进行更改（取决于Runner执行程序），例如由`before_script`或`script`脚本安装的软件。
 *  有一个单独的超时，硬编码为5分钟。有关详细信息，请参见 [相关问题][Link 8]。
 *  不要影响作业的退出代码。如果该`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 script
      script:
        - my command
      after_script:
        - execute this after my script

YAML锚`before_script`和`after_script`可用。

#### 着色脚本输出 ####

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

例如，使用[带有颜色代码的Bash][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颜色代码][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]将长命令分成多行命令以提高可读性。

**警告：** 如果将多个命令组合到一个命令字符串中，则只会报告最后一个命令的失败或成功， [错误地忽略了由于bug导致的先前命令的失败][bug] 。如果作业的成功取决于这些命令的成功或失败，则可以将命令作为单独的 `script:` 项目运行，或者 `exit 1` 在需要时将适当的命令添加到命令字符串中。

您可以使用`|`（文字上的）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 line
          is split over two lines."
    
          echo "Second command line."

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

job:
      script:
        - echo "First command line
          is 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将通过连接非空行来形成命令，因此请确保在连接时行可以运行。

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

job:
      script:
        - |
          tr a-z A-Z << END_TEXT
            one two three
            four five six
          END_TEXT

结果是：

$ tr a-z A-Z << END_TEXT # collapsed multi-line command ONE TWO THREE FOUR FIVE SIX

### `stage` ###

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

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

#### 使用自己的跑步者 ####

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

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

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

#### `.pre` 和 `.post` ####

在GitLab 12.4中[引入][Link 10]。

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

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

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

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

*  按顺序配置：
    
        stages:
          - .pre
          - a
          - b
          - .post
 *  配置乱序：
    
        stages:
          - a
          - .pre
          - b
          - .post
 *  未明确配置：
    
        stages:
          - a
          - b

**注意：** 如果管道仅包含 `.pre` 或 `.post` 阶段中的作业，则不会创建管道。

### `extends` ###

在GitLab 11.3中引入。

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

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

.tests:
      script: rake test
      stage: test
      only:
        refs:
          - branches
    
    rspec:
      extends: .tests
      script: rake rspec
      only:
        variables:
          - $RSPEC

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

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

这将导致以下`rspec`工作：

rspec:
      script: rake rspec
      stage: test
      only:
        refs:
          - branches
        variables:
          - $RSPEC

**注意：** 请注意 `script: rake test` 已被覆盖 `script: rake rspec` 。

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

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

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

.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

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

#### 合并细节 ####

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

.only-important:
      variables:
        URL: "http://my-url.internal"
        IMPORTANT_VAR: "the details"
      only:
        - master
        - 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:
        - master
        - stable
      tags:
        - docker
      image: alpine
      script:
        - 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: alpine
      extends: .template

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

### `rules` ###

在GitLab 12.3中[引入][Link 11]。

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

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

**注意：** `rules` 不能与之组合使用， `only/except` 因为它是该功能的替代品。如果尝试执行此操作，则linter返回 `key may not be used with 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: delayed
          start_in: '3 hours'
          allow_failure: true

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

#### 规则条款 ####

可用的规则子句为：

<table> 
 <thead> 
  <tr> 
   <th>条款 </th> 
   <th>描述 </th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td><a rel="nofollow"><code>if</code></a> </td> 
   <td>通过评估一条<code>if</code>语句在管道中添加或排除作业。类似于<a rel="nofollow"><code>only:variables</code></a>。 </td> 
  </tr> 
  <tr> 
   <td><a rel="nofollow"><code>changes</code></a> </td> 
   <td>根据更改的文件在管道中添加或排除作业。与相同<a rel="nofollow"><code>only:changes</code></a>。 </td> 
  </tr> 
  <tr> 
   <td><a rel="nofollow"><code>exists</code></a> </td> 
   <td>根据特定文件的存在在管道中添加或排除作业。 </td> 
  </tr> 
 </tbody> 
</table>

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

*  `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: manual
          allow_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`。

**注意：** 如果使用 `when: on_success` ， `always` 或 `delayed` 作为最终规则，则可能同时启动两个管道。推送管道和合并请求管道都可以由同一事件触发（对于打开的合并请求，将其推送到源分支）。见 之间的重要区别`rules`和`only`/`except` 了解更多详情。

#### `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: manual
          allow_failure: true
        - if: '$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME' # Checking for the presence of a variable is possible

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

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

##### 通用`if`条款`rules` #####

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

<table> 
 <thead> 
  <tr> 
   <th>值 </th> 
   <th>描述 </th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td><code>push</code> </td> 
   <td>对于<code>git push</code>事件触发的管道，包括分支和标签。 </td> 
  </tr> 
  <tr> 
   <td><code>web</code> </td> 
   <td>对于使用GitLab UI中的<strong>“运行管道”</strong>按钮创建的<strong>管道</strong>，请从项目的<strong>CI / CD&gt;“管道”</strong>部分。 </td> 
  </tr> 
  <tr> 
   <td><code>trigger</code> </td> 
   <td>对于使用触发令牌创建的管道。 </td> 
  </tr> 
  <tr> 
   <td><code>schedule</code> </td> 
   <td>对于<a rel="nofollow">预定的管道</a>。 </td> 
  </tr> 
  <tr> 
   <td><code>api</code> </td> 
   <td>对于由<a rel="nofollow">管道API</a>触发的<a rel="nofollow">管道</a>。 </td> 
  </tr> 
  <tr> 
   <td><code>external</code> </td> 
   <td>使用除GitLab以外的CI服务时。 </td> 
  </tr> 
  <tr> 
   <td><code>pipeline</code> </td> 
   <td>对于通过结合<a rel="nofollow">使用API<code>CI_JOB_TOKEN</code></a>创建的多项目管道。 </td> 
  </tr> 
  <tr> 
   <td><code>chat</code> </td> 
   <td>对于使用<a rel="nofollow">GitLab ChatOps</a>命令创建的管道。 </td> 
  </tr> 
  <tr> 
   <td><code>webide</code> </td> 
   <td>对于使用<a rel="nofollow">WebIDE</a>创建的管道。 </td> 
  </tr> 
  <tr> 
   <td><code>merge_request_event</code> </td> 
   <td>对于在创建或更新合并请求时创建的管道。启用<a rel="nofollow">合并请求管道</a>，<a rel="nofollow">合并结果管道</a>和<a rel="nofollow">合并序列所</a>必需。 </td> 
  </tr> 
  <tr> 
   <td><code>external_pull_request_event</code> </td> 
   <td>在GitHub上创建或更新外部拉取请求时。有关<a rel="nofollow">外部拉取请求，</a>请参见<a rel="nofollow">管道</a>。 </td> 
  </tr> 
  <tr> 
   <td><code>parent_pipeline</code> </td> 
   <td>对于由触发管道<a rel="nofollow">父/子管道</a>用<code>rules</code>，在孩子管道配置使用，以便它可以由父母管道被触发。 </td> 
  </tr> 
 </tbody> 
</table>

例如：

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

本示例将作业作为合并请求管道 和计划管道中的`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:
            - Dockerfile
          when: manual
          allow_failure: true

在此示例中：

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

##### `rules:exists` #####

在GitLab 12.4中[引入][Link 13]。

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

例如：

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

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

例如：

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

**注意：** 出于性能原因， `exists` 与模式一起使用限制为10000个检查。第10000次检查后，带有图案化球形的规则将始终匹配。

##### `rules:allow_failure` #####

在GitLab 12.8中[引入][Link 14]。

您可以`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: manual
          allow_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`][rules]中正在讨论未来的关键字改进，[以改进][rules]，任何人都可以添加建议或请求。

### `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`允许使用特殊关键字：

<table> 
 <thead> 
  <tr> 
   <th><strong>值</strong> </th> 
   <th><strong>描述</strong> </th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td><code>branches</code> </td> 
   <td>当管道的Git参考是分支时。 </td> 
  </tr> 
  <tr> 
   <td><code>tags</code> </td> 
   <td>当管道的Git参考是标签时。 </td> 
  </tr> 
  <tr> 
   <td><code>api</code> </td> 
   <td>对于由<a rel="nofollow">管道API</a>触发的<a rel="nofollow">管道</a>。 </td> 
  </tr> 
  <tr> 
   <td><code>external</code> </td> 
   <td>使用除GitLab以外的CI服务时。 </td> 
  </tr> 
  <tr> 
   <td><code>pipelines</code> </td> 
   <td>对于通过结合使用API创建的多项目管道<code>CI_JOB_TOKEN</code>。 </td> 
  </tr> 
  <tr> 
   <td><code>pushes</code> </td> 
   <td>对于<code>git push</code>事件触发的管道，包括分支和标签。 </td> 
  </tr> 
  <tr> 
   <td><code>schedules</code> </td> 
   <td>对于<a rel="nofollow">预定的管道</a>。 </td> 
  </tr> 
  <tr> 
   <td><code>triggers</code> </td> 
   <td>对于使用触发令牌创建的管道。 </td> 
  </tr> 
  <tr> 
   <td><code>web</code> </td> 
   <td>对于使用GitLab UI中的<strong>“运行管道”</strong>按钮创建的<strong>管道</strong>，请从项目的<strong>CI / CD&gt;“管道”</strong>部分。 </td> 
  </tr> 
  <tr> 
   <td><code>merge_requests</code> </td> 
   <td>对于在创建或更新合并请求时创建的管道。启用<a rel="nofollow">合并请求管道</a>，<a rel="nofollow">合并结果管道</a>和<a rel="nofollow">合并序列</a>。 </td> 
  </tr> 
  <tr> 
   <td><code>external_pull_requests</code> </td> 
   <td>在GitHub上创建或更新<a rel="nofollow">外部拉取请求时</a>（有关<a rel="nofollow">外部拉取请求，</a>请参见<a rel="nofollow">管道</a>）。 </td> 
  </tr> 
  <tr> 
   <td><code>chat</code> </td> 
   <td>对于使用<a rel="nofollow">GitLab ChatOps</a>命令创建的管道。 </td> 
  </tr> 
 </tbody> 
</table>

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

job:
      # use regexp
      only:
        - /^issue-.*$/
      # use special keyword
      except:
        - branches

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

job:
      # use regexp
      only:
        - /^issue-.*$/i
      # use special keyword
      except:
        - branches

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

job:
      # use special keywords
      only:
        - tags
        - triggers
        - schedules

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

job:
      only:
        - branches@gitlab-org/gitlab
      except:
        - 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-`。

**提示：** 使用定位符 `^` 和 `$` 避免正则表达式仅匹配标记名称或分支名称的子字符串。例如， `/^issue-.*$/` 等于 `/^issue-/` ，而just `/issue/` 还要匹配名为的分支 `severe-issues` 。

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

**警告：** 这是GitLab 11.9.4引入的重大更改。

在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`（高级） ###

**警告：** 这是 *Alpha版* 功能，如有更改，恕不另行通知！

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

有四个键可用：

*  `refs`
 *  `variables`
 *  `changes`
 *  `kubernetes`

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

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

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

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

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

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

test:
      script: npm run test
      only:
        refs:
          - master
          - schedules
        variables:
          - $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 test
      except:
        refs:
          - master
        changes:
          - "README.md"

#### `only:refs`/`except:refs` ####

`refs` GitLab 10.0中引入的策略。

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

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

deploy:
      only:
        refs:
          - master
          - schedules

#### `only:kubernetes`/`except:kubernetes` ####

`kubernetes` GitLab 10.0中引入的策略。

[GitLab Runner]: https://docs.gitlab.com/runner/
[GitLab Runner 1]: https://docs.gitlab.com/runner/configuration/advanced-configuration.html
[.gitlab-ci.yml_gitlab]: https://gitlab.com/gitlab-org/gitlab/blob/master/.gitlab-ci.yml
[CI _ CD]: https://www.youtube.com/embed/opdLqwz6tcE
[Link 1]: https://about.gitlab.com/compare/github-actions-alternative/
[Verizon]: https://about.gitlab.com/blog/2019/02/14/verizon-customer-story/
[Link 2]: https://gitlab.com/gitlab-org/gitlab/-/issues/207484
[Link 3]: https://gitlab.com/gitlab-org/gitlab/-/issues/29654
[Link 4]: https://gitlab.com/gitlab-org/gitlab/-/issues/217732
[Branch-Pipelines]: https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/gitlab/ci/templates/Workflows/Branch-Pipelines.gitlab-ci.yml
[MergeRequest-Pipelines]: https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/gitlab/ci/templates/Workflows/MergeRequest-Pipelines.gitlab-ci.yml
[GitLab Premium]: https://about.gitlab.com/pricing/
[Moved]: https://gitlab.com/gitlab-org/gitlab-foss/-/issues/42861
[Link 5]: https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53903
[Link 6]: https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53445
[GitLab]: https://gitlab.com/gitlab-org/gitlab/tree/master/lib/gitlab/ci/templates
[Link 7]: https://gitlab.com/gitlab-org/gitlab-foss/-/issues/56836
[GitLab 12.4]: https://gitlab.com/gitlab-org/gitlab/-/issues/28212
[Link 8]: https://gitlab.com/gitlab-org/gitlab-runner/-/issues/2716
[ANSI]: https://en.wikipedia.org/wiki/ANSI_escape_code#Colors
[Bash]: https://misc.flogisoft.com/bash/tip_colors_and_formatting
[PowerShell]: https://superuser.com/a/1259916
[YAML]: https://yaml-multiline.info/
[bug]: https://gitlab.com/gitlab-org/gitlab-runner/-/issues/25394
[Link 9]: https://en.wikipedia.org/wiki/Here_document
[Runner]: https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-global-section
[Link 10]: https://gitlab.com/gitlab-org/gitlab/-/issues/31441
[Link 11]: https://gitlab.com/gitlab-org/gitlab/-/issues/27863
[Link 12]: https://gitlab.com/gitlab-org/gitlab/-/issues
[Link 13]: https://gitlab.com/gitlab-org/gitlab/-/issues/24021
[Link 14]: https://gitlab.com/gitlab-org/gitlab/-/issues/30235
[rules]: https://gitlab.com/groups/gitlab-org/-/epics/2783
[RE2]: https://github.com/google/re2/wiki/Syntax
[Ruby Regexp]: https://ruby-doc.org/core/Regexp.html