InfoGrab DocsInfoGrab Docs

GitLab 공식 CI/CD 컴포넌트 개발 가이드

요약

이 문서는 GitLab이 유지 관리하는 CI/CD 컴포넌트를 개발하는 방법을 설명합니다. 모든 공식 GitLab 컴포넌트 프로젝트의 위치는 gitlab.com/components 그룹입니다. GitLab 내부 전용 컴포넌트, 예를 들어 gitlab-org/gitlab 프로젝트에 특화된 컴포넌트는 gitlab-org 그룹 하위에 구현해야 합니다.

이 문서는 GitLab이 유지 관리하는 CI/CD 컴포넌트를 개발하는 방법을 설명합니다. 여기에는 공식 공개 컴포넌트와 내부 사용 컴포넌트가 모두 포함됩니다.

모든 공식 GitLab 컴포넌트 프로젝트의 위치는 gitlab.com/components 그룹입니다. 이 그룹에는 범용적으로 설계되어 모든 GitLab 사용자에게 제공되며 GitLab이 유지 관리하는 모든 컴포넌트가 포함됩니다. 예를 들어 SAST, 시크릿 탐지, 코드 품질 컴포넌트 등이 있습니다. 컴포넌트 프로젝트는 처음에는 다른 그룹(예: gitlab-org)에서 생성될 수 있지만, 첫 번째 버전이 카탈로그에 게시되기 전에 components 그룹으로 이동해야 합니다. gitlab.com/components 그룹 하위의 모든 프로젝트는 공개(public)여야 합니다.

GitLab 내부 전용 컴포넌트, 예를 들어 gitlab-org/gitlab 프로젝트에 특화된 컴포넌트는 gitlab-org 그룹 하위에 구현해야 합니다.

CI/CD 카탈로그에 게시될 예정인 컴포넌트 프로젝트는 프로젝트 품질을 유지하고 직접적인 사용 경험을 갖추기 위해 먼저 내부적으로 사용(dogfood)해야 합니다.

소유권 정의#

공식 GitLab 컴포넌트는 커뮤니티의 신뢰를 받으므로 높은 수준의 품질과 시기적절한 유지 관리가 필요합니다. 컴포넌트는 최신 상태로 유지되고, 보안 취약점을 모니터링하며, 버그를 수정해야 합니다.

각 컴포넌트 프로젝트에는 도메인 전문가이기도 한 Owner 및 유지 관리자 집합이 있어야 합니다. 전문가는 GitLab의 어느 부서에서든 올 수 있으며, Engineering부터 Support, Customer Success, Developer Relations까지 다양합니다.

컴포넌트가 GitLab 기능(예: 시크릿 탐지)과 관련된 경우, 해당 기능 카테고리를 소유하거나 가장 밀접하게 관련된 팀이 프로젝트를 유지 관리해야 합니다. 이 경우 기능 카테고리의 Engineering Manager가 프로젝트 Owner로 지정됩니다.

프로젝트에서 owner 권한을 가진 멤버는 오픈된 이슈와 머지 리퀘스트를 트리아지하여 신속하게 처리되도록 보장하는 DRI입니다.

컴포넌트 프로젝트는 처음에 별도의 팀이나 개인이 생성할 수 있지만, 첫 번째 버전이 카탈로그에 게시되기 전에 Owner 집합으로 전환되어야 합니다.

프로젝트 리포지터리의 README.md 파일에는 필요 시 더 넓은 커뮤니티가 연락할 수 있도록 프로젝트의 주요 Owner가 명시되어야 합니다.

프로젝트 Owner 집합을 보장할 수 없거나 컴포넌트를 내부적으로 사용할 수 없는 경우, 공식 GitLab 컴포넌트 프로젝트를 생성하지 말고 더 넓은 커뮤니티가 카탈로그에서 수요를 충족시키도록 두는 것을 강력히 권장합니다.

개발 프로세스#

  • gitlab.com/components 하위에 프로젝트를 생성하거나 그룹 Owner 중 한 명에게 빈 프로젝트를 생성해 달라고 요청하세요.

  • 컴포넌트 생성 표준 가이드를 따르세요.

  • 컴포넌트 프로젝트가 제공하는 기능을 명확하게 설명하는 간결한 프로젝트 설명을 추가하세요.

  • 컴포넌트 작성에 대한 일반 지침과 공식 컴포넌트 모범 사례를 반드시 따르세요.

  • MIT 라이선스로 LICENSE.md 파일을 추가하세요 (예시).

  • 프로젝트에는 다음을 수행하는 .gitlab-ci.yml 파일이 있어야 합니다:

