贡献 CI/CD 配置

术语表

• CI/CD 配置：定义项目 CI/CD 配置的 YAML 文件。
• 关键字：CI/CD 配置中的每个关键字。
• 条目：代表 CI/CD 配置中关键字的 Entry 类。

并非 CI/CD 配置中的每个关键字都由 Entry 类表示。 我们为具有复杂结构或可重用部分的关键字创建 Entry 类。

例如：

• image 关键字由 Entry::Image 类表示。
• image 关键字的 name 子关键字不由 Entry 类表示。
• image 关键字的 pull_policy 子关键字由 Entry::PullPolicy 类表示。

添加新关键字

CI 配置关键字添加在 lib/gitlab/ci/config/entry 目录中。 对于 EE 特定的更改，请使用 ee/lib/gitlab/ci/config/entry 或 ee/lib/ee/gitlab/ci/config/entry 目录。

继承

条目由继承自以下基类的类表示：

• Entry::Node：用于简单关键字。 （例如，Entry::Stage）
• Entry::Simplifiable：用于具有多种结构的关键字。 例如，Entry::Retry 可以是简单的数字或哈希配置。
• Entry::ComposableArray：用于具有单一类型子元素列表的关键字。 例如，Entry::Includes 包含一个 Entry::Include 元素列表。
• Entry::ComposableHash：用于具有用户定义键的单一类型子元素的关键字。 例如，Entry::Variables 包含一个具有用户定义键的 Entry::Variable 元素列表。

辅助类

以下辅助类可用于条目中：

• Entry::Validatable：在条目类中启用 validations 块并提供验证功能。
• Entry::Attributable：在条目类中启用 attributes 方法。它为每个属性创建这些方法：xxx、has_xxx?、has_xxx_value?。
• Entry::Configurable：在条目类中启用 entry 方法。它为每个条目创建这些方法：xxx_defined?、xxx_entry、xxx_value。

value 方法

value 方法是条目类的主要方法。它返回条目的实际值。 默认情况下，从 Entry::Node 类开始，value 方法返回条目的哈希配置，除非它有嵌套条目。 对于简单条目，这很有用。例如，Entry::Paths 的值是一个字符串数组，因此可以直接返回字符串数组。

在某些关键字中，我们重写了 value 方法。在这个方法中，我们返回我们想要从条目中返回的内容和方式。 Entry::Attributable 和 Entry::Configurable 的使用在这里可能扮演着重要角色。例如， 在 Entry::Secret 中，我们有以下代码：

attributes %i[vault file token].freeze

entry :vault, Entry::Vault::Secret
entry :file, ::Gitlab::Config::Entry::Boolean

def value
  {
    vault: vault_value,
    file: file_value,
    token: token
  }.compact
end

• vault_value 是嵌套 vault 条目的值。
• file_value 是嵌套 file 条目的值。
• token 是基本 token 属性的值。

重要的是，我们应该始终使用 xxx_value 方法来获取嵌套条目的值。

功能标志使用

在添加新的 CI/CD 配置关键字时，重要的是使用功能标志来控制变更的发布。 这允许我们在生产环境中测试变更，而不会影响所有用户。有关更多信息，请参阅 功能标志文档。

检查功能标志的常见位置是在 Gitlab::Config::Entry::Node#value 方法中。例如：

def value
  {
    vault: vault_value,
    file: file_available? ? file_value : nil,
    token: token
  }.compact
end

private

def file_available?
  ::Gitlab::Ci::Config::FeatureFlags.enabled?(:secret_file_available, type: :beta)
end

功能标志执行者

在条目类中，我们无法访问当前项目或用户。但是，不建议在没有 执行者 的情况下使用功能标志。 为了解决这个问题，我们有三个选项：

1. 使用 Feature.enabled?(:feature_flag, Feature.current_request)。
2. 使用 Config::FeatureFlags.enabled?(:feature_flag)
3. 不要在条目类中使用功能标志，而是在代码的其他部分使用它们。

测试和验证

在添加或修改条目时，必须添加或更新相应的规范文件。 此外，为了获得完全集成的测试，在 spec/lib/gitlab/ci/yaml_processor_spec.rb 文件或 spec/lib/gitlab/ci/yaml_processor/test_cases/* 目录中的文件中添加/修改测试也很重要。