CI/CD 구성 요소

Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated

GitLab 16.0에서 실험적 기능으로 도입되었으며, ci_namespace_catalog_experimental라는 플래그가 있습니다. 기본적으로 비활성화되어 있습니다.

GitLab 16.2에서 GitLab.com 및 Self-managed에 활성화됨.

GitLab 16.3에서 기능 플래그 ci_namespace_catalog_experimental가 제거됨.

GitLab 16.6에서 베타로 이동됨.

GitLab 17.0에서 일반적으로 사용 가능.

CI/CD 구성 요소는 재사용 가능한 단일 파이프라인 구성 단위입니다. 구성 요소를 사용하여 더 큰 파이프라인의 작은 부분을 생성하거나 완전한 파이프라인 구성을 작성할 수 있습니다.

구성 요소는 보다 동적인 동작을 위해 입력 매개변수로 구성할 수 있습니다.

CI/CD 구성 요소는 include 키워드로 추가된 다른 종류의 구성과 유사하지만, 여러 가지 이점을 가지고 있습니다:

구성 요소는 CI/CD 카탈로그에 나열할 수 있습니다.
구성 요소는 특정 버전과 함께 릴리스되고 사용될 수 있습니다.
동일한 프로젝트 내에서 여러 구성 요소를 정의하고 함께 버전을 관리할 수 있습니다.

자신의 구성 요소를 만드는 대신, CI/CD 카탈로그에서 필요한 기능을 가진 공개된 구성 요소를 검색할 수도 있습니다.

소개 및 실습 예제를 보려면 재사용 가능한 CI/CD 구성 요소를 사용한 효율적인 DevSecOps 워크플로를 참조하세요.

일반적인 질문 및 추가 지원은 FAQ: GitLab CI/CD 카탈로그 블로그 게시물을 참조하세요.

구성 요소 프로젝트

구성 요소당 최대 개수 변경됨 10개에서 30개로 GitLab 16.9에서.

구성 요소 프로젝트는 하나 이상의 구성 요소를 호스팅하는 리포지토리가 있는 GitLab 프로젝트입니다. 프로젝트 내의 모든 구성 요소는 함께 버전 관리되며, 프로젝트당 최대 30개의 구성 요소가 있습니다.

구성 요소가 다른 구성 요소와 다른 버전 관리가 필요한 경우, 구성 요소는 전담 구성 요소 프로젝트로 이동해야 합니다.

구성 요소 프로젝트 만들기

구성 요소 프로젝트를 만들려면 다음을 수행해야 합니다:

README.md 파일이 있는 새 프로젝트 생성하기:
- 설명이 구성 요소에 대한 명확한 소개를 제공하는지 확인하세요.
- 선택 사항. 프로젝트가 생성된 후 프로젝트 아바타를 추가할 수 있습니다.
CI/CD 카탈로그에 게시된 구성 요소는 구성 요소 프로젝트의 요약을 표시할 때 설명과 아바타를 모두 사용합니다.

각 구성 요소에 대해 YAML 구성 파일을 추가하고 필수 디렉토리 구조를 따르세요.
예:

spec:  
  inputs:  
    stage:  
      default: test  
---  
component-job:  
  script: echo job 1  
  stage: $[[ inputs.stage ]]  

구성 요소를 구성 요소 사용하기 위해 즉시 사용할 수 있지만, CI/CD 카탈로그에 구성 요소를 게시하는 것을 고려할 수 있습니다.

디렉토리 구조

리포지토리는 다음을 포함해야 합니다:

리포지토리의 모든 구성 요소에 대한 세부 정보를 문서화하는 README.md 마크다운 파일.
모든 구성 요소 구성이 포함된 최상위 templates/ 디렉토리. 이 디렉토리에서 구성 요소를 정의할 수 있습니다:
- 각 구성 요소에 대해 .yml로 끝나는 단일 파일에서 정의, 예: templates/secret-detection.yml.
- 여러 관련 파일을 함께 묶는 구성 요소의 진입점으로 template.yml 파일이 포함된 하위 디렉토리에서 정의. 예: templates/secret-detection/template.yml.

참고: 선택적으로, 각 구성 요소는 더 자세한 정보를 제공하는 자체 README.md 파일을 가질 수 있으며, 이는 최상위 README.md 파일에서 링크될 수 있습니다. 이는 구성 요소 프로젝트를 더 잘 살펴보고 사용하는 방법을 제공하는 데 도움이 됩니다.

또한 다음을 수행해야 합니다:

프로젝트의 .gitlab-ci.yml을 구성하여 구성 요소 테스트 및 새 버전 발표를 수행합니다.
구성 요소 사용을 포괄하는 선택한 라이센스를 가진 LICENSE.md 파일을 추가합니다. 예: MIT 또는 Apache 2.0 오픈 소스 라이센스.