프로젝트의 모든 컴포넌트를 올바르게 검증합니다 (예시).

  • 새로 릴리즈된 태그를 카탈로그에 게시하는 release job을 포함합니다 (예시).

  • 공식 컴포넌트 프로젝트의 경우, 컴포넌트 프로젝트에 공식 아바타 이미지를 업로드하세요.

공식 컴포넌트 모범 사례#

  • README.md에 최소한 아래의 섹션이 포함되어 있는지 확인하세요 (예시는 Code quality 컴포넌트 참조):

Overview: 컴포넌트 프로젝트가 제공하는 기능.

  • Components: 각 컴포넌트에 대한 하위 섹션으로, 각각 다음을 포함합니다:

Usage: 입력값 있는 경우와 없는 경우(선택적인 경우)의 예시.

  • Inputs: 입력 이름, 타입, 기본값(있는 경우), 설명을 보여주는 테이블.

  • Variables (해당되는 경우): 변수 이름, 지원되는 값, 설명.

  • Contribute: 유지 관리자에게 연락하는 방법과 노트. 일반적으로 기여 프로세스는 공식 가이드를 따라야 합니다.

  • inputs 이름을 지정할 때, 복합 이름에는 밑줄 _을 사용하고 필요한 경우 하이픈 -을 구분자로 사용하세요. 예: service_x-project_name.

  • 사용자가 rules를 구성할 수 있도록 하려면 inputs를 사용하세요. 여기에서 예시를 확인하세요. rules가 정의되지 않은 경우 기본 동작을 유지하려면 이 이슈가 해결될 때까지 입력에 default: [{when: on_success}]를 사용해야 합니다.

새 버전 태그 지정 및 릴리즈#

컴포넌트 릴리즈에 적합한 버전 유형을 결정하려면 다음 가이드라인을 따르세요:

main 브랜치에서 모든 테스트가 통과하는지 확인하세요.

시맨틱 버전 관리를 사용하여 새 태그를 생성하세요.

태그에 대한 파이프라인이 실행되어 자동으로 릴리즈가 생성될 때까지 기다리세요.

새 버전이 CI/CD Components 카탈로그에 게시되었는지 확인하세요.

일반적으로 사용되는 시나리오에서 CI/CD Components 카탈로그의 새 버전을 수동으로 테스트하세요.

주요 버전(X.0.0)#

  • 호환성이 깨지는 API 변경.

  • 더 이상 사용되지 않는 기능 제거

  • 근본적인 아키텍처 변경

명확하지 않을 수 있는 호환성이 깨지는 변경:

  • 입력 수정: 필수 입력 추가, 기존 입력 제거, 또는 입력 검증을 더 제한적으로 변경(예: 정규식 패턴, 타입 또는 옵션 변경)

  • YAML 노드 충돌: 사용자가 이미 파이프라인에서 재정의하고 있을 수 있는 새 YAML 노드(예: before_script, after_script, variables) 추가

  • 러너 요구 사항: 특정 러너 구성 또는 최신 GitLab Runner 버전이 필요한 변경

  • 라이선스 의존성: 특정 GitLab 라이선스 티어가 필요한 기능 추가

환경 호환성:

  • Self-managed 고려 사항: 컴포넌트가 이전 GitLab 버전, 사용자 정의 인증 기관(CA), 비활성화된 컨테이너 레지스트리, 다양한 프로젝트 제한과 함께 작동하는지 확인

  • Dedicated 환경 지원: 버전 지연(일반적으로 1 마일스톤 뒤처짐)과 다른 인프라 제약 사항을 고려

  • CI 문법 호환성: 광범위한 GitLab 버전을 지원하는 경우 최신 CI 기능을 피함

마이너 버전(X.Y.0)#

  • 하위 호환성을 유지하는 새로운 기능

  • 기존 기능 개선

  • 성능 향상

패치 버전(X.Y.Z)#

  • 하위 호환 버그 수정

  • 문서 업데이트

  • 공개 API에 영향을 주지 않는 의존성 업데이트

공식 컴포넌트 검토 및 기여 프로세스#

