gitlab-ci.yml关键字整理(转载)

[toc]

Gitlab CI/CD 管道配置参考

在每个项目中，使用名为.gitlab-ci.yml 的 yaml 文件配置 Gitlab CI/CD 管道。

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

使用 Gitlab Runner 执行什么。

遇到特殊情况时要做什么决定？例如，当一个进程成功或失败时。

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

Gitlab CI/CD 变量，用于配置管道运行的环境。

Gitlab Runner 高级配置，用于配置 Gitlab Runner。

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

要快速介绍 Gitlab CI，请遵循我们的快速入门指南。

有关示例的集合，请参见 Gitlab CI/CD 示例。

要查看企业中使用的大型.gitlab-ci.yml 文件，请参见 gitlab ce 的.gitlab-ci.yml 文件。

如果你有一个镜像存储库，其中有 gitlab，你可能需要在项目的 Settings > Repository > Pull from a remote repository > Trigger 镜像更新管道。

1. 介绍

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

工作包括：

定义了在什么条件下应该执行它们的约束。

具有任意名称的顶级元素，必须至少包含 script 子句。

不限于可定义的数量。

例如：

YML
job1:
  script: "execute-script-for-job1"
job2:
  script: "execute-script-for-job2"

上面的示例是最简单的 CI/CD 配置，有两个独立的 job，其中每个 job 执行不同的命令。当然，命令可以直接执行代码（./configure；make；make install）或者在存储库中运行 script（test.sh）。
工作由 Runners 挑选并在 Runner 的环境。重要的是，每个 job 都在运行彼此独立。

2. 验证 .gitlab-ci.yml

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

3. Unavailable names for jobs

每个 job 必须有一个唯一的名称，但有一些保留的关键字不能用作 job 名称：

YML
image
services
stages
types
before_script
after_script
variables
cache

4. 使用保留关键字

如果在使用特定值（例如，true or false）时出现验证错误，请尝试：

–引用它们。

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

5. 配置参数

job 定义为定义 job 行为的参数列表。

下表列出了 job 的可用参数：

Keyword	描述
script	由运行程序执行的 shell 脚本。
image	使用 Docker 图像。还提供：image:name 和 image:entrypoint。
services	使用 Docker 服务图像。还提供：services:name、services:alias、services:entrypoint 和 services:command。
before_script	重写在 job 之前执行的一组命令。
after_script	重写在 job 后执行的一组命令。
stages	定义管道中的阶段。
stage	定义 job 阶段（default: test）。
only	限制创建 when jobs。还可用：only：refs，only：kubernetes，only：variables，only：changes。
except	限制未创建 when jobs。还可用：except:refs，except:kubernetes，except:variables 和 except:changes。
tags	用于选择运行程序的标记列表。
allow_failure	允许 job 失败。失败的 job 不影响提交状态。
when	何时运行 job。还可用：when:manual and when:delayed。
environment	job 部署到的环境的名称。还可用：environment:name, environment:url, environment:on_stop, and environment:action.
cache	在后续运行之间应缓存的文件列表。还可用：cache:paths, cache:key, cache:untracked, and cache:policy.。
artifacts	成功时要附加到 job 的文件和目录列表。还可用：artifacts:paths, artifacts:name, artifacts:untracked, artifacts:when, artifacts:expire_in, artifacts:reports, and artifacts:reports:junit。在 Gitlab 企业版中，这些可用：artifacts:reports:codequality, artifacts:reports:sast, artifacts:reports:dependency_scanning, artifacts:reports:container_scanning, artifacts:reports:dast, artifacts:reports:license_management, artifacts:reports:performance and artifacts:reports:metrics。
dependencies	job 所依赖的其他 job，以便在它们之间传递 artifacts。
coverage	给定 job 的代码覆盖率设置。
retry	如果出现故障，一个 job 可以自动重试的时间和次数。
parallel	一个 job 应并行运行多少个实例。
trigger	定义下游管道触发器。
include	允许此 job 包含外部 yaml 文件。还提供：include:local、include:file、include:template 和 include:remote。
extends	此 job 将从中继承的配置项。
pages	上载 job 的结果以用于 Gitlab 页面。
variables	在 job 级别定义 job 变量。

NOTE: Note:Parameters types and type are deprecated.(弃用)

6. 设置默认参数

某些参数可以全局设置为所有 job 的默认值，使用默认值：关键字。然后，默认参数可以被特定于 job 的参数覆盖配置。

可以在默认块内定义以下 job 参数：

YML
image
services
before_script
after_script
cache

在下面的示例中，ruby:2.5 图像被设置为所有图像的默认值。job，rspec 2.6job 除外，它使用 ruby:2.6 映像：

YML
default:
  image: ruby:2.5

rspec:
  script: bundle exec rspec

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

7. 参数详细信息

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

7.1. script

script 是 job 所需的唯一关键字。这是一个 shellscript 由运行程序执行。例如：

1
2
3

YML
job:
  script: "bundle exec rspec"

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

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

有时，script 命令需要用单引号或双引号括起来。例如，包含冒号（：）的命令需要用引号括起来，因此 yaml 解析器知道将整个事件解释为字符串而不是 “key:value” 对。使用特殊字符时要小心:
:, {, }, [, ], ,, &, *, #, ?, |, -, <, >, =, !, %, @, `.

7.2. image

用于指定要用于 job 的 Docker 映像。

用于：

简单定义示例，请参见从.gitlab-ci.yml 定义图像和服务。

详细使用信息，请参阅 Docker 集成文档。

image:name

扩展 Docker 配置选项。

有关详细信息，请参阅图像的可用设置。

image:entrypoint

扩展 Docker 配置选项。

有关详细信息，请参阅图像的可用设置。

7.3. services

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

用于：

简单定义示例，请参见从.gitlab-ci.yml 定义图像和服务。

详细使用信息，请参阅 Docker 集成文档。

例如服务，请参见 Gitlab CI Services。

services:name

扩展 Docker 配置选项。有关详细信息，请参阅 “服务的可用设置”。

services:alias

扩展 Docker 配置选项。有关详细信息，请参阅 “服务的可用设置”。

services:entrypoint

扩展 Docker 配置选项。有关详细信息，请参阅 “服务的可用设置”。

services:command

扩展 Docker 配置选项。有关详细信息，请参阅 “服务的可用设置”。

7.4. before_script / after_script

before_script 用于定义应在所有命令之前运行的命令 job，包括部署 job，但在恢复 artifacts 之后。这可以是一个数组或多行字符串。

after_script 用于定义将要运行的命令 job，包括失败的 job。这必须是一个数组或多行字符串。

在 before_script 指定的 script 是：

与主 script 中指定的 script 连接。工作级别在 script 定义之前覆盖全局级别在 script 定义之前与 script 定义连接时。

与主 scriptscript 一起在单个 shell 中作为一个 script 执行上下文。

after_script 指定的 script：

将当前工作目录设置回默认值。

在与 script 和 script 之前分开的 shell 上下文中执行 script。

由于上下文分隔，无法查看定义的 script 所做的更改在 “script” 或 “before_script”，请执行以下操作之一：