예를 들어:

프로젝트에 단일 구성 요소가 포함된 경우, 디렉토리 구조는 다음과 유사해야 합니다:

├── templates/
│   └── my-component.yml
├── LICENSE.md
├── README.md
└── .gitlab-ci.yml

프로젝트에 여러 구성 요소가 포함된 경우, 디렉토리 구조는 다음과 유사해야 합니다:
```
├── templates/
│   ├── my-simple-component.yml
│   └── my-complex-component/
│       ├── template.yml
│       ├── Dockerfile
│       └── test.sh
├── LICENSE.md
├── README.md
└── .gitlab-ci.yml
```
이 예에서:
- my-simple-component 구성 요소의 구성은 단일 파일에 정의됩니다.
- my-complex-component 구성 요소의 구성은 디렉토리에 있는 여러 파일로 구성됩니다.

구성 요소 사용하기

프로젝트의 CI/CD 구성에 구성 요소를 추가하려면 include: component 키워드를 사용합니다. 구성 요소 참조는 <fully-qualified-domain-name>/<project-path>/<component-name>@<specific-version> 형식으로 작성되며, 예를 들어:

include:
  - component: $CI_SERVER_FQDN/my-org/security-components/secret-detection@1.0.0
    inputs:
      stage: build

이 예에서:

$CI_SERVER_FQDN은 GitLab 호스트에 대해 일치하는 사전 정의 변수입니다. 프로젝트와 동일한 GitLab 인스턴스에서만 구성 요소를 참조할 수 있습니다.
my-org/security-components는 구성 요소가 포함된 프로젝트의 전체 경로입니다.
secret-detection은 단일 파일 templates/secret-detection.yml 또는 template.yml이 포함된 디렉토리 templates/secret-detection/로 정의된 구성 요소 이름입니다.
1.0.0은 구성 요소의 버전입니다.

GitLab이 새로운 파이프라인을 생성할 때, 구성 요소의 구성이 가져와져서 파이프라인의 구성에 추가됩니다.

자가 관리 인스턴스에서 GitLab.com 구성 요소를 사용하려면 구성 요소 프로젝트 미러링을 해야 합니다.

경고: 구성 요소가 작동하는 데 토큰, 비밀번호 또는 기타 민감한 데이터의 사용을 요구하는 경우, 해당 데이터가 예상하고 승인한 작업을 수행하는 데만 사용되는지 확인하기 위해 구성 요소의 소스 코드를 감사해야 합니다. 또한 작업을 완료하는 데 필요한 최소한의 권한, 접근 또는 범위로 토큰과 비밀을 사용해야 합니다.

구성 요소 버전

가장 높은 우선 순위부터 차례로, 구성 요소 버전은 다음과 같습니다:

커밋 SHA, 예: e3262fdd0914fa823210cdb79a8c421e2cef79d8.
태그, 예: 1.0.0. 동일한 이름의 태그와 커밋 SHA가 존재할 경우, 커밋 SHA가 태그보다 우선합니다. CI/CD 카탈로그에 배포된 구성 요소는 시맨틱 버전으로 태그가 지정되어야 합니다.
브랜치 이름, 예: main. 동일한 이름의 브랜치와 태그가 존재할 경우, 태그가 브랜치보다 우선합니다.
~latest, 항상 CI/CD 카탈로그에 게시된 최신 시맨틱 버전을 가리킵니다. 언제나 절대 최신 버전을 사용하고자 할 경우에만 ~latest를 사용하세요. 이는 파괴적인 변경 사항이 포함될 수 있습니다. ~latest는 사전 릴리스(예: 1.0.1-rc)는 포함하지 않습니다. 사전 릴리스는 프로덕션 준비 완료로 간주되지 않습니다.

구성 요소에서 지원하는 모든 버전을 사용할 수 있지만, CI/CD 카탈로그에 게시된 버전을 사용하는 것이 좋습니다. 커밋 SHA 또는 브랜치 이름으로 참조된 버전은 CI/CD 카탈로그에 게시되지 않을 수 있지만, 테스트에 사용될 수 있습니다.

시맨틱 버전 범위

도입됨 GitLab 16.11에서

CI/CD 카탈로그 구성 요소를 참조할 때, 범위 내에서 최신 시맨틱 버전을 지정하기 위한 특별한 형식을 사용할 수 있습니다.

최신 릴리스를 지정하려면:

마이너 버전의 경우, 참조에서 마이너와 메이저 버전 번호 모두를 사용하되, 패치 버전 번호는 사용하지 마세요. 예를 들어, 1.1을 사용하여 1.1로 시작하는 최신 버전(1.1.0 또는 1.1.9 포함)을 사용하되, 1.2.0은 사용하지 마세요.
메이저 버전의 경우, 참조에서 메이저 버전 번호만 사용하세요. 예를 들어, 1을 사용하여 1.로 시작하는 최신 버전(1.0.0 또는 1.9.9 포함)을 사용하되, 2.0.0은 사용하지 마세요.
모든 버전의 경우, 최신 릴리스 버전을 사용하려면 ~latest를 사용하세요.

예를 들어, 구성 요소가 다음과 같은 정확한 순서로 릴리스됩니다:

1.0.0
1.1.0
2.0.0
1.1.1
1.2.0
2.1.0
2.0.1

이 예에서 구성 요소를 참조할 경우:

1은 1.2.0 버전을 사용합니다.
1.1은 1.1.1 버전을 사용합니다.
~latest는 2.1.0 버전을 사용합니다.

사전 릴리스 버전은 버전 범위를 참조할 때 절대 가져오지 않습니다. 사전 릴리스 버전을 가져오려면 전체 버전을 지정하세요. 예: 1.0.1-rc.

구성 요소 작성

이 섹션에서는 고품질 구성 요소 프로젝트를 만들기 위한 몇 가지 모범 사례를 설명합니다.

의존성 관리

구성 요소가 다른 구성 요소를 사용하는 것이 가능하지만, 의존성을 신중하게 선택해야 합니다. 의존성을 관리하려면 다음과 같이 하세요:

의존성을 최소한으로 유지하세요. 작은 양의 중복은 일반적으로 의존성을 갖는 것보다 낫습니다.
가능할 경우 로컬 의존성에 의존하세요. 예를 들어, include:local을 사용하는 것은 여러 파일에서 동일한 Git SHA를 사용하도록 보장하는 좋은 방법입니다.
다른 프로젝트의 구성 요소에 의존할 경우, 이동하는 대상 버전인 ~latest 또는 Git 참조를 사용하는 것이 아니라 카탈로그의 릴리스로 버전을 고정하세요. 릴리스 또는 Git SHA를 사용하면 항상 동일한 수정본을 가져오고 구성 요소 소비자에게 일관된 동작을 보장합니다.
의존성을 정기적으로 업데이트하여 최신 릴리스로 고정하세요. 그런 다음 업데이트된 의존성과 함께 구성 요소의 새로운 릴리스를 게시합니다.

명확한 `README.md` 작성하기

각 구성 요소 프로젝트는 명확하고 포괄적인 문서를 가져야 합니다. 좋은 README.md 파일을 작성하기 위해:

문서는 프로젝트의 구성 요소들이 제공하는 기능에 대한 요약으로 시작해야 합니다.
프로젝트에 여러 구성 요소가 포함된 경우, 목차를 사용하여 사용자가 특정 구성 요소의 세부 정보로 빠르게 이동할 수 있도록 합니다.
프로젝트의 각 구성 요소에 대해 ## Components 섹션과 ### Component A와 같은 하위 섹션을 추가합니다.
각 구성 요소 섹션에서는:
- 구성 요소가 수행하는 작업에 대한 설명을 추가합니다.
- 이를 사용하는 방법을 보여주는 최소 하나의 YAML 예제를 추가합니다.
- 구성 요소가 입력을 사용하는 경우, 이름, 설명, 유형 및 기본 값을 포함한 모든 입력을 보여주는 표를 추가합니다.
- 구성 요소가 변수 또는 비밀을 사용하는 경우, 해당 내용도 문서화해야 합니다.
기여가 환영되는 경우 ## Contribute 섹션을 추가하는 것이 좋습니다.

구성 요소에 더 많은 지침이 필요한 경우, 구성 요소 디렉터리에 Markdown 파일로 추가 문서를 작성하고 이를 주요 README.md 파일에서 링크합니다. 예를 들어:

README.md    # 특정 docs.md에 대한 링크 포함
templates/
├── component-1/
│   ├── template.yml
│   └── docs.md
└── component-2/
    ├── template.yml
    └── docs.md

구성 요소 README.md의 예시는 AWS에 GitLab CI/CD 구성 요소의 README.md를 참조하세요.

구성 요소 테스트하기

CI/CD 구성 요소를 개발 워크플로의 일부로 테스트하는 것이 강력히 권장되며, 일관된 동작을 보장하는 데 도움이 됩니다.

