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(Enterprise Edition)-특정 변경 사항을 위해서는 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 구성 키워드를 추가할 때 변경 사항을 롤아웃(control)하기 위해 기능 플래그를 사용하는 것이 중요합니다. 이를 통해 모든 사용자에게 영향을 미치지 않고 프로덕션 환경에서 변경 사항을 테스트할 수 있습니다. 자세한 정보는 기능 플래그 문서를 참조하세요.

기능 플래그를 확인하는 일반적인 위치는 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/* 디렉토리의 파일에도 테스트를 추가/수정하는 것이 중요합니다.