프로젝트의 컴포넌트에 GitLab 코드베이스의 관련 CI/CD 템플릿이 있을 수 있습니다. 이 경우 컴포넌트 프로젝트와 CI/CD 템플릿을 상호 연결해야 합니다:

  • CI/CD 템플릿에 관련 컴포넌트 프로젝트의 위치를 주석으로 추가하세요.

  • 컴포넌트 프로젝트의 README.md에 기존 CI/CD 템플릿의 위치를 나타내는 섹션을 추가하세요.

이러한 컴포넌트에 변경 사항이 적용될 때, CI/CD 템플릿에도 변경 사항을 통합할 수 있는지 확인하세요. CI/CD 템플릿의 버전 관리 엄격성으로 인해 불가능할 수도 있습니다.

컴포넌트가 일관된 스타일로 작성되고 모범 사례를 따르는지 확인하기 위해 유지 관리자 중 한 명에게 검토를 요청하세요.

GitLab 공식 컴포넌트 기본 유지 관리자#

gitlab.com/components 그룹 하위의 각 컴포넌트 프로젝트에는 특정 DRI와 유지 관리자가 있어야 하지만, @gitlab-org/maintainers/ci-components 유지 관리자 그룹이 전반적으로 components 그룹을 관리하는 책임을 집니다.

이 유지 관리자 그룹의 책임:

  • 최상의 개발 경험을 제공하기 위해 툴킷 컴포넌트 및 프로젝트 템플릿과 같은 개발 및 헬퍼 리소스를 관리합니다.

  • 명확한 DRI가 없거나 개발 중인 컴포넌트 프로젝트를 관리하고, 장기적으로 적합한 Owner를 찾기 위해 노력합니다.

  • 코드 리뷰 시 및 이슈 트러블슈팅 시 개별 컴포넌트 프로젝트의 유지 관리자를 안내하고 멘토링합니다.

  • 시간이 지남에 따라 모범 사례가 적용되고 개선되도록 보장합니다.

유지 관리자가 되기 위한 요건:

  • CI/CD YAML 문법 및 기능에 대한 심층적인 이해가 있어야 합니다.

  • CI 컴포넌트의 작동 방식을 이해하고 개발 경험을 보여야 합니다.

  • 컴포넌트 작성 방법에 대한 확실한 이해가 있어야 합니다.

gitlab-components 일반 유지 관리자 그룹에 참여하는 방법:

GitLab 공식 CI/CD 컴포넌트 개발 가이드

GitLab v19.1
원문 보기
요약

이 문서는 GitLab이 유지 관리하는 CI/CD 컴포넌트를 개발하는 방법을 설명합니다. 모든 공식 GitLab 컴포넌트 프로젝트의 위치는 gitlab.com/components 그룹입니다. GitLab 내부 전용 컴포넌트, 예를 들어 gitlab-org/gitlab 프로젝트에 특화된 컴포넌트는 gitlab-org 그룹 하위에 구현해야 합니다.

이 문서는 GitLab이 유지 관리하는 CI/CD 컴포넌트를 개발하는 방법을 설명합니다. 여기에는 공식 공개 컴포넌트와 내부 사용 컴포넌트가 모두 포함됩니다.

모든 공식 GitLab 컴포넌트 프로젝트의 위치는 gitlab.com/components 그룹입니다. 이 그룹에는 범용적으로 설계되어 모든 GitLab 사용자에게 제공되며 GitLab이 유지 관리하는 모든 컴포넌트가 포함됩니다. 예를 들어 SAST, 시크릿 탐지, 코드 품질 컴포넌트 등이 있습니다. 컴포넌트 프로젝트는 처음에는 다른 그룹(예: gitlab-org)에서 생성될 수 있지만, 첫 번째 버전이 카탈로그에 게시되기 전에 components 그룹으로 이동해야 합니다. gitlab.com/components 그룹 하위의 모든 프로젝트는 공개(public)여야 합니다.

GitLab 내부 전용 컴포넌트, 예를 들어 gitlab-org/gitlab 프로젝트에 특화된 컴포넌트는 gitlab-org 그룹 하위에 구현해야 합니다.

CI/CD 카탈로그에 게시될 예정인 컴포넌트 프로젝트는 프로젝트 품질을 유지하고 직접적인 사용 경험을 갖추기 위해 먼저 내부적으로 사용(dogfood)해야 합니다.

소유권 정의#

공식 GitLab 컴포넌트는 커뮤니티의 신뢰를 받으므로 높은 수준의 품질과 시기적절한 유지 관리가 필요합니다. 컴포넌트는 최신 상태로 유지되고, 보안 취약점을 모니터링하며, 버그를 수정해야 합니다.