.gitlab-ci.yml을 루트 디렉터리에 생성하여 CI/CD 파이프라인에서 변경 사항을 테스트합니다 (다른 프로젝트와 마찬가지로). 구성 요소의 동작과 잠재적인 부작용 모두를 테스트해야 합니다. 필요할 경우 GitLab API를 사용할 수 있습니다.

예를 들어:

include:
  # 현재 SHA에서 현재 프로젝트에 위치한 구성 요소 포함
  - component: $CI_SERVER_FQDN/$CI_PROJECT_PATH/my-component@$CI_COMMIT_SHA
    inputs:
      stage: build

stages: [build, test, release]

# `my-component의 구성 요소 작업`이 추가되었는지 확인합니다.
# 이 예제 작업은 포함된 구성 요소가 예상대로 작동하는지 테스트할 수도 있습니다.
ensure-job-added:
  stage: test
  image: badouralix/curl-jq
  # "my-component의 구성 요소 작업"을 구성 요소의 작업 이름으로 바꿉니다.
  script:
    - |
      route="${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/pipelines/${CI_PIPELINE_ID}/jobs"
      count=`curl --silent "$route" | jq 'map(select(.name | contains("component job of my-component"))) | length'`
      if [ "$count" != "1" ]; then
        exit 1; else
        echo "구성 요소 작업 존재"
      fi

# 파이프라인이 의미론적 버전이 있는 새 태그의 경우, 모든 이전 작업이 성공하면
# 릴리스를 생성합니다.
create-release:
  stage: release
  image: registry.gitlab.com/gitlab-org/release-cli:latest
  script: echo "릴리스 $CI_COMMIT_TAG 생성 중"
  rules:
    - if: $CI_COMMIT_TAG
  release:
    tag_name: $CI_COMMIT_TAG
    description: "구성 요소 저장소 $CI_PROJECT_PATH의 릴리스 $CI_COMMIT_TAG"

변경 사항을 커밋하고 푸시한 후, 파이프라인이 구성 요소를 테스트하고, 이전 작업이 성공하면 릴리스를 생성합니다.

참고: 프로젝트가 비공식인 경우 인증이 필요합니다.

구성 요소를 샘플 파일에 대해 테스트하기

일부 경우, 구성 요소는 상호 작용할 원본 파일이 필요합니다. 예를 들어, Go 소스 코드를 구축하는 구성 요소는 테스트할 Go 샘플이 필요할 가능성이 높습니다. 또는, Docker 이미지를 구축하는 구성 요소는 테스트할 샘플 Dockerfile이 필요할 가능성이 높습니다.

이러한 샘플 파일을 구성 요소 프로젝트에 직접 포함시켜 구성 요소 테스트 중에 사용할 수 있습니다.

구성 요소를 테스트하는 방법에 대한 자세한 내용은 구성 요소 테스트 사례를 참조하십시오.

인스턴스 또는 프로젝트 특정 값을 하드코딩하지 않기

구성 요소에서 다른 구성 요소 사용하기 를 사용할 때, 인스턴스의 정규화된 도메인 이름 대신 $CI_SERVER_FQDN을 사용합니다 (예: gitlab.com).

구성 요소에서 GitLab API에 액세스할 때, 인스턴스의 전체 URL 및 경로 대신 $CI_API_V4_URL을 사용합니다 (예: https://gitlab.com/api/v4).

이러한 미리 정의된 변수들은 구성 요소가 다른 인스턴스에서 사용될 때도 작동할 수 있도록 보장합니다. 예를 들어 자체 관리 인스턴스에서 GitLab.com 구성 요소 사용하기를 사용할 때 그렇습니다.

API 리소스가 항상 공개적이라고 가정하지 않기

구성 요소와 그 테스트 파이프라인이 자체 관리 인스턴스에서 작동하는지 확인하십시오. GitLab.com의 공개 프로젝트의 일부 API 리소스는 인증되지 않은 요청을 통해 접근할 수 있지만, 자체 관리 구성 요소 프로젝트는 비공식적이거나 내부 프로젝트로 미러링될 수 있습니다.

액세스 토큰이 선택적으로 입력값 또는 변수 통해 제공될 수 있도록 하는 것이 중요합니다. 이는 자체 관리 인스턴스에서 요청을 인증하는 데 사용됩니다.

글로벌 키워드 사용 피하기

구성 요소에서 글로벌 키워드를 사용하지 않도록 합니다.

구성 요소에서 이러한 키워드를 사용하면 모든 파이프라인의 모든 작업에 영향을 미치며, 이는 직접 .gitlab-ci.yml에서 정의된 작업이나 다른 포함된 구성 요소에도 해당됩니다.

글로벌 키워드의 대안으로는:

구성 요소 구성에서 일부 중복이 있더라도 각 작업에 직접 구성을 추가합니다.
구성 요소에서 extends 키워드를 사용하되, 구성요소가 구성에 병합될 때 이름 충돌의 위험을 줄이는 고유한 이름을 사용합니다.

예를 들어, default 글로벌 키워드를 사용하지 마십시오:

# 추천하지 않음
default:
  image: ruby:3.0

rspec-1:
  script: bundle exec rspec dir1/

rspec-2:
  script: bundle exec rspec dir2/

대신, 다음과 같은 방법을 사용할 수 있습니다:

각 작업에 구성을 명시적으로 추가합니다:

rspec-1:
  image: ruby:3.0
  script: bundle exec rspec dir1/

rspec-2:
  image: ruby:3.0
  script: bundle exec rspec dir2/

구성을 재사용하기 위해 extends를 사용합니다:

.rspec-image:
  image: ruby:3.0

rspec-1:
  extends:
    - .rspec-image
  script: bundle exec rspec dir1/

rspec-2:
  extends:
    - .rspec-image
  script: bundle exec rspec dir2/

하드코딩된 값을 입력값으로 교체하기

CI/CD 구성 요소에서 하드코딩된 값을 사용하지 않도록 합니다. 하드코딩된 값은 구성 요소 사용자가 구성 요소의 내부 세부 정보를 검토하고 해당 파이프라인을 구성 요소와 함께 작동하도록 적응하도록 강요할 수 있습니다.

문제가 있는 하드코딩된 값이 있는 일반적인 키워드는 stage입니다. 만약 구성 요소 작업의 단계가 하드코딩되어 있다면, 해당 구성 요소를 사용하는 모든 파이프라인은 반드시 정확히 동일한 단계를 정의하거나, 재정의해야 합니다.

선호되는 방법은 input 키워드를 사용하여 동적 구성 요소 구성을 만드는 것입니다. 구성 요소 사용자가 정확히 필요한 값을 지정할 수 있습니다.

예를 들어, 사용자가 정의할 수 있는 stage 구성이 있는 구성 요소를 만들기 위한 방법은 다음과 같습니다:

구성 요소 구성에서:

spec:
  inputs:
    stage:
      default: test
---
unit-test:
  stage: $[[ inputs.stage ]]
  script: echo unit tests

integration-test:
  stage: $[[ inputs.stage ]]
  script: echo integration tests

구성 요소를 사용하는 프로젝트에서:

stages: [verify, release]

include:
  - component: $CI_SERVER_FQDN/myorg/ruby/test@1.0.0
    inputs:
      stage: verify

입력으로 작업 이름 정의하기

stage 키워드의 값과 유사하게 CI/CD 구성 요소에 작업 이름을 하드 코딩하는 것을 피해야 합니다.

구성 요소의 사용자가 작업 이름을 사용자 정의할 수 있으면 파이프라인에 있는 기존 이름과의 충돌을 방지할 수 있습니다.

사용자는 다른 입력 옵션을 사용하여 다양한 이름으로 구성 요소를 여러 번 포함할 수도 있습니다.

inputs를 사용하여 구성 요소의 사용자가 특정 작업 이름 또는 작업 이름의 접두사를 정의할 수 있도록 하세요. 예를 들어:

spec:
  inputs:
    job-prefix:
      description: "작업 이름의 접두사를 정의합니다."
    job-name:
      description: "또는 작업의 이름을 정의합니다."
    job-stage:
      default: test
---

"$[[ inputs.job-prefix ]]-scan-website":
  stage: $[[ inputs.job-stage ]]
  script:
    - scan-website-1

"$[[ inputs.job-name ]]":
  stage: $[[ inputs.job-stage ]]
  script:
    - scan-website-2

입력으로 사용자 정의 CI/CD 변수 교체하기

구성 요소에서 CI/CD 변수를 사용할 때 inputs 키워드를 사용하는 것이 더 나은지 평가하세요.

구성 요소를 구성하기 위해 사용자가 사용자 정의 변수를 정의하도록 요청하는 것을 피하고, inputs가 더 나은 해결책일 때 사용하는 것이 좋습니다.

입력은 구성 요소의 spec 섹션에서 명시적으로 정의되며, 변수보다 더 나은 유효성 검사를 제공합니다.

예를 들어 필수 입력이 구성 요소에 전달되지 않으면 GitLab은 파이프라인 오류를 반환합니다.

반대로 변수가 정의되지 않으면 그 값이 비어 있으며 오류가 없습니다.

예를 들어, 스캐너의 출력 형식을 구성할 때 변수가 아닌 inputs를 사용하세요:

구성 요소 구성에서:

spec:
  inputs:
    scanner-output:
      default: json
---
my-scanner:
  script: my-scan --output $[[ inputs.scanner-output ]]

구성 요소를 사용하는 프로젝트에서:

include:
  - component: $CI_SERVER_FQDN/path/to/project/my-scanner@1.0.0
    inputs:
      scanner-output: yaml

다른 경우에는 CI/CD 변수가 여전히 선호될 수 있습니다. 예를 들어:

미리 정의된 변수를 사용하여 사용자의 프로젝트에 맞도록 구성 요소를 자동으로 구성하세요.
사용자가 프로젝트 설정에서 마스킹되거나 보호된 CI/CD 변수로 민감한 값을 저장하도록 요청하세요.

CI/CD 카탈로그

Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated

GitLab 16.1에서 실험으로 소개되었습니다.

GitLab 16.7에서 베타로 이동되었습니다.

GitLab 17.0에서 일반 제공되었습니다.

CI/CD 카탈로그는 CI/CD 워크플로를 확장하기 위해 사용할 수 있는 CI/CD 구성 요소가 게시된 프로젝트 목록입니다.

누구나 구성 요소 프로젝트를 생성하고 CI/CD 카탈로그에 추가하거나, 기존 프로젝트에 기여하여 제공되는 구성 요소를 개선할 수 있습니다.

클릭하여 시연을 보려면 CI/CD 카탈로그 베타 제품 투어를 참조하세요.

CI/CD 카탈로그 보기

CI/CD 카탈로그에 접근하고 사용 가능한 게시된 구성 요소를 보려면:

왼쪽 사이드바에서 Search or go to를 선택합니다.
Explore를 선택합니다.
CI/CD Catalog를 선택합니다.

또는, 이미 파이프라인 편집기에서 프로젝트에 있는 경우, CI/CD Catalog를 선택할 수 있습니다.

CI/CD 카탈로그의 구성 요소 가시성은 구성 요소 소스 프로젝트의
가시성 설정을 따릅니다. 소스 프로젝트가 설정된 구성 요소는 다음과 같이 다릅니다:

Private은 소스 구성 요소 프로젝트에 최소한 Guest 역할이 할당된 사용자만 볼 수 있습니다.
Internal은 GitLab 인스턴스에 로그인한 사용자만 볼 수 있습니다.
Public은 GitLab 인스턴스에 접근할 수 있는 누구나 볼 수 있습니다.

구성 요소 프로젝트 게시

CI/CD 카탈로그에 구성 요소 프로젝트를 게시하려면:

프로젝트를 카탈로그 프로젝트로 설정합니다.
새로운 릴리스를 게시합니다.

구성 요소 프로젝트를 카탈로그 프로젝트로 설정

게시된 버전의 구성 요소 프로젝트를 CI/CD 카탈로그에서 볼 수 있도록 하려면,
프로젝트를 카탈로그 프로젝트로 설정해야 합니다.

선결 조건:

프로젝트에 대해 Owner 역할이 있어야 합니다.

프로젝트를 카탈로그 프로젝트로 설정하려면:

왼쪽 사이드바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
Settings > General을 선택합니다.
Visibility, project features, permissions을 확장합니다.
CI/CD Catalog project 토글을 켭니다.

프로젝트는 새로운 릴리스를 게시한 후에만 카탈로그에서 찾을 수 있게 됩니다.

이 설정을 활성화하기 위해 자동화를 사용할 경우 mutationcatalogresourcescreate
GraphQL 엔드포인트를 사용할 수 있습니다. 이슈 463043
는 이것을 REST API에도 노출하자는 제안을 하고 있습니다.

새로운 릴리스 게시

CI/CD 구성 요소는 구성 요소 사용하기 섹션에 있는 것처럼
CI/CD 카탈로그에 나열되지 않고도 사용할 수 있습니다.
그러나 구성 요소의 릴리스를 카탈로그에 게시하면 다른 사용자들이 발견할 수 있게 됩니다.

선결 조건:

프로젝트에 대해 최소한 Maintainer 역할이 있어야 합니다.
프로젝트는:
- 카탈로그 프로젝트로 설정되어야 합니다.
- 프로젝트 설명이 정의되어 있어야 합니다.
- 릴리스되는 태그의 커밋 SHA에 대해 루트 디렉터리에 README.md 파일이 있어야 합니다.
- 릴리스되는 태그의 커밋 SHA에 대해 templates/ 디렉토리에 적어도 하나의 CI/CD 구성 요소가 있어야 합니다.

카탈로그에 구성 요소의 새 버전을 게시하려면:

.gitlab-ci.yml 파일에 작업을 추가하여 태그가 생성될 때
release 키워드를 사용하여 새 릴리스를 생성합니다.
태그 파이프라인을 구성하여 구성 요소 테스트를 수행한 후
릴리스 작업을 실행해야 합니다. 예를 들어:

create-release:
  stage: release
  image: registry.gitlab.com/gitlab-org/release-cli:latest
  script: echo "Creating release $CI_COMMIT_TAG"
  rules:
    - if: $CI_COMMIT_TAG
  release:
    tag_name: $CI_COMMIT_TAG
    description: "Release $CI_COMMIT_TAG of components in $CI_PROJECT_PATH"

릴리에 대한 새 태그를 생성합니다.
이 태그는 릴리스를 생성하는 작업을 포함하는 태그 파이프라인을 트리거해야 합니다.
태그는 의미론적 버전 관리를 사용해야 합니다.

릴리스 작업이 성공적으로 완료되면 릴리스가 생성되고 새로운 버전이
CI/CD 카탈로그에 게시됩니다.

시맨틱 버전 관리

GitLab 16.10에서 도입됨.

카탈로그에 구성 요소의 새 버전을 태그하고 릴리스하는 경우, 시맨틱 버전 관리를 사용해야 합니다. 시맨틱 버전 관리는 변경 사항이 주요, 마이너, 패치 또는 기타 유형의 변경 사항임을 전달하기 위한 표준입니다.

예를 들어, 1.0.0, 2.3.4 및 1.0.0-alpha는 모두 유효한 시맨틱 버전입니다.

구성 요소 프로젝트 비공개

카탈로그에서 구성 요소 프로젝트를 제거하려면 프로젝트 설정에서 CI/CD 카탈로그 리소스 토글을 끄십시오.

경고: 이 작업은 구성 요소 프로젝트 및 해당 버전에 대한 메타데이터를 파괴합니다.

프로젝트와 그 저장소는 여전히 존재하지만 카탈로그에는 표시되지 않습니다.

구성 요소 프로젝트를 카탈로그에 다시 게시하려면 새 릴리스를 게시하십시오.

인증된 구성 요소 생성자

GitLab 16.11에 도입됨

일부 CI/CD 구성 요소는 GitLab에 의해 검증된 사용자에 의해 생성되었고 유지 관리되고 있음을 표시하기 위해 아이콘으로 배지되어 있습니다.

GitLab-maintained (): GitLab에 의해 생성 및 유지 관리되는 구성 요소입니다.
GitLab Partner (): 독립적으로 생성되고 GitLab 인증 파트너에 의해 유지 관리되는 구성 요소입니다.

GitLab 파트너는 GitLab Partner Alliance의 구성원에게 연락하여 자신의 네임스페이스를 GitLab 인증으로 표시하도록 요청할 수 있습니다. 그런 다음 해당 네임스페이스에 있는 모든 CI/CD 구성 요소는 GitLab 파트너 구성 요소로 배지됩니다. 파트너 얼라이언스 구성원은 검증된 파트너를 대신하여 내부 요청 문제를 생성합니다: https://gitlab.com/gitlab-com/support/internal-requests/-/issues/new?issuable_template=CI%20Catalog%20Badge%20Request.

면책 조항: GitLab 파트너가 생성한 구성 요소는 어떤 종류의 보증 없이 있는 그대로 제공됩니다. 최종 사용자의 GitLab 파트너 생성 구성 요소 사용은 사용자의 책임이며, GitLab은 최종 사용자의 구성 요소 사용에 대해 어떤 보상 의무나 책임도 지지 않습니다. 최종 사용자의 해당 콘텐츠 사용 및 그와 관련된 모든 책임은 콘텐츠의 게시자와 최종 사용자 간의 문제입니다.

CI/CD 템플릿을 구성 요소로 변환

include: 구문을 사용하여 프로젝트에서 사용하는 기존 CI/CD 템플릿은 CI/CD 구성 요소로 변환할 수 있습니다:

구성 요소가 기존 구성 요소 프로젝트와 함께 그룹화되기를 원하는지, 또는 새 구성 요소 프로젝트를 만들지를 결정합니다.
디렉터리 구조에 따라 구성 요소 프로젝트에 YAML 파일을 생성합니다.
원래 템플릿 YAML 파일의 내용을 새 구성 요소 YAML 파일로 복사합니다.
새 구성 요소의 구성을 다음과 같이 리팩토링합니다:
- 구성 요소 작성에 대한 가이드를 따릅니다.
- 예를 들어 병합 요청 파이프라인을 활성화하거나 더 효율적으로 개선합니다.
구성 요소 저장소의 .gitlab-ci.yml을 활용하여 구성 요소에 변경 사항을 테스트합니다.
구성 요소를 태그하고 릴리스합니다.

Go CI/CD 템플릿을 CI/CD 구성 요소로 마이그레이션하는 실용적인 예시를 따라 더 많은 것을 배울 수 있습니다.

GitLab.com 구성요소를 자체 관리 인스턴스에서 사용하기

Tier: Premium, Ultimate Offering: Self-managed, GitLab Dedicated

새로운 GitLab 인스턴스를 설치하면 CI/CD 카탈로그는 게시된 CI/CD 구성요소가 없습니다.

인스턴스의 카탈로그를 채우려면 다음을 수행할 수 있습니다:

자신의 구성요소 게시하기.
GitLab.com의 구성요소를 자체 관리 인스턴스에 미러링하기.

자체 관리 인스턴스에 GitLab.com 구성요소를 미러링하려면:

gitlab.com에 대한 네트워크 아웃바운드 요청이 허용되었는지 확인하십시오.
구성요소 프로젝트를 호스팅할 그룹 만들기(추천 그룹: components).
새로운 그룹에 구성요소 프로젝트의 미러 만들기.
미러링된 구성요소 프로젝트에 대한 프로젝트 설명 작성하기 - 미러링된 저장소는 설명을 복사하지 않습니다.
자체 호스팅된 구성요소 프로젝트를 카탈로그 리소스로 설정하기.
태그(보통 최신 태그)를 위해 파이프라인 실행하기로 자체 호스팅된 구성요소 프로젝트에서 새 릴리스 게시하기.

문제 해결

`content not found` 메시지

다음과 유사한 오류 메시지를 받을 수 있습니다. 이는 카탈로그 프로젝트에서 호스팅되는 구성요소를 참조하기 위해 ~latest 버전 한정을 사용할 때 발생합니다:

This GitLab CI configuration is invalid: Component 'gitlab.com/my-namespace/my-project/my-component@~latest' - content not found  

~latest 동작은 GitLab 16.10에서 업데이트되었습니다.

이제 카탈로그 리소스의 최신 의미론적 버전을 참조합니다. 이 문제를 해결하려면, 새 릴리스 만들기.

CI/CD 구성 요소

구성 요소 프로젝트

구성 요소 프로젝트 만들기

디렉토리 구조

구성 요소 사용하기

구성 요소 버전

시맨틱 버전 범위

구성 요소 작성

의존성 관리

명확한 `README.md` 작성하기

구성 요소 테스트하기

구성 요소를 샘플 파일에 대해 테스트하기

인스턴스 또는 프로젝트 특정 값을 하드코딩하지 않기

API 리소스가 항상 공개적이라고 가정하지 않기

글로벌 키워드 사용 피하기

하드코딩된 값을 입력값으로 교체하기

입력으로 작업 이름 정의하기

입력으로 사용자 정의 CI/CD 변수 교체하기

CI/CD 카탈로그

CI/CD 카탈로그 보기

구성 요소 프로젝트 게시

구성 요소 프로젝트를 카탈로그 프로젝트로 설정

새로운 릴리스 게시

시맨틱 버전 관리

구성 요소 프로젝트 비공개

인증된 구성 요소 생성자

CI/CD 템플릿을 구성 요소로 변환

GitLab.com 구성요소를 자체 관리 인스턴스에서 사용하기

문제 해결

`content not found` 메시지

도움말

기능 사용 가능성과 제품 평가판

도움받기

CI/CD 구성 요소

구성 요소 프로젝트

구성 요소 프로젝트 만들기

디렉토리 구조

구성 요소 사용하기

구성 요소 버전

시맨틱 버전 범위

구성 요소 작성

의존성 관리

명확한 README.md 작성하기

구성 요소 테스트하기

구성 요소를 샘플 파일에 대해 테스트하기

인스턴스 또는 프로젝트 특정 값을 하드코딩하지 않기

API 리소스가 항상 공개적이라고 가정하지 않기

글로벌 키워드 사용 피하기

하드코딩된 값을 입력값으로 교체하기

입력으로 작업 이름 정의하기

입력으로 사용자 정의 CI/CD 변수 교체하기

CI/CD 카탈로그

CI/CD 카탈로그 보기

구성 요소 프로젝트 게시

구성 요소 프로젝트를 카탈로그 프로젝트로 설정

새로운 릴리스 게시

시맨틱 버전 관리

구성 요소 프로젝트 비공개

인증된 구성 요소 생성자

CI/CD 템플릿을 구성 요소로 변환

GitLab.com 구성요소를 자체 관리 인스턴스에서 사용하기

문제 해결

content not found 메시지

도움말

기능 사용 가능성과 제품 평가판

도움받기

명확한 `README.md` 작성하기

`content not found` 메시지