在外壳中。例如，script 中导出的命令别名和变量 script。

在工作树之外（取决于运行者执行者）。例如，由 before_script 或 scriptscript 安装的软件。

可以覆盖在 script 之前和之后定义的全局，如果按 job 设置：

YML
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

7.5. stages

stages 用于全局定义 job 可以使用的阶段

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

同一阶段的 job 并行运行。

下一阶段的 job 在上一阶段的 job 之后运行成功完成。

让我们考虑下面的例子，它定义了 3 个阶段：

YML
stages:
  - build
  - test
  - deploy

首先，build 的所有 job 都是并行执行的。

如果 build 的所有 job 都成功，则 test job 将并行执行。

如果 test 的所有 job 都成功，则 deploy job 将并行执行。

如果 Deploy 的所有 job 都成功，则提交标记为通过。

如果以前的任何 job 失败，提交将标记为失败，并且不

执行下一阶段的工作。

还有两个边缘案例值得一提：

如果在.gitlab-ci.yml 中没有定义阶段，默认情况下，build, test and deploy 用作 job 的阶段。

如果 job 未指定阶段，则该 job 将被分配到 test 阶段。

7.6. stage

stage 是定义单个 job，并依赖于全局的 stages。它允许将 job 分组到不同的阶段，并且相同的 job 阶段是并行执行的（取决于某些条件）。例如：

YML
stages:
  - build
  - test
  - deploy

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

Using your own Runners

使用自己的运行程序时，默认情况下，Gitlab 运行程序一次只运行一个 job（请参见运行程序全局设置中的并发标志）。

只有在以下情况下，job 才会并行运行：

在不同程序上运行

运行程序的并发设置已更改。

7.7. only/except (basic)

only 和 except 两个参数将 job 策略设置为限制创建的 job：

only 定义要为其运行 job 的分支和标记的名称。

except 定义排除的 job

有一些规则适用于 job 策略的使用：

only 和 except 是包容性的。如果只定义 only 和 except 在 job 规范中，引用 only 由和 except。

only 和 except 允许使用正则表达式（支持的 regexp 语法）。

only 和 except 允许指定用于筛选 job 的存储库路径分支。

此外，only 和 except 情况允许使用特殊关键字：

Value	描述
branches	当管道的 Git 引用是分支时。
tags	当管道的 Git 引用是标记时。
api	当管道被第二个管道 API 触发时（而不是触发 API）。
external	使用 Gitlab 以外的 CI 服务时。
pipelines	对于多项目触发器，使用带有 CI_JOB_TOKEN 的 API 创建的。
pushes	管道由用户的 git push 触发。
schedules	用于计划的管道。
triggers	用于使用触发器标记创建的管道。
web	对于使用 Gitlab UI 中的 “运行管道” 按钮创建的管道（在项目的管道下）。
merge_requests	创建或更新合并请求时（有关合并请求，请参阅管道）。
chats	对于使用 gitlab chatops 命令创建的 job。

在下面的示例中，job 将仅对以问题 - 开头的引用运行，鉴于将跳过所有分支：

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

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

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

在本例中，job 将仅对标记的引用运行，或者如果通过 API 触发器或管道计划显式请求生成：

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

存储库路径只能用于执行父存储库的 job，而不能用于分叉：

YML
job:
  only:
    - branches@gitlab-org/gitlab-ce
  except:
    - master@gitlab-org/gitlab-ce
    - /^release/.*$/@gitlab-org/gitlab-ce

上面的示例将为 gitlab-org/gitlab-ce 上的所有分支运行 job，master 和以 release / 作为前缀的分支除外。

only 默认值：’’branches’、’tags’]

except 默认值为空。

例如，

1
2
3

YML
job:
  script: echo 'test'

转换为：

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

Regular expressions

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

只有标记或分支名称才能与正则表达式匹配。如果给定存储库路径，则始终按字面匹配。

如果使用正则表达式来匹配标记或分支名称，模式的整个引用名称部分必须是正则表达式，必须用 / 包围。（在结束 / 后附加正则表达式标志）因此，问题 -/.*/ 无法匹配所有标记名或分支名从问题开始。

使用锚 ^ 和 $ 避免正则表达式只匹配标记名或分支名的子字符串。例如，/^issue-.$/ 等于 /^issue-/，而 just/issue/ 也将匹配一个称为严重问题的分支。

Supported only/except regexp syntax

警告：警告：这是 Gitlab 11.9.4 引入的突破性变化。

在 Gitlab 11.9.4 中，Gitlab 开始内部转换使用的 regexp 仅限 RE2 和 RE2 的参数。

这意味着只有 RubyRegexp 提供的特性的子集支持。RE2 限制了功能集由于计算的复杂性，这意味着一些特性在 Gitlab 11.9.4 中变得不可用。例如，负数 lookaheads。

对于 11.9.7 到 Gitlab 12.0 的 Gitlab 版本，Gitlab 提供了一个可以由管理员启用，允许用户使用不安全的 regexp 语法。这带来了兼容性使用以前允许的语法版本，并允许用户优雅地迁移到新语法。

1 2	YML Feature.enable(:allow_unsafe_ruby_regexp)

7.8. only/except (advanced) 高级

警告：警告：这是一个 alpha 功能，随时可能更改，恕不另行通知！

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

有四把钥匙：

YML
refs
variables
changes
kubernetes

If you use multiple keys under only or except, they act as an AND. The logic is:

(any of refs) AND (any of variables) AND (any of changes) AND (if kubernetes is active)

only:refs/except:refs

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

在下面的示例中，只有在为主分支计划管道或运行管道时，才会创建部署 job：

YML
deploy:
  only:
    refs:
      - master
      - schedules

only:kubernetes/except:kubernetes

kubernetes 策略只接受活动关键字。

在下面的示例中，只有当项目中的 kubernetes 服务处于活动状态时，才会创建部署 job：

YML
deploy:
  only:
    kubernetes: active

only:variables/except:variables

variables 关键字用于定义变量表达式。换句话说，您可以使用预定义的变量 /project/group 或环境范围的变量来定义一个表达式 gitlab 将要评估，以决定是否应该创建一个 job。

使用变量表达式的示例：

YML
deploy:
  script: cap staging deploy
  only:
    refs:
      - branches
    variables:
      - $RELEASE == "staging"
      - $STAGING

另一个用例是根据提交消息排除 job：

YML
end-to-end:
  script: rake test:end-to-end
  except:
    variables:
      - $CI_COMMIT_MESSAGE =~ /skip-end-to-end-tests/

Learn more about variables expressions.

only:changes/except:changes

使用 changes 关键字 only 或 except 可以定义是否应基于 Git push 事件修改的文件创建 job。

For example:

YML
docker build:
  script: docker build -t my-image:$CI_COMMIT_REF_SLUG .
  only:
    changes:
      - Dockerfile
      - docker/scripts/*
      - dockerfiles/**/*
      - more_scripts/*.{rb,py,sh}

在上面的场景中，将多个提交推送到 Gitlab 时，分支，Gitlab 创建并触发 Docker 构建 job，前提是提交包含对以下任一项的更改：

Dockerfile 文件。

docker/scripts/directory 中的任何文件。

dockerfiles 目录中的任何文件和子目录。

more_scripts 目录中任何具有 rb、py、sh 扩展名的文件。

您还可以使用 glob 模式来匹配 repo 根目录或 repo 中的任何目录中的多个文件。例如：

YML
test:
  script: npm run test
  only:
    changes:
      - "*.json"
      - "**/*.sql"