각 컴포넌트 프로젝트에는 도메인 전문가이기도 한 Owner 및 유지 관리자 집합이 있어야 합니다. 전문가는 GitLab의 어느 부서에서든 올 수 있으며, Engineering부터 Support, Customer Success, Developer Relations까지 다양합니다.

컴포넌트가 GitLab 기능(예: 시크릿 탐지)과 관련된 경우, 해당 기능 카테고리를 소유하거나 가장 밀접하게 관련된 팀이 프로젝트를 유지 관리해야 합니다. 이 경우 기능 카테고리의 Engineering Manager가 프로젝트 Owner로 지정됩니다.

프로젝트에서 owner 권한을 가진 멤버는 오픈된 이슈와 머지 리퀘스트를 트리아지하여 신속하게 처리되도록 보장하는 DRI입니다.

컴포넌트 프로젝트는 처음에 별도의 팀이나 개인이 생성할 수 있지만, 첫 번째 버전이 카탈로그에 게시되기 전에 Owner 집합으로 전환되어야 합니다.

프로젝트 리포지터리의 README.md 파일에는 필요 시 더 넓은 커뮤니티가 연락할 수 있도록 프로젝트의 주요 Owner가 명시되어야 합니다.

프로젝트 Owner 집합을 보장할 수 없거나 컴포넌트를 내부적으로 사용할 수 없는 경우, 공식 GitLab 컴포넌트 프로젝트를 생성하지 말고 더 넓은 커뮤니티가 카탈로그에서 수요를 충족시키도록 두는 것을 강력히 권장합니다.

개발 프로세스#

  • gitlab.com/components 하위에 프로젝트를 생성하거나 그룹 Owner 중 한 명에게 빈 프로젝트를 생성해 달라고 요청하세요.

  • 컴포넌트 생성 표준 가이드를 따르세요.

  • 컴포넌트 프로젝트가 제공하는 기능을 명확하게 설명하는 간결한 프로젝트 설명을 추가하세요.

  • 컴포넌트 작성에 대한 일반 지침과 공식 컴포넌트 모범 사례를 반드시 따르세요.

  • MIT 라이선스로 LICENSE.md 파일을 추가하세요 (예시).

  • 프로젝트에는 다음을 수행하는 .gitlab-ci.yml 파일이 있어야 합니다:

프로젝트의 모든 컴포넌트를 올바르게 검증합니다 (예시).

  • 새로 릴리즈된 태그를 카탈로그에 게시하는 release job을 포함합니다 (예시).

  • 공식 컴포넌트 프로젝트의 경우, 컴포넌트 프로젝트에 공식 아바타 이미지를 업로드하세요.

공식 컴포넌트 모범 사례#

  • README.md에 최소한 아래의 섹션이 포함되어 있는지 확인하세요 (예시는 Code quality 컴포넌트 참조):

Overview: 컴포넌트 프로젝트가 제공하는 기능.

  • Components: 각 컴포넌트에 대한 하위 섹션으로, 각각 다음을 포함합니다:

Usage: 입력값 있는 경우와 없는 경우(선택적인 경우)의 예시.

  • Inputs: 입력 이름, 타입, 기본값(있는 경우), 설명을 보여주는 테이블.

  • Variables (해당되는 경우): 변수 이름, 지원되는 값, 설명.

  • Contribute: 유지 관리자에게 연락하는 방법과 노트. 일반적으로 기여 프로세스는 공식 가이드를 따라야 합니다.

  • inputs 이름을 지정할 때, 복합 이름에는 밑줄 _을 사용하고 필요한 경우 하이픈 -을 구분자로 사용하세요. 예: service_x-project_name.

  • 사용자가 rules를 구성할 수 있도록 하려면 inputs를 사용하세요. 여기에서 예시를 확인하세요. rules가 정의되지 않은 경우 기본 동작을 유지하려면 이 이슈가 해결될 때까지 입력에 default: [{when: on_success}]를 사용해야 합니다.

새 버전 태그 지정 및 릴리즈#

컴포넌트 릴리즈에 적합한 버전 유형을 결정하려면 다음 가이드라인을 따르세요:

main 브랜치에서 모든 테스트가 통과하는지 확인하세요.

시맨틱 버전 관리를 사용하여 새 태그를 생성하세요.

태그에 대한 파이프라인이 실행되어 자동으로 릴리즈가 생성될 때까지 기다리세요.

