一、GitLab CI/CD 流水线配置参考文档

原文链接：https://docs.gitlab.com/ee/ci/yaml/

在一个项目中，GitLab CI/CD 流水线通过使用名为 .gitlab-ci.yml 的 YAML 格式文件进行配置。

.gitlab-ci.yml 文件定义了流水线的文件结构和执行顺序，并确定：

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

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

• GitLab CI/CD Variables，用于配置流水线运行的环境。
• GitLab Runner advanced configuration，用于配置 GitLab Runner。

我们也提供配置流水线的完整示例：

• 有关 GitLab CI 的快速介绍，请按照我们的快速入门指南进行操作。
• 有关示例的集合，请查看 GitLab CI/CD Examples。
• 查看企业中使用的大型 .gitlab-ci.yml 文件，请查看 .gitlab-ci.yml file for gitlab-ce。

注意：如果您有一个从 GitLab 拉取过来的镜像存储库，您可能需要在项目的 Settings > Repository > Pull from a remote repository > Trigger pipelines for mirror updates 以启用并触发流水线。

介绍

流水线的配置从作业开始。作业是 .gitlab-ci.yml 文件中最基本的元素。

作业是：

• 定义它们应在什么条件下执行的约束。
• 具有任意名称的顶级元素，并且必须至少包含 script 项。
• 不限制可以定义的作业数量。

例如：

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

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

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

作业会被 Runner 选中并在 Runner 的所在的环境中执行。重要的是，每项作业都是相互独立运作的。

验证 .gitlab-ci.yml 文件

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

不可用的作业名称

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

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

使用保留关键字

如果在使用特定值时遇到验证错误（例如，true 或 false），请尝试：

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

配置参数

作业是通过一系列用于定义作业行为的参数来组成的。
下表列出了作业的可用参数：

关键字	描述
script	由 Runner 执行的 Shell 脚本。
image	使用 docker 镜像。 以下这些也可用： image:name image:entrypoint
services	使用 docker 服务镜像。 以下这些也可用： services:name services:alias services:entrypoint services:command
before_script	包括一组在作业被执行之前执行的命令
after_script	包括一组在作业被执行之后执行的命令
stages	定义流水线中的阶段
stage	定义一个作业阶段（默认：test）
only	创建作业的限制条件。 以下这些也可用： only:refs, only:kubernetes, only:variables only:changes
except	不创建作业的限制条件。 以下这些也可用： except:refs, except:kubernetes, except:variables except:changes
tags	用于选择 Runner 的标签列表。
allow_failure	允许作业执行失败。失败的作业无助于提交状态
when	什么时候执行作业。 以下这些也可用： when:manual when:delayed
environment	作业被部署的环境的名称。 以下这些也可用： environment:name environment:url environment:on_stop environment:action
cache	用于后续运行的缓存文件列表。 以下这些也可用： cache:paths cache:key cache:untracked cache:policy
artifacts	成功附加到作业中的文件和目录列表。 以下这些也可用： artifacts:paths artifacts:name artifacts:untracked artifacts:when artifacts:expire_in artifacts:reports 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 artifacts:reports:metrics
dependencies	作业被执行时所要依赖的其他作业，以便您可以在它们之间传递 artifacts。
coverage	设置给定作业执行时的代码覆盖率要求
retry	在发生故障时，自动重试作业的次数和时机
parallel	应该并行运行多少个作业实例
trigger	定义下游流水线触发器。
include	允许此作业包含外部 YAML 文件。 以下这些也可用： include:local include:file include:template include:remote
extends	此作业将继承的配置条目
pages	上传作业执行的结果以用于 GitLab Pages。
variables	在作业级别中定义的作业变量

注意：参数 types 和 type 已失效。

---

全局参数

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

全局默认值

使用 default: 关键字可以将某些参数全局设置为所有作业都可用的默认值。特定于作业中的相同参数配置可以覆盖默认参数。

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

• image
• services
• before_script
• after_script
• cache

在以下示例中，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中引入。

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

要启用或禁用全部全局定义默认值和变量参数的继承，请使用以下格式：

• default: true or default: false
• variables: true or variables: false

要仅继承全局定义默认值和变量参数，请指定要继承的内容，未列出的任何内容均不会被继承。使用以下格式之一：

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

or:

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 中元素的顺序定义了 job 执行的顺序：

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

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

stages:
  - build
  - test
  - deploy

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

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

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

---

未完待续……