在上面的示例中，表达式被双引号括起来，因为它们是全局模式。Gitlab 将无法解析带有未封装的 glob 模式的.gitlab-ci.yml 文件。

如果在 repo 根目录下扩展名为.md 的任何文件中检测到更改，则以下示例将跳过 CIjob：

YML
build:
  script: npm run build
  except:
    changes:
      - "*.md"

警告：警告：在将此功能与新的分支和标记一起使用时，需要注意一些事项。请参阅下面的部分。

使用带有新分支和标记的更改

在将新分支或新标记推送到 Gitlab 时，，策略的计算结果始终为 true，Gitlab 将创建 job。此功能尚未与合并请求连接，并且，由于 Gitlab 正在创建管道，用户才能创建合并请求，因此此时目标分支的位置未知。

对合并请求使用更改

对于合并请求的管道，可以根据合并请求中修改的文件定义要创建的 job。

For example:

YML
docker build service one:
  script: docker build -t my-service-one-image:$CI_COMMIT_REF_SLUG .
  only:
    refs:
      - merge_requests
    changes:
      - Dockerfile
      - service-one/**/*

在上面的场景中，如果创建或更新合并请求以更改 service one 目录或 dockerfile 中的文件，那么 gitlab 将创建并触发 docker build service onejob。

7.9. tags

tags 用于从允许运行此项目的所有运行者列表中选择特定的运行者。

在注册运行程序期间，可以指定运行程序的 tags，例如 ruby、postgres、development。

tags 允许您使用分配了指定 tags 的运行者运行 job：

YML
job:
  tags:
    - ruby
    - postgres

上面的规范将确保 job 由同时定义了 ruby 和 postgres 标记的运行程序构建。

标签也是在不同平台上运行不同 job 的好方法，例如，给定一个带有标签 OSX 的 OSX 运行程序和带有标签的 Windows 运行程序 Windows，以下 job 在各自的平台上运行：

YML
windows job:
  stage:
    - build
  tags:
    - windows
  script:
    - echo Hello, %USERNAME%!

osx job:
  stage:
    - build
  tags:
    - osx
  script:
    - echo "Hello, $USER!"

7.10. allow_failure

允许失败允许 job 失败而不影响 CI 套件的其余部分。默认值为假，手动 job 除外。

当启用并且 job 失败时，该 job 将在用户界面中显示橙色警告。但是，管道的逻辑流会将 job 视为成功 / 通过，并且不会被阻塞。

假设所有其他 job 都成功，则 job 的阶段及其管道将显示相同的橙色警告。但是，关联的提交将被标记为 “通过”，没有警告。

在下面的示例中，job1 和 job2 将并行运行，但如果 job1 失败，则不会停止下一阶段的运行，因为它标记为 allow_failure:true:

YML
job1:
  stage: test
  script:
    - execute_script_that_will_fail
  allow_failure: true

job2:
  stage: test
  script:
    - execute_script_that_will_succeed

job3:
  stage: deploy
  script:
    - deploy_to_staging

7.11. when

用于实现在失败或失败时运行的 job。

when 可以设置为以下值之一：

on_success - 仅当先前阶段的所有 job 成功时执行 job（或由于标记为 “允许失败” 而被视为成功）。这是默认设置。

on_failure - 仅当先前阶段中的至少一个 job 失败时才执行 job。

always - 执行 job，而不管先前阶段的 job 状态如何。

manual - 手动执行 job（在 Gitlab 8.10 中添加）。阅读下面的手动操作。

For example:

YML
stages:
  - build
  - cleanup_build
  - test
  - deploy
  - cleanup

build_job:
  stage: build
  script:
    - make build

cleanup_build_job:
  stage: cleanup_build
  script:
    - cleanup build when failed
  when: on_failure

test_job:
  stage: test
  script:
    - make test

deploy_job:
  stage: deploy
  script:
    - make deploy
  when: manual

cleanup_job:
  stage: cleanup
  script:
    - cleanup after jobs
  when: always

上面的脚本将：

仅当 build_job 失败时才执行 cleanup_build_job。

始终在最后执行 cleanup_job 而不管成功或失败。

允许您从 Gitlab 的用户界面手动执行 Deploy_job。

when:manual

手动操作是一种特殊类型的 job，不能自动执行，需要由用户显式启动。手动操作的一个示例用法是部署到生产环境。可以从管道、job、环境和部署视图启动手动操作。Read more at the
environments documentation.

手动操作可以是可选的，也可以是阻塞的。阻止手动操作将在定义此操作的阶段阻止管道的执行。它是当有人通过单击播放按钮执行阻止手动操作时，可以恢复管道的执行。

当管道被阻塞时，如果设置了 “管道成功时合并”，则不会合并管道。阻塞的管道也有一个特殊的状态，称为手动。默认情况下，手动操作是非阻塞的。如果要进行手动操作阻止，则必须在.gitlab-ci.yml 中的 job 定义中添加 allow_failure:false。

可选的手动操作默认情况下 allow_failure: true，其状态不会影响整个管道状态。因此，如果手动操作失败，管道最终会成功。

手动操作被认为是写操作，因此当用户希望触发操作时，将使用受保护分支的权限。换句话说，为了触发分配给正在运行管道的分支的手动操作，用户需要能够合并到此分支。

when:delayed

延迟 job 用于在一段时间后执行脚本。如果希望避免 job 立即进入挂起状态，则此操作非常有用。

您可以用 start_in 键设置周期。除非提供了一个单位，否则 start_in key 的值是以秒为单位的已用时间，并且时间必须小于或等于一小时。例如：

YML
10 seconds
30 minutes
1 hour

当某个阶段中存在延迟 job 时，管道将不会进行，直到延迟 job 完成。这意味着这个关键字也可以用于在不同阶段之间插入延迟。

延迟 job 的计时器在上一阶段完成后立即启动。与其他类型的 job 类似，延迟 job 的计时器将不会启动，除非上一阶段已通过。

下面的示例创建一个名为 Timed Rollow 10% 的 job，该 job 在上一阶段完成 30 分钟后执行：

YML
timed rollout 10%:
  stage: deploy
  script: echo 'Rolling out 10% ...'
  when: delayed
  start_in: 30 minutes

通过单击 Unschedule 按钮，可以停止延迟 job 的活动计时器。除非手动执行该 job，否则将来永远不会执行该 job。

您可以通过单击 “播放” 按钮立即启动延迟的 job。Gitlab Runner 将很快选择您的工作并开始工作。

7.12. environment

environment 用于定义 job 部署到特定环境。如果指定了 environment，并且该名称下不存在任何环境，则将自动创建一个新的环境。

在其最简单的形式中，environment 关键字的定义如下：