새 버전이 CI/CD Components 카탈로그에 게시되었는지 확인하세요.

일반적으로 사용되는 시나리오에서 CI/CD Components 카탈로그의 새 버전을 수동으로 테스트하세요.

주요 버전(X.0.0)#

  • 호환성이 깨지는 API 변경.

  • 더 이상 사용되지 않는 기능 제거

  • 근본적인 아키텍처 변경

명확하지 않을 수 있는 호환성이 깨지는 변경:

  • 입력 수정: 필수 입력 추가, 기존 입력 제거, 또는 입력 검증을 더 제한적으로 변경(예: 정규식 패턴, 타입 또는 옵션 변경)

  • YAML 노드 충돌: 사용자가 이미 파이프라인에서 재정의하고 있을 수 있는 새 YAML 노드(예: before_script, after_script, variables) 추가

  • 러너 요구 사항: 특정 러너 구성 또는 최신 GitLab Runner 버전이 필요한 변경

  • 라이선스 의존성: 특정 GitLab 라이선스 티어가 필요한 기능 추가

환경 호환성:

  • Self-managed 고려 사항: 컴포넌트가 이전 GitLab 버전, 사용자 정의 인증 기관(CA), 비활성화된 컨테이너 레지스트리, 다양한 프로젝트 제한과 함께 작동하는지 확인

  • Dedicated 환경 지원: 버전 지연(일반적으로 1 마일스톤 뒤처짐)과 다른 인프라 제약 사항을 고려

  • CI 문법 호환성: 광범위한 GitLab 버전을 지원하는 경우 최신 CI 기능을 피함

마이너 버전(X.Y.0)#

  • 하위 호환성을 유지하는 새로운 기능

  • 기존 기능 개선

  • 성능 향상

패치 버전(X.Y.Z)#

  • 하위 호환 버그 수정

  • 문서 업데이트

  • 공개 API에 영향을 주지 않는 의존성 업데이트

공식 컴포넌트 검토 및 기여 프로세스#

프로젝트의 컴포넌트에 GitLab 코드베이스의 관련 CI/CD 템플릿이 있을 수 있습니다. 이 경우 컴포넌트 프로젝트와 CI/CD 템플릿을 상호 연결해야 합니다:

  • CI/CD 템플릿에 관련 컴포넌트 프로젝트의 위치를 주석으로 추가하세요.

  • 컴포넌트 프로젝트의 README.md에 기존 CI/CD 템플릿의 위치를 나타내는 섹션을 추가하세요.

이러한 컴포넌트에 변경 사항이 적용될 때, CI/CD 템플릿에도 변경 사항을 통합할 수 있는지 확인하세요. CI/CD 템플릿의 버전 관리 엄격성으로 인해 불가능할 수도 있습니다.

컴포넌트가 일관된 스타일로 작성되고 모범 사례를 따르는지 확인하기 위해 유지 관리자 중 한 명에게 검토를 요청하세요.

GitLab 공식 컴포넌트 기본 유지 관리자#

gitlab.com/components 그룹 하위의 각 컴포넌트 프로젝트에는 특정 DRI와 유지 관리자가 있어야 하지만, @gitlab-org/maintainers/ci-components 유지 관리자 그룹이 전반적으로 components 그룹을 관리하는 책임을 집니다.

이 유지 관리자 그룹의 책임:

  • 최상의 개발 경험을 제공하기 위해 툴킷 컴포넌트 및 프로젝트 템플릿과 같은 개발 및 헬퍼 리소스를 관리합니다.

  • 명확한 DRI가 없거나 개발 중인 컴포넌트 프로젝트를 관리하고, 장기적으로 적합한 Owner를 찾기 위해 노력합니다.

  • 코드 리뷰 시 및 이슈 트러블슈팅 시 개별 컴포넌트 프로젝트의 유지 관리자를 안내하고 멘토링합니다.

  • 시간이 지남에 따라 모범 사례가 적용되고 개선되도록 보장합니다.

유지 관리자가 되기 위한 요건:

  • CI/CD YAML 문법 및 기능에 대한 심층적인 이해가 있어야 합니다.

  • CI 컴포넌트의 작동 방식을 이해하고 개발 경험을 보여야 합니다.

  • 컴포넌트 작성 방법에 대한 확실한 이해가 있어야 합니다.

gitlab-components 일반 유지 관리자 그룹에 참여하는 방법: