CI/CD 구성 요소

Tier: Free, Premium, Ultimate Offering: GitLab.com, 자체 관리, GitLab Dedicated

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

구성 요소는 입력 매개변수로 동적 동작을 얻을 수 있습니다.

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

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

자체 구성 요소를 작성하는 대신에 필요한 기능을 가진 게시된 구성 요소를 CI/CD 카탈로그에서 검색할 수도 있습니다.

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

자주 묻는 질문과 추가적인 지원은 FAQ: GitLab CI/CD 카탈로그 블로그 글을 참조하세요.

구성 요소 프로젝트

  • 프로젝트당 구성 요소의 최대 수가 GitLab 16.9에서 10에서 30으로 변경됨.

구성 요소 프로젝트는 하나 이상의 구성 요소를 호스팅하는 저장소를 가진 GitLab 프로젝트입니다. 프로젝트 내의 모든 구성 요소는 최대 30개까지 함께 버전화됩니다.

구성 요소가 다른 구성 요소와 다른 버전 관리를 필요로 하는 경우, 해당 구성 요소는 별도의 구성 요소 프로젝트로 이동해야 합니다.

구성 요소 프로젝트 생성

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

  1. README.md 파일을 포함한 새 프로젝트를 작성합니다:
    • 설명란에서 해당 구성 요소에 대한 명확한 소개를 제공합니다.
    • 선택 사항. 프로젝트가 생성된 후에는 프로젝트 아바타를 추가할 수 있습니다.

    CI/CD 카탈로그에 게시된 구성 요소는 구성 요소 프로젝트의 요약을 표시할 때 설명 및 아바타 모두 사용합니다.

  2. 각 구성 요소에 대한 YAML 구성 파일을 추가합니다. 필수 디렉터리 구조를 따릅니다. 예: 

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

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

디렉터리 구조

저장소에는 다음이 있어야 합니다:

  • 저장소 내의 모든 구성 요소에 대한 세부 정보를 문서화하는 README.md Markdown 파일.
  • 모든 구성 요소 구성이 포함된 최상위 templates/ 디렉터리. 이 디렉터리에 구성을 정의할 수 있습니다:
    • 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: 구성요소 키워드를 사용하십시오. 구성 요소 참조는 <완전히-정규화된-도메인-이름>/<프로젝트-경로>/<구성-요소-이름>@<특정-버전> 형식으로 구성됩니다. 예를 들면: 

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

이 예제에서:

  • $CI_SERVER_FQDN은 GitLab 호스트와 일치하는 완전히 정규화된 도메인명(FQDN)에 대한 사전 정의된 변수입니다. 프로젝트가 사용 중인 GitLab 인스턴스 내에서만 구성 요소를 참조할 수 있습니다.
  • my-org/security-components은 구성 요소를 포함하는 프로젝트의 전체 경로입니다.
  • secret-detection은 단일 파일인 templates/secret-detection.yml로 정의되거나 templates/secret-detection/ 디렉토리 내에 template.yml을 포함하는 구성 요소 이름입니다.
  • 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 카탈로그에 게시되지 않을 수 있지만, 테스트에 사용될 수 있습니다.

의미 있는 버전 범위

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

다음을 지정하는 특별한 형식은 다음과 같습니다:

  • 마이너 버전의 경우, 참조에서 주 버전 및 마이너 버전을 사용하되 패치 버전은 사용하지 않습니다. 예를 들어, 1.1을 사용하여 1.1로 시작하는 최신 버전을 사용하고, 1.1.0 또는 1.1.9가 포함되지만 1.2.0는 포함되지 않습니다.
  • 메이저 버전의 경우, 참조에서 주 버전 번호만 사용합니다. 예를 들어, 1을 사용하여 1.0.0 또는 1.9.9와 같이 1.로 시작하는 최신 버전을 사용하지만 2.0.0는 사용하지 않습니다.
  • 모든 버전은 ~latest를 사용하여 최신 버전을 사용합니다.

예를 들어, 구성 요소가 다음과 같은 순서로 출시됩니다:

  1. 1.0.0
  2. 1.1.0
  3. 2.0.0
  4. 1.1.1
  5. 1.2.0
  6. 2.1.0
  7. 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 파일을 작성하려면 아래 사항을 준수해야 합니다:

  • 설명서는 프로젝트의 구성 요소가 제공하는 기능에 대한 개요로 시작해야 합니다.
  • 프로젝트에 여러 구성 요소가 포함된 경우 목차를 사용하여 사용자가 빠르게 특정 구성 요소의 세부 정보로 이동할 수 있도록 합니다.
  • 각 구성 요소에 대한 ### 구성 요소 A와 같은 하위 섹션을 포함하는 ## 구성 요소 섹션을 추가합니다.
  • 각 구성 요소 섹션에서:
    • 구성 요소가 하는 일에 대한 설명을 추가합니다.
    • 사용 방법을 보여주는 적어도 하나의 YAML 예제를 추가합니다.
    • 구성 요소가 입력을 사용하는 경우 이름, 설명, 유형 및 기본값이 포함된 테이블을 추가합니다.
    • 구성 요소가 변수나 비밀을 사용하는 경우 해당 정보를 문서화해야 합니다.
  • 기여가 환영되는 경우 ## 기여 섹션이 권장됩니다.

구성 요소에 대한 추가 지침이 필요한 경우, 구성 요소 디렉토리 내의 Markdown 파일에 추가 문서를 추가하고 해당 파일을 메인 README.md 파일에서 링크해야 합니다. 예를 들어: 

README.md    # 구체적인 문서.md로의 링크가 포함된 파일
templates/
├── component-1/
│   ├── template.yml
│   └── docs.md
└── component-2/
    ├── template.yml
    └── docs.md

구성 요소 README.md 예제는 GitLab CI/CD로 AWS에 배포하는 구성 요소의 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`의 구성 요소 작업이 추가되었는지 확인합니다.
# 이 예제 작업은 포함된 구성 요소가 예상대로 작동하는지도 테스트할 수 있습니다.
# 구성 요소에서 생성된 데이터를 검사하거나 GitLab API 엔드포인트나 타사 도구를 사용할 수 있습니다.
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("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 및 경로(https://gitlab.com/api/v4와 같은) 대신 $CI_API_V4_URL을 사용하세요.

이러한 사전 정의된 변수를 사용하면 구성 요소가 다른 인스턴스에서도 작동함이 보장됩니다. 예를 들어, 자체 관리 인스턴스에서 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입니다. 구성 요소 작업의 stage가 하드 코딩되어 있으면, 구성 요소를 사용하는 모든 파이프라인 반드시 정확히 동일한 stage를 정의하거나 구성 값 덮어쓰기를 해야 합니다.

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

예를 들어 사용자가 정의할 수 있는 stage 구성을 가진 구성을 만들기 위해서:

  • 구성요소 구성에서: 

    spec:
  inputs:
    stage:
      default: test
---
unit-test:
  stage: $[[ inputs.stage ]]
  script: echo 단위 테스트

integration-test:
  stage: $[[ inputs.stage ]]
  script: echo 통합 테스트

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

    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가 더 나은 해결책일 때 사용자에게 사용자 정의 변수를 정의하도록 요청하는 것을 피하세요.

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 카탈로그

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

CI/CD 카탈로그는 사용할 수 있는 게시된 CI/CD 구성 요소가 포함된 프로젝트 목록입니다.

누구나 구성 요소 프로젝트를 생성하여 CI/CD 카탈로그에 추가하거나 기존 프로젝트에 기여하여 사용 가능한 구성 요소를 개선할 수 있습니다.

클릭하여 데모를 확인하려면 CI/CD 카탈로그 베타 제품 투어를 참조하세요.

CI/CD 카탈로그 보기

CI/CD 카탈로그에 액세스하여 사용 가능한 게시된 구성 요소를 보려면 다음을 수행하세요:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택합니다.
  2. 탐색을 선택합니다.
  3. CI/CD 카탈로그를 선택합니다.

또는 이미 프로젝트의 파이프라인 에디터에 있는 경우 CI/CD 카탈로그를 선택할 수 있습니다.

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

  • 비공개인 경우, 해당 구성 요소의 소스 프로젝트에 할당된 최소한 게스트 역할의 사용자만 볼 수 있습니다.
  • 내부적인 경우, GitLab 인스턴스에 로그인한 사용자만 볼 수 있습니다.
  • 공개 인 경우, GitLab 인스턴스에 액세스 권한이 있는 누구나 볼 수 있습니다.

구성 요소 프로젝트 게시

CI/CD 카탈로그에서 구성 요소 프로젝트를 게시하려면 다음을 수행해야 합니다:

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

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

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

전제 조건:

  • 프로젝트에 소유자 역할이 있어야 합니다.

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

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
  2. 설정 > 일반을 선택합니다.
  3. 가시성, 프로젝트 기능, 권한을 확장합니다.
  4. CI/CD 카탈로그 프로젝트 토글을 켭니다.

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

이 설정을 자동화하여 사용하려면 mutationcatalogresourcescreate GraphQL 엔드포인트를 사용할 수 있습니다. Issue 463043에서 REST API에서 이를 노출하도록 제안하고 있습니다.

새 릴리스를 게시

CI/CD 구성 요소는 CI/CD 카탈로그에 목록되지 않은 상태에서도 사용될 수 있습니다. 그러나 구성 요소의 릴리스를 카탈로그에 게시하면 다른 사용자들이 더 쉽게 찾을 수 있게 됩니다.

전제 조건:

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

  1. 프로젝트의 .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: "$CI_COMMIT_TAG의 구성 요소 릴리스($CI_PROJECT_PATH 내의 컴포넌트)"

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

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

시맨틱 버전

컴포넌트의 태그 및 새 버전을 릴리스할 때, 시맨틱 버전을 사용해야 합니다. 시맨틱 버전은 변경 사항이 주요, 마이너, 패치 또는 다른 종류의 변경인지를 전달하는 표준입니다.

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

컴포넌트 프로젝트 취소 등록

카탈로그에서 컴포넌트 프로젝트를 제거하려면 프로젝트 설정에서 CI/CD 카탈로그 리소스 토글을 끄면 됩니다.

경고: 이 작업은 카탈로그에 게시된 컴포넌트 프로젝트와 해당 버전에 대한 메타데이터를 파기합니다. 프로젝트와 해당 저장소는 여전히 존재하지만 카탈로그에서는 보이지 않습니다.

카탈로그에 다시 컴포넌트 프로젝트를 게시하려면 새 릴리스를 게시해야 합니다.

검증된 컴포넌트 생성자

일부 CI/CD 컴포넌트는 GitLab에서 검증한 사용자에 의해 생성 및 유지관리된 것을 나타내는 아이콘으로 배지가 부여됩니다:

  • GitLab에서 유지관리 (): GitLab에서 생성 및 유지관리되는 컴포넌트입니다.
  • GitLab 파트너 (): GitLab에서 검증한 파트너가 독립적으로 생성하고 유지관리하는 컴포넌트입니다.

GitLab 파트너는 GitLab에서 검증한 파트너로 플래그를 지정하려면 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 컴포넌트로 변환할 수 있습니다:

  1. 기존 컴포넌트 프로젝트의 일부로 컴포넌트를 그룹화할지 또는 새 컴포넌트 프로젝트를 생성할지 결정합니다.
  2. 컴포넌트 프로젝트에 디렉터리 구조에 따라 YAML 파일을 생성합니다.
  3. 원본 템플릿 YAML 파일의 내용을 새로운 컴포넌트 YAML 파일로 복사합니다.
  4. 새로운 컴포넌트 구성을:
  5. 컴포넌트 저장소의 .gitlab-ci.yml을 활용하여 컴포넌트 변경 사항을 테스트합니다.
  6. 컴포넌트를 태그하고 릴리스합니다.

Go CI/CD 템플릿을 CI/CD 컴포넌트로 마이그레이션하는 실제 예제를 따라서 자세히 알아보세요.

GitLab.com 컴포넌트를 자체 관리형 인스턴스에서 사용

Tier: 프리미엄, 얼티메이트 Offering: Self-managed, GitLab Dedicated

GitLab 인스턴스의 새로운 설치는 게시된 CI/CD 컴포넌트가 전혀 없는 상태로 시작됩니다. 인스턴스의 카탈로그를 채우려면 다음을 수행할 수 있습니다:

자체 관리형 인스턴스에서 GitLab.com 컴포넌트를 미러링하려면:

  1. gitlab.com에 대한 네트워크 외부 요청이 허용되었는지 확인합니다.
  2. 새 그룹을 생성하여(권장 그룹: components) 컴포넌트 프로젝트를 호스팅합니다.
  3. 새로운 그룹에서 컴포넌트 프로젝트를 미러링합니다.
  4. 릴리스하지 않은 저장소를 미러링하는 경우 프로젝트 설명을 작성합니다. 미러링된 저장소는 설명을 복사하지 않습니다.
  5. 자체 호스트된 컴포넌트 프로젝트를 카탈로그 리소스로 설정합니다.
  6. 태그(일반적으로 최신 태그)에 대한 파이프라인을 실행하여 자체 호스트된 컴포넌트 프로젝트에서 새 릴리스를 게시합니다.

문제 해결

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에서 업데이트되어 이제 카탈로그 리소스의 최신 시맨틱 버전을 나타냅니다. 이 문제를 해결하려면 새 릴리스를 게시하세요.