YML
deploy to production:
  stage: deploy
  script: git push production HEAD:master
  environment:
    name: production

在上面的示例中，部署到生产 job 将标记为对生产环境进行部署。

environment:name

The environment name can contain:

YML
letters
digits
spaces
-
_
/
$
{
}

常见的名称有 qa, staging, and production，但是您可以将任何名称用于您的工作流。

除了在 environment 关键字后定义环境名称，还可以将其定义为单独的值。为此，请在环境下使用 name 关键字：

YML
deploy to production:
  stage: deploy
  script: git push production HEAD:master
  environment:
    name: production

environment:url

这是一个可选值，设置后，它会在 Gitlab 中的不同位置显示按钮，单击该按钮会将您带到定义的 URL。

在下面的示例中，如果 job 成功完成，它将在合并请求和环境 / 部署页面中创建按钮，这些页面将指向 https://prod.example.com。

YML
deploy to production:
  stage: deploy
  script: git push production HEAD:master
  environment:
    name: production
    url: https://prod.example.com

environment:on_stop

关闭（停止）环境可以通过在 environment 下定义的 on-stop 关键字来实现。它声明了一个不同的 job，该 job 运行的目的是关闭环境。

例如，请阅读 environment:action 部分。

environment:action

action 关键字将与 on_stop 一起使用，并在调用以关闭环境的 job 中定义。

例如：

YML
review_app:
  stage: deploy
  script: make deploy-app
  environment:
    name: review
    on_stop: stop_review_app

stop_review_app:
  stage: deploy
  variables:
    GIT_STRATEGY: none
  script: make delete-app
  when: manual
  environment:
    name: review
    action: stop

在上面的示例中，我们设置了 review-appjob 以部署到 review 环境中，并且在 on-stop 下定义了一个新的 stop-review-appjob。一旦 review_app 完成，它将根据 “when” 下定义的内容触发 stop_review_app。在本例中，我们将其设置为手动，以便它需要通过 Gitlab 的 Web 界面进行手动操作才能运行。

同样在这个例子中，GIT_STRATEGY 被设置为 “none”，这样当自动触发 stop_review_app 时，Gitlab Runner 不会在删除分支后尝试 check out 代码。

stop_review_app 需要定义以下关键字：

YML
when - reference
environment:name
environment:action
stage应与review_app相同，以便在删除分支时环境自动停止。

动态环境

For example:

YML
deploy as review app:
  stage: deploy
  script: make deploy
  environment:
    name: review/$CI_COMMIT_REF_NAME
    url: https://$CI_ENVIRONMENT_SLUG.example.com/

deploy as review app 将标记为 deployment，以动态创建 review/$CI_COMMIT_REF_NAME 环境，其中 $CI_COMMIT_REF_NAME 是运行程序设置的环境变量。$CI_ENVIRONMENT_SLUG 变量基于环境名称，但适合包含在 URL 中。在这种情况下，如果在名为 pow 的分支中运行 deploy as review app，则可以使用类似 https://review pow.example.com/ 的 URL 访问此环境。

当然，这意味着承载应用程序的底层服务器配置正确。

常见的用例是为分支创建动态环境，并将它们用作审查应用程序。您可以在 https://gitlab.com/gitlab-examples/review-apps-nginx/ 上看到一个使用 review-apps 的简单示例。

7.13. cache

TIP: Learn more:Read how caching works and find out some good practices in the caching dependencies documentation.

cache 用于指定应在 job 之间缓存的文件和目录的列表。只能使用项目工作区内的路径。

如果 cache 是在 job 范围之外定义的，则意味着它是全局设置的，所有 job 都将使用该定义。

cache:paths

使用 paths 指令选择将缓存哪些文件或目录。可以使用通配符跟踪 glob 模式和 filepath.match。

缓存以.apk 和.config 文件结尾的二进制文件中的所有文件：

YML
rspec:
  script: test
  cache:
    paths:
      - binaries/*.apk
      - .config

本地定义的缓存覆盖全局定义的选项。以下 rspecjob 将只缓存二进制文件 /：

YML
cache:
  paths:
    - my/files

rspec:
  script: test
  cache:
    key: rspec
    paths:
      - binaries/

请注意，由于缓存是在 job 之间共享的，如果您对不同的 job 使用不同的路径，则还应设置不同的 cache:key，否则缓存内容会被覆盖。

cache:key

由于缓存是在 job 之间共享的，如果您对不同的 job 使用不同的路径，则还应设置不同的 cache:key，否则缓存内容会被覆盖。

key 指令允许您定义 job 之间缓存的关联性，允许为所有 job 都有一个缓存、每个 job 缓存、每个分支缓存。或者其他适合您工作流程的方式。通过这种方式，您可以微调缓存，允许您在不同的 job 之间甚至不同的分支之间缓存数据。

cache:key 变量可以使用任何预定义的变量，如果没有设置默认键，则它只是文字默认值，这意味着默认情况下，从 gitlab 9.0 开始，每个管道和 job 之间共享所有内容。

cache:key 变量不能包含 / 字符，或者编码为 %2f 的等效 URI；也禁止使用仅由点（.，%2e）构成的值。

例如，要启用每个分支缓存：

YML
cache:
  key: "$CI_COMMIT_REF_SLUG"
  paths:
    - binaries/

如果使用 Windows 批处理运行 shell 脚本，则需要将 $ 替换为 %：

YML
cache:
  key: "%CI_COMMIT_REF_SLUG%"
  paths:
    - binaries/

cache:untracked

set untracked:true 缓存 Git 存储库中所有未跟踪的文件：

YML
rspec:
  script: test
  cache:
    untracked: true

缓存 binaries 下的所有 Git 未跟踪文件和文件：

YML
rspec:
  script: test
  cache:
    untracked: true
    paths:
      - binaries/

cache:policy

缓存 job 的默认行为是在执行开始时下载文件，并在结束时重新上传文件。这允许为将来的运行保留 job 所做的任何更改，称为 pull-push 缓存策略。

如果知道 job 不会更改缓存文件，可以通过设置 policy:pull 来跳过上传步骤。通常，这将与早期阶段的普通缓存 job 成对出现，以确保缓存不时更新：

YML
stages:
  - setup
  - test

prepare:
  stage: setup
  cache:
    key: gems
    paths:
      - vendor/bundle
  script:
    - bundle install --deployment

rspec:
  stage: test
  cache:
    key: gems
    paths:
      - vendor/bundle
    policy: pull
  script:
    - bundle exec rspec ...

这有助于加快 job 执行速度并减少缓存服务器上的负载，特别是当您有大量的缓存使用并行执行的 job 时。

此外，如果有一个 job 无条件地重新创建缓存而不引用其先前的内容，则可以使用 policy: push 跳过下载步骤。

7.14. artifacts

artifacts 用于指定在 job 成功、失败或总是失败时应附加到该 job 的文件和目录列表。

artifacts 将在 job 完成后发送到 Gitlab，并可在 Gitlab UI 中下载。
Read more about artifacts.

artifacts:paths

只能使用项目工作区内的路径。可以使用通配符跟踪 glob 模式和 filepath.match。

要在不同 job 之间传递 artifacts，see dependencies.。

发送 binaries and .config: 下所有文件：

YML
artifacts:
  paths:
    - binaries/
    - .config

要禁用 artifacts 传递，请使用 dependencies: []

YML
job:
  stage: build
  script: make build
  dependencies: []

您可能希望只为 tags 的版本创建 artifacts，以避免用临时的 artifacts 填充构建服务器存储。

仅为 tags 创建 artifacts（default-job 不会创建 artifacts）：

YML
default-job:
  script:
    - mvn test -U
  except:
    - tags

release-job:
  script:
    - mvn package -U
  artifacts:
    paths:
      - target/*.war
  only:
    - tags

artifacts:name

name 指令允许您定义创建的 artifacts 存档的名称。这样，当您想从 Gitlab 下载归档文件时，每个归档文件都可以有一个唯一的名称。artifacts:name 变量可以使用任何预定义的变量。默认名称为 artifacts，下载时将变为 artifacts.zip。

如果您的分支名称包含正斜杠（例如 feature/my feature），建议使用 $ci-commit-ref-slug 而不是 $ci-commit-ref-name 来正确命名 artifacts。

要使用当前 job 的名称创建存档，请执行以下操作：

YML
job:
  artifacts:
    name: "$CI_JOB_NAME"
    paths:
      - binaries/

要使用当前分支或标记的名称（仅包括 binaries 文件夹）创建存档，请执行以下操作：

YML
job:
  artifacts:
    name: "$CI_COMMIT_REF_NAME"
    paths:
      - binaries/

要使用当前 job 的名称和当前分支或标记（仅包括 binaries 文件夹）创建存档，请执行以下操作：

YML
job:
  artifacts:
    name: "$CI_JOB_NAME-$CI_COMMIT_REF_NAME"
    paths:
      - binaries/

要创建具有当前阶段名称和分支名称的存档，请执行以下操作：

YML
job:
  artifacts:
    name: "$CI_JOB_STAGE-$CI_COMMIT_REF_NAME"
    paths:
      - binaries/

如果使用 Windows 批处理运行 shell 脚本，则需要将 $ 替换为 %：

YML
job:
  artifacts:
    name: "%CI_JOB_STAGE%-%CI_COMMIT_REF_NAME%"
    paths:
      - binaries/

如果使用 Windows PowerShell 运行 shell 脚本，则需要将 $ 替换为 $env:：

YML
job:
  artifacts:
    name: "$env:CI_JOB_STAGE-$env:CI_COMMIT_REF_NAME"
    paths:
      - binaries/

artifacts:untracked

artifacts:untracked 用于将所有 git 未跟踪文件添加为 artifacts（沿着 artifacts:paths 中定义的路径）。

artifacts:untracked 忽略存储库的.gitignore 文件中的配置。

发送所有 git 未跟踪文件：

1
2
3

YML
artifacts:
  untracked: true

发送所有 git 未跟踪文件和二进制文件：

YML
artifacts:
  untracked: true
  paths:
    - binaries/

artifacts:when

artifacts:when 用于在 job 失败或尽管失败时上载 artifacts 的时间。

artifacts:when 可以设置为以下值之一：

on_success - 仅当 job 成功时上载 artifacts。这是默认设置。

on_failure - 仅当 job 失败时才上载 artifacts。

always - 上载 artifacts，不管 job 状态如何。

仅当 job 失败时上载项目：

YML
job:
  artifacts:
    when: on_failure

artifacts:expire_in

expire_-in 允许您指定 artifacts 在过期之前应该存在多长时间，从而从它们上传和存储到 Gitlab 的时间开始删除。如果未定义到期时间，则默认为实例范围的设置。（默认为 30 天，永远在 gitlab.com 上）。

您可以使用 “job” 页上的 “保留” 按钮来覆盖过期时间并永久保留项目。

过期后，artifacts 默认每小时删除一次（通过 cronjob），并且不再可访问。

expire_in 的值是以秒为单位的已用时间，除非提供了一个单位。可分析值示例：

YML
'42'
'3 mins 4 sec'
'2 hrs 20 min'
'2h20min'
'6 mos 1 day'
'47 yrs 6 mos and 4d'
'3 weeks and 2 days'

要在上载后 1 周使项目过期，请执行以下操作：

YML
job:
  artifacts:
    expire_in: 1 week

artifacts:reports

reports 关键字用于从 job 收集测试报告并在 Gitlab 的 UI（合并请求、管道视图）中公开它们。阅读如何将其与 JUnit 报告一起使用。

无论 job 结果如何（成功或失败），都会收集测试报告。您可以使用 artifacts:expire\u 来设置其 artifacts 的到期日期。
如果还希望能够浏览报告输出文件，请包含 artifacts:paths 关键字。

artifacts:reports:junit

JUnit 报告将 JUnit XML 文件收集为 artifacts。虽然 JUnit 最初是在爪哇开发的，但是有许多其他第三方端口，如 yml、Python、Ruby 等。

有关更多详细信息和示例，请参阅 JUnit 测试报告。下面是从 Ruby 的 rspec 测试工具收集 JUnit XML 文件的示例：

YML
rspec:
  stage: test
  script:
  - bundle install
  - rspec --format RspecJunitFormatter --out rspec.xml
  artifacts:
    reports:
      junit: rspec.xml

收集到的 JUnit 报告将作为 artifacts 上传到 Gitlab，并将自动显示在合并请求中。

如果 JUnit 工具使用导出到多个 XML 文件，则可以在一个 job 中指定多个测试报告路径，这些路径将自动连接到一个文件中。使用文件名模式（junit:rspec-.xml）、文件名数组（junit:[rspec-1.xml、rspec-2.xml、rspec-3.xml]）或其组合（junit:[rspec.xml，测试结果 /test-.xml]）。

artifacts:reports:codequality (STARTER)

代码质量报告将代码质量问题收集为 artifacts。

收集的代码质量报告将作为 artifacts 上传到 Gitlab，并将自动显示在合并请求中。

artifacts:reports:sast (ULTIMATE) 终极

sast 报告将 sast 漏洞收集为 artifacts。

收集的 SAST 报告将作为 artifacts 上传到 Gitlab，并将自动显示在合并请求、管道视图中，并为安全仪表盘提供数据。

artifacts:reports:dependency_scanning (ULTIMATE) 终极

依赖项扫描报告将依赖项扫描漏洞收集为 artifacts。

收集到的依赖项扫描报告将作为 artifacts 上载到 Gitlab，并将自动显示在合并请求、管道视图中，并为安全仪表板提供数据。

artifacts:reports:container_scanning (ULTIMATE)

容器扫描报告将容器扫描漏洞收集为 artifacts。

收集的容器扫描报告将作为一个 artifacts 上载到 Gitlab，并将自动显示在合并请求、管道视图中，并为安全仪表板提供数据。

artifacts:reports:dast (ULTIMATE)

DAST 报告将 DAST 漏洞收集为 artifacts。

收集的 DAST 报告将作为 artifacts 上传到 Gitlab，并将自动显示在合并请求、管道视图中，并为安全仪表盘提供数据。

artifacts:reports:license_management (ULTIMATE)

许可证管理报告将许可证作为 artifacts 收集。

收集的许可证管理报告将作为一个 artifacts 上载到 Gitlab，并将自动显示在合并请求、管道视图中，并为安全仪表盘提供数据。

artifacts:reports:performance (PREMIUM)

性能报告将性能指标收集为 artifacts。

收集到的性能报告将作为 artifacts 上传到 Gitlab，并将自动显示在合并请求中。

artifacts:reports:metrics (PREMIUM)

性能报告将性能指标收集为 artifacts。
收集到的性能报告将作为 artifacts 上传到 Gitlab，并将自动显示在合并请求中。

artifacts:reports:metrics (PREMIUM)

度量报告将度量收集为 artifacts。

收集的度量报告将作为 artifacts 上传到 Gitlab，并将自动显示在合并请求中。

7.15. dependencies

此功能应该与 artifacts 一起使用，并允许您定义要在不同 job 之间传递的 artifacts。

请注意，默认情况下，来自所有先前阶段的 artifacts 都会被传递。

若要使用此功能，请在 job 的上下文中定义依赖项，并传递一个列表，其中列出了应从中下载 artifacts 的所有先前 job。只能从当前 job 之前执行的阶段定义 job。如果从当前阶段或下一阶段定义 job，将显示一个错误。

定义空数组将跳过下载该 job 的任何 artifacts。使用依赖项时不考虑上一个 job 的状态，因此如果它失败或是未运行的手动 job，则不会发生错误。

在下面的示例中，我们用 artifacts 定义了两个 job，build:osx 和 build:linux。执行 test:osx 时，来自 build:osx 的 artifacts

将在生成上下文中下载和提取。对于 test:linux 和 build:linux 中的 artifacts 也是如此。

由于阶段优先，job 部署将从所有以前的 job 下载项目：

YML
build:osx:
  stage: build
  script: make build:osx
  artifacts:
    paths:
      - binaries/

build:linux:
  stage: build
  script: make build:linux
  artifacts:
    paths:
      - binaries/

test:osx:
  stage: test
  script: make test:osx
  dependencies:
    - build:osx

test:linux:
  stage: test
  script: make test:linux
  dependencies:
    - build:linux

deploy:
  stage: deploy
  script: make deploy

When a dependent job will fail

如果设置为依赖项的 job 的 artifacts 已过期或清除，则依赖 job 将失败。

您可以要求管理员翻转此开关并恢复旧行为。

7.16. coverage

Coverage 允许您配置如何从 job 输出中提取代码覆盖率。

正则表达式是此处唯一有效的值类型。因此，为了一致和显式地表示正则表达式字符串，必须使用环绕 /。如果你想从字面上匹配特殊字符，你必须转义它们。

A simple example:

YML
job1:
  script: rspec
  coverage: '/Code coverage: \d+\.\d+/'

7.17. retry

重试” 允许您配置一个 job 在发生故障时将重试多少次。

当一个 job 失败并配置了重试时，它将被再次处理到 retry 关键字指定的次数。

如果 retry 设置为 2，并且 job 在第二次运行（第一次重试）中成功，则不会重试。

再一次。重试值必须是一个正整数，等于或大于 0，但小于或等于 2（最多两次重试，总共三次）。

在所有故障情况下重试的简单示例：

YML
test:
  script: rspec
  retry: 2

默认情况下，将在所有失败情况下重试 job。要更好地控制重试失败的次数，retry 可以是具有以下键的哈希：

max：最大重试次数。

when：失败的案例要重试。

要最多重试两次运行程序系统故障，请执行以下操作：

YML
test:
  script: rspec
  retry:
    max: 2
    when: runner_system_failure

如果存在除运行程序系统故障以外的其他故障，则不会重试 job。

要在多个故障情况下重试，时间也可以是一个故障数组：

YML
test:
  script: rspec
  retry:
    max: 2
    when:
      - runner_system_failure
      - stuck_or_timeout_failure

Possible values for when are:

always：在出现任何故障时重试（默认）。

unknown_failure：失败原因未知时重试。

script_failure：当脚本失败时重试。

api_failure：在 api 失败时重试。

stuck_or_timeout_failure：当 job 卡住或超时时重试。

runner_system_failure：如果运行程序系统故障（例如设置 job 失败），请重试。

missing_dependency_failure：如果缺少依赖项，请重试。

runner_unsupported：如果运行程序不受支持，请重试。

7.18. parallel

Parallel 允许您配置要并行运行的 job 实例数。该值必须大于或等于两（2）且小于或等于 50。

这将创建并行运行的同一 job 的 n 个实例。它们按顺序从 job_name 1/n 到 job_name n/n 命名。

对于每个 job，都会设置 CI_NODE_INDEX and CI_NODE_TOTAL environment variables。

一个简单的例子：

YML
test:
  script: rspec
  parallel: 5

跨并行 job 并行化测试套件。不同的语言有不同的工具来促进这一点。

7.19. trigger (PREMIUM)

trigger 允许您定义下游管道 trigger。当从 trigger 定义创建的 job 由 Gitlab 启动时，将创建下游管道。
Learn more about multi-project pipelines.

简单触发器语法

配置下游触发器以使用具有下游项目完整路径的触发器关键字的最简单方法：

YML
rspec:
  stage: test
  script: bundle exec rspec

staging:
  stage: deploy
  trigger: my/deployment

复杂触发器语法

可以配置 Gitlab 用于创建下游管道的分支名称：

YML
rspec:
  stage: test
  script: bundle exec rspec

staging:
  stage: deploy
  trigger:
    project: my/deployment
    branch: stable

7.20. include

使用 include 关键字，可以允许包含外部 yaml 文件。include 要求外部 yaml 文件具有扩展名.yml 或.yaml，否则将不包括外部文件。

include 中定义的文件包括：

–与.gitlab-ci.yml 中的合并。

–始终首先评估并与.gitlab-ci.yml 的内容合并，而不管 include 关键字的位置如何。

使用合并可使用本地定义自定义和覆盖包含的 CI/CD 配置。
不支持跨 include 源的不同 yaml 文件使用 yaml 别名。您只能引用同一文件中的别名。您可以使用 extends 关键字，而不是使用 yaml 锚。

包含支持四个包含方法

YML
local
file
template
remote

See usage examples.

所有方法包含的.gitlab-ci.yml 配置在管道创建时进行评估。配置是一个及时的快照，并持久存在于数据库中。在创建下一个管道之前，对引用的.gitlab-ci.yml 配置所做的任何更改都不会反映在 gitlab 中。

include:local

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

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

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

不支持通过 git 子模块路径包含本地文件。

例子：

1
2
3

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

include:file

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

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

还可以指定 ref，默认值为项目的标题：

YML
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 都将在目标项目的范围内执行，因此可以使用本地（相对于目标项目）、项目、远程或模板 include。

include:template

include:template 可用于包含随 Gitlab 一起提供的.gitlab-ci.yml 模板。

For example:

YML
# File sourced from GitLab's template collection
include:
  - template: Auto-DevOps.gitlab-ci.yml

所有嵌套的 include 只能在用户的权限下执行，因此可以使用 project、remote 或 template include。

include:remote

nclude:remote 可用于包含来自不同位置的文件，使用 http/https，使用完整的 URL 引用。远程文件必须通过简单的 GET 请求公开访问，因为不支持远程 URL 中的身份验证架构。例如：

1
2
3

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

所有嵌套的 include 将作为公共用户在没有上下文的情况下执行，因此只允许使用其他远程、公共项目或模板。

嵌套包含

嵌套的 include 允许您组成一组 include。总共允许 50 个。

重复包含被视为配置错误。

包括示例

下面还有一些例子。

单个字符串或多个值的数组，您可以将额外的 yaml 文件作为单个字符串或多个值的数组包含在内。下面的例子都是有效的。

包含 include:local 方法的单个字符串：

1 2	YML include: '/templates/.after-script-template.yml'

包含 include 方法的数组：

YML
include:
  - 'https://gitlab.com/awesome-project/raw/master/.before-script-template.yml'
  - '/templates/.after-script-template.yml'

显式指定包含方法的单个字符串：

1
2
3

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

带有 include:remote 的数组是单个项：

1
2
3

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

具有多个包含方法的数组已明确指定：

YML
include:
  - remote: 'https://gitlab.com/awesome-project/raw/master/.before-script-template.yml'
  - local: '/templates/.after-script-template.yml'
  - template: Auto-DevOps.gitlab-ci.yml

数组混合语法：

YML
include:
  - 'https://gitlab.com/awesome-project/raw/master/.before-script-template.yml'
  - '/templates/.after-script-template.yml'
  - template: Auto-DevOps.gitlab-ci.yml
  - project: 'my-group/my-project'
    ref: master
    file: '/templates/.gitlab-ci-template.yml'

重新使用前脚本模板

在下面的示例中，.before-script-template.yml 的内容将与.gitlab-ci.yml 的内容一起自动获取和评估。

https://gitlab.com/awesome project/raw/master/.before-script-template.yml 的内容：

YML
before_script:
  - apt-get update -qq && apt-get install -y -qq sqlite3 libsqlite3-dev nodejs
  - gem install bundler --no-document
  - bundle install --jobs $(nproc)  "${FLAGS[@]}"

Content of .gitlab-ci.yml:

YML
include: 'https://gitlab.com/awesome-project/raw/master/.before-script-template.yml'

rspec:
  script:
    - bundle exec rspec

覆盖外部模板值以下示例显示了特定的 yaml 定义的变量以及在.gitlab-ci.yml 中自定义的 include 文件中生产 job 的详细信息。

https://company.com/autodevops-template.yml 的内容：

YML
variables:
  POSTGRES_USER: user
  POSTGRES_PASSWORD: testing_password
  POSTGRES_DB: $CI_ENVIRONMENT_SLUG

production:
  stage: production
  script:
    - install_dependencies
    - deploy
  environment:
    name: production
    url: https://$CI_PROJECT_PATH_SLUG.$KUBE_INGRESS_BASE_DOMAIN
  only:
    - master

Content of .gitlab-ci.yml:

YML
include: 'https://company.com/autodevops-template.yml'

image: alpine:latest

variables:
  POSTGRES_USER: root
  POSTGRES_PASSWORD: secure_password

stages:
  - build
  - test
  - production

production:
  environment:
    url: https://domain.com

在这种情况下，变量 postgres-user 和 postgres-password 以及 autodevops-template.yml 中定义的生产 job 的环境 url 已被.gitlab-ci.yml 中定义的新值覆盖。

合并允许扩展和重写字典映射，但不能向包含的数组添加或修改项。例如，要向生产 job 脚本添加其他项，必须重复现有的脚本项：

https://company.com/autodevops-template.yml 的内容：

YML
production:
  stage: production
  script:
    - install_dependencies
    - deploy

Content of .gitlab-ci.yml:

YML
include: 'https://company.com/autodevops-template.yml'

stages:
  - production

production:
  script:
    - install_dependencies
    - deploy
    - notify_owner

在这种情况下，如果在.gitlab-ci.yml 中不重复 install_dependencies 和 deploy，它们将不会成为组合 CI 配置中生产 job 脚本的一部分。

使用嵌套的 include

下面的示例说明如何使用不同方法的组合从不同的源嵌套 include。

在本例中，.gitlab-ci.yml 包含本地文件 /.gitlab-ci/another-config.yml：

1
2
3

YML
include:
  - local: /.gitlab-ci/another-config.yml

.gitlab ci/another-config.yml 包含一个模板和另一个项目的 /templates/docker-workflow.yml 文件：

YML
include:
  - template: Bash.gitlab-ci.yml
  - project: group/my-project
    file: /templates/docker-workflow.yml

group/my 项目中的 /templates/docker-workflow.yml 包含 group/my 项目的两个本地文件：

YML
include:
  - local: /templates/docker-build.yml
  - local: /templates/docker-testing.yml

group/my 项目中的 /templates/docker-build.yml 添加了一个 docker 构建 job：

1
2
3

YML
docker-build:
  script: docker build -t my-image .

我们的第二个 /templates/docker-test.yml 出现在 group/my 项目中，它添加了一个 docker 测试 job：

1
2
3

YML
docker-test:
  script: docker run my-image /run/tests.sh

7.21. extends

扩展定义了使用扩展的 job 将从中继承的项名称。

它是使用 yaml 锚的替代方法，并且更灵活和易读：

YML
.tests:
  script: rake test
  stage: test
  only:
    refs:
      - branches

rspec:
  extends: .tests
  script: rake rspec
  only:
    variables:
      - $RSPEC

在上面的示例中，rspecjob 继承自.tests 模板 job。Gitlab 将根据这些键执行反向深进。Gitlab 想要：

递归地将 rspec 内容放入.tests。

不去键的值。

这将导致以下 job：

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

请注意，script:rake 测试已被 script:rake rspec 覆盖。

如果您想包括 rake 测试，请参见之前的脚本和之后的脚本。

. 本例中的测试是隐藏的密钥，但也可以从常规 job 继承。扩展支持多级别继承，但不建议使用三个以上的级别。支持的最大嵌套级别为 10。

以下示例具有两个继承级别：

YML
.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 及更高版本中，也可以使用多个父级进行扩展。用于合并的算法是 “最近的作用域获胜”，因此来自最后一个成员的键将始终隐藏在其他级别上定义的任何内容。例如：

YML
.only-important:
  only:
    - master
    - stable
  tags:
    - production

.in-docker:
  tags:
    - docker
  image: alpine

rspec:
  extends:
    - .only-important
    - .in-docker
  script:
    - rake rspec

这将导致以下 RSPECjob：

YML
rspec:
  only:
    - master
    - stable
  tags:
    - docker
  image: alpine
  script:
    - rake rspec

Using extends and include together

扩展配置文件和 include 的工作。

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

YML
.template:
  script:
    - echo Hello!

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

YML
include: included.yml

useTemplate:
  image: alpine
  extends: .template

这将运行一个名为 usetemplate 的 job，该 job 运行 echo hello！根据.templatejob 中的定义，并使用本地 job 中定义的 Alpine Docker 图像。

7.22. pages

页面是一项特殊的工作，用于将静态内容上载到 Gitlab，该工作可用于为您的网站提供服务。它有一个特殊的语法，所以这两个

必须满足以下要求：

任何静态内容都必须放在 public / 目录下。

必须定义具有公共 / 目录路径的项目。

下面的示例只是将所有文件从项目的根目录移动到 public/directory。.public 解决方案是这样的，cp 不会无限循环地将 public / 复制到自身：

YML
pages:
  stage: deploy
  script:
    - mkdir .public
    - cp -r * .public
    - mv .public public
  artifacts:
    paths:
      - public
  only:
    - master

7.23. variables

> 整数（以及字符串）对于变量的名称和值都是合法的。浮动不合法，不能使用。

Gitlab CI/CD 允许您在.gitlab-ci.yml 中定义变量，然后在 job 环境中传递这些变量。它们可以全局设置，也可以按 job 设置。

在 job 级别上使用 variables 关键字时，它将覆盖全局 yaml 变量和预定义变量。

它们存储在 Git 存储库中，用于存储非敏感项目配置，例如：

1
2
3

YML
variables:
  DATABASE_URL: "postgres://postgres@postgres/my_database"

这些变量稍后可以在所有执行的命令和脚本中使用。yaml 定义的变量也被设置为所有创建的服务容器，从而允许对它们进行微调。

除了用户定义的变量之外，还有运行程序本身设置的变量。一个例子是 ci-commit-ref-name，它具有为其构建项目的分支或标记名的值。除了可以在.gitlab-ci.yml 中设置的变量外，还可以在 gitlab 的用户界面中设置所谓的变量。
Learn more about variables and their priority.

Git strategy

您可以在 “变量” 部分中设置用于获取最新应用程序代码的 Git_策略（全局或每个 job）。如果未指定，将使用项目设置中的默认值。

有三个可能的值：clone、fetch 和 none。

克隆是最慢的选项。它为每个 job 从头克隆存储库，确保项目工作空间始终是原始的。

1
2
3

YML
variables:
  GIT_STRATEGY: clone

提取速度更快，因为它重新使用项目工作区（如果不存在则返回到克隆）。Git Clean 用于撤消上一个 job 所做的任何更改，Git Fetch 用于检索自上一个 job 运行以来所做的提交。

1
2
3

YML
variables:
  GIT_STRATEGY: fetch

也没有人会重新使用项目工作区，但会跳过所有 Git 操作（包括 Gitlab Runner 的预克隆脚本，如果存在的话）。它主要用于只在 artifacts 上操作的 job（例如部署）。Git 存储库数据可能存在，但它肯定是过时的，因此您应该只依赖从缓存或 artifacts 引入到项目工作区的文件。

1
2
3

YML
variables:
  GIT_STRATEGY: none

Kubernetes 的执行者不支持 Git_策略，但将来可能会支持。有关更新，请参阅支持带 kubernetes 执行器的 git 策略的特性建议。

Git submodule strategy

Git_子模块_策略变量用于控制在生成前获取代码时是否包含 Git 子模块 / 如何包含 Git 子模块。您可以在 “变量” 部分中全局或按 job 设置它们。

有三个可能的值：无、正常和递归：

无表示在获取项目代码时不包括子模块。这是默认值，与 v1.10 之前的行为匹配。

正常意味着只包括顶级子模块。相当于：

1
2
3

YML
git submodule sync
git submodule update --init

递归意味着将包括所有子模块（包括子模块的子模块）。此功能需要 Git v1.8.1 及更高版本。当使用不基于 Docker 的执行器的 Gitlab 运行程序时，请确保 Git 版本满足该要求。相当于：

1
2
3

YML
git submodule sync --recursive
git submodule update --init --recursive

请注意，要使此功能正常工作，子模块必须（在.gitmodules 中）配置为：

公共可访问存储库的 HTTP（S）URL，或指向同一 Gitlab 服务器上另一个存储库的相对路径。请参见 Git 子模块文档。

Git checkout

当 git 策略设置为 clone 或 fetch 以指定是否应运行 git 签出时，可以使用 git 签出变量。如果未指定，则默认为 true。您可以在 “变量” 部分中全局或按 job 设置它们。如果设置为 false，则运行程序将：

执行提取时 - 更新存储库并将工作副本保留在当前版本上，执行克隆时 - 克隆存储库并将工作副本保留在默认分支上。

将此设置设置为 true 意味着对于克隆和获取策略，运行程序将签出工作副本到与 CI 管道相关的修订：

YML
variables:
  GIT_STRATEGY: clone
  GIT_CHECKOUT: "false"
script:
  - git checkout -B master origin/master
  - git merge $CI_COMMIT_SHA

Git clean flags

git-clean-flags 变量用于控制签出源后 git-clean 的默认行为。您可以全局设置它，也可以在变量部分中为每个 job 设置它。

git_clean_标志接受 git clean 命令的所有可能选项。

如果指定了 git_checkout:false，则禁用 git clean。如果 git_clean_标志是：

未指定，git clean 标志默认为 - ffdx。

给定值 none，不执行 git clean。

例如：

YML
variables:
  GIT_CLEAN_FLAGS: -ffdx -e cache/
script:
  - ls -al cache/

Job stages attempts

您可以设置正在运行的 job 将尝试执行以下每个阶段的尝试次数：

Variable	Description
GET_SOURCES_ATTEMPTS	尝试获取运行 job 的源的次数
ARTIFACT_DOWNLOAD_ATTEMPTS	尝试下载运行 job 的项目的次数
RESTORE_CACHE_ATTEMPTS	尝试还原运行 job 的缓存的次数

默认为一次尝试。

Example:

1
2
3

YML
variables:
  GET_SOURCES_ATTEMPTS: 3

Shallow cloning

可以使用 git_depth 指定提取和克隆的深度。这允许对存储库进行浅层克隆，这可以显著加快对具有大量提交或旧的大型二进制文件的存储库的克隆。价值是

传递给了 git fetch 和 git clone。

如果使用深度 1 并有 job 队列或重试 job，则 job 可能会失败。

因为 Git 获取和克隆是基于引用的，例如分支名称，所以运行者不能克隆特定的 commit SHA。如果队列中有多个 job，或者您正在重试一个旧 job，那么要测试的提交需要在克隆的 Git 历史记录中。为 GIT_DEPTH 设置的值太小可能导致无法运行这些旧提交。您将在中看到未解决的引用

job 日志。然后，您应该重新考虑将 GIT_DEPTH 更改为更高的值。

当设置 GIT_DEPTH 时，依赖于 Git 描述的 job 可能无法正常工作，因为 Git 历史只有一部分存在。

要仅获取或克隆最后 3 个提交：

1
2
3

YML
variables:
  GIT_DEPTH: "3"

您可以全局设置它，也可以在变量部分中为每个 job 设置它。

8. 不推荐使用的参数 (见原文)

以下参数已弃用。……

文章作者: 雪人

文章链接: https://www.webq.top/2020/11/19/doc/ci/