용어 설명#

• CI/CD configuration: 프로젝트의 CI/CD 구성을 정의하는 YAML 파일입니다.
• keyword: CI/CD 구성의 각 키워드입니다.
• entry: CI/CD 구성에서 키워드를 나타내는 Entry 클래스입니다.

CI/CD 구성의 모든 키워드가 Entry 클래스로 표현되지는 않습니다. 복잡한 구조나 재사용 가능한 부분이 있는 키워드에 대해서만 Entry 클래스를 생성합니다.

예를 들면 다음과 같습니다.

• image 키워드는 Entry::Image 클래스로 표현됩니다.
• image 키워드의 name 서브키워드는 Entry 클래스로 표현되지 않습니다.
• image 키워드의 pull_policy 서브키워드는 Entry::PullPolicy 클래스로 표현됩니다.

YAML 구문 작업 시 고려할 중요한 사항은 YAML 구문 변경 리뷰 가이드를 참고합니다.

새 키워드 추가#

CI 구성 키워드는 lib/gitlab/ci/config/entry 디렉터리에 추가합니다. EE 전용 변경 사항에는 ee/lib/gitlab/ci/config/entry 또는 ee/lib/ee/gitlab/ci/config/entry 디렉터리를 사용합니다.

JSON 스키마도 그에 맞게 업데이트합니다.

상속#

entry는 다음 중 하나를 상속하는 클래스로 표현됩니다.

• Entry::Node: 단순한 키워드에 사용합니다. (예: Entry::Stage)
• Entry::Simplifiable: 여러 구조를 가지는 키워드에 사용합니다. 예를 들어 Entry::Retry는 단순한 숫자일 수도 있고 해시 구성일 수도 있습니다.
• Entry::ComposableArray: 단일 타입 하위 요소의 목록을 가지는 키워드에 사용합니다. 예를 들어 Entry::Includes는 Entry::Include 요소의 목록을 가집니다.
• Entry::ComposableHash: 사용자 정의 키를 가진 단일 타입 하위 요소를 가지는 키워드에 사용합니다. 예를 들어 Entry::Variables는 사용자 정의 키를 가진 Entry::Variable 요소의 목록을 가집니다.

헬퍼 클래스#

entry에서는 다음 헬퍼 클래스를 사용할 수 있습니다.

• Entry::Validatable: entry 클래스에서 validations 블록을 사용할 수 있게 하고 검증 기능을 제공합니다.
• Entry::Attributable: entry 클래스에서 attributes 메서드를 사용할 수 있게 합니다. 각 속성에 대해 xxx, has_xxx?, has_xxx_value? 메서드를 생성합니다.
• Entry::Configurable: entry 클래스에서 entry 메서드를 사용할 수 있게 합니다. 각 entry에 대해 xxx_defined?, xxx_entry, xxx_value 메서드를 생성합니다.

value 메서드#

value 메서드는 entry 클래스의 핵심 메서드입니다. entry의 실제 값을 반환합니다. 기본적으로 Entry::Node 클래스의 value 메서드는 중첩된 entry가 없는 한 entry의 해시 구성을 반환합니다. 단순한 entry에 유용합니다. 예를 들어 Entry::Paths는 문자열 배열을 값으로 가지므로 문자열 배열을 그대로 반환할 수 있습니다.

일부 키워드에서는 value 메서드를 재정의합니다. 이 메서드에서 entry가 무엇을 어떤 방식으로 반환할지 정합니다. 여기서는 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 entry의 값입니다.
• file_value는 중첩된 file entry의 값입니다.
• token은 기본 token 속성의 값입니다.

중첩된 entry의 값을 가져올 때는 항상 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

피처 플래그 액터#

entry 클래스에서는 현재 프로젝트나 사용자에 접근할 수 없습니다. 그러나 액터 없이 피처 플래그를 사용하는 방식은 권장되지 않습니다. 이 문제를 해결하는 방법은 세 가지입니다.

1. Feature.enabled?(:feature_flag, Feature.current_request)를 사용합니다.
2. Config::FeatureFlags.enabled?(:feature_flag)를 사용합니다
3. entry 클래스에서는 피처 플래그를 사용하지 않고 코드의 다른 부분에서 사용합니다.

테스트 및 검증#

entry를 추가하거나 수정할 때는 해당하는 spec 파일도 함께 추가하거나 업데이트해야 합니다. 또한 완전히 통합된 테스트를 구성하려면 spec/lib/gitlab/ci/yaml_processor_spec.rb 파일이나 spec/lib/gitlab/ci/yaml_processor/test_cases/* 디렉터리의 파일에 테스트를 추가하거나 수정하는 작업도 중요합니다.