히스토리

• GitLab 16.0에서 ci_namespace_catalog_experimental이라는 플래그와 함께 실험적 기능으로 도입. 기본적으로 비활성화됨.
• GitLab 16.2에서 GitLab.com 및 GitLab Self-Managed에서 활성화.
• GitLab 16.3에서 기능 플래그 ci_namespace_catalog_experimental 제거.
• GitLab 16.6에서 베타로 이동.
• GitLab 17.0에서 일반 공급(GA).

CI/CD 컴포넌트는 재사용 가능한 단일 파이프라인 구성 단위입니다. 컴포넌트를 사용하여 더 큰 파이프라인의 일부를 구성하거나, 완전한 파이프라인 구성 전체를 조합할 수 있습니다.

컴포넌트는 더 동적인 동작을 위해 입력 파라미터로 구성할 수 있습니다.

CI/CD 컴포넌트는 include 키워드로 추가하는 다른 종류의 구성과 유사하지만, 다음과 같은 몇 가지 장점이 있습니다:

• 컴포넌트는 CI/CD 카탈로그에 나열될 수 있습니다.
• 컴포넌트는 특정 버전으로 릴리스하고 사용할 수 있습니다.
• 여러 컴포넌트를 동일한 프로젝트에서 정의하고 함께 버전 관리할 수 있습니다.

직접 컴포넌트를 만드는 대신, CI/CD 카탈로그에서 필요한 기능을 가진 게시된 컴포넌트를 검색할 수도 있습니다.

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

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

컴포넌트 프로젝트#

히스토리

• 프로젝트당 최대 컴포넌트 수가 GitLab 16.9에서 10개에서 30개로 변경.
• 프로젝트당 최대 컴포넌트 수가 GitLab 18.5에서 30개에서 100개로 변경.

컴포넌트 프로젝트는 하나 이상의 컴포넌트를 호스팅하는 저장소가 있는 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 마크다운 파일.
• 모든 컴포넌트 구성을 포함하는 최상위 templates/ 디렉터리. 이 디렉터리에서:
  • templates/secret-detection.yml과 같이 각 컴포넌트에 대해 .yml로 끝나는 단일 파일을 사용할 수 있습니다.
  • templates/secret-detection/template.yml과 같이 각 컴포넌트에 대해 template.yml이 있는 하위 디렉터리를 만들 수 있습니다. 컴포넌트를 사용하는 다른 프로젝트는 template.yml 파일만 사용합니다. 이 디렉터리의 다른 파일은 컴포넌트와 함께 릴리스되지 않지만, 테스트나 컨테이너 이미지 빌드와 같은 용도로 사용할 수 있습니다.

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

• 프로젝트의 .gitlab-ci.yml을 구성하여 컴포넌트를 테스트하고 새 버전을 릴리스합니다.
• 컴포넌트 사용에 적용되는 원하는 라이선스가 포함된 LICENSE.md 파일을 추가합니다. 예를 들어 MIT 또는 Apache 2.0 오픈 소스 라이선스.

예시:

• 프로젝트에 단일 컴포넌트가 포함된 경우, 디렉터리 구조는 다음과 유사해야 합니다:

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

• 프로젝트에 여러 컴포넌트가 포함된 경우, 디렉터리 구조는 다음과 유사해야 합니다:

  ├── templates/
  │   ├── my-component.yml
  │   └── my-other-component/
  │       ├── template.yml
  │       ├── Dockerfile
  │       └── test.sh
  ├── LICENSE.md
  ├── README.md
  └── .gitlab-ci.yml
  

  이 예시에서:

  • my-component 컴포넌트의 구성은 단일 파일에 정의됩니다.
  • my-other-component 컴포넌트의 구성은 디렉터리에 여러 파일을 포함합니다. 컴포넌트를 사용하는 다른 프로젝트는 template.yml 파일만 사용할 수 있습니다.

컴포넌트 사용#

사전 요구 사항:

현재 그룹 또는 프로젝트를 포함하는 상위 그룹의 구성원인 경우:

• 프로젝트 상위 그룹의 가시성 수준에서 설정한 최소 권한을 보유해야 합니다. 예를 들어, 상위 프로젝트가 Private로 설정된 경우 Reporter, Developer, Maintainer, 또는 Owner 권한이 있어야 합니다.

컴포넌트를 프로젝트의 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 호스트와 일치하는 완전한 도메인 이름(FQDN)에 대한 사전 정의된 변수입니다. 프로젝트와 동일한 GitLab 인스턴스의 컴포넌트만 참조할 수 있습니다.
• my-org/security-components는 컴포넌트를 포함하는 프로젝트의 전체 경로입니다.
• secret-detection은 단일 파일 templates/secret-detection.yml이나 template.yml을 포함하는 디렉터리 templates/secret-detection/으로 정의된 컴포넌트 이름입니다.
• 1.0.0은 컴포넌트의 버전입니다.

파이프라인 구성과 컴포넌트 구성은 독립적으로 처리되지 않습니다. 파이프라인이 시작되면, 포함된 컴포넌트 구성은 파이프라인의 구성에 병합됩니다. 파이프라인과 컴포넌트 모두 동일한 이름의 구성을 포함하면, 예상치 못한 방식으로 상호 작용할 수 있습니다.

예를 들어, 동일한 이름의 두 job은 하나의 job으로 병합됩니다. 마찬가지로, 파이프라인의 job과 동일한 이름의 구성에 대해 extends를 사용하는 컴포넌트는 잘못된 구성을 확장할 수 있습니다. 컴포넌트의 구성을 재정의하려는 경우가 아니라면, 파이프라인과 컴포넌트가 동일한 이름의 구성을 공유하지 않도록 하십시오.

GitLab.com 컴포넌트를 GitLab Self-Managed 인스턴스에서 사용하려면 컴포넌트 프로젝트를 미러링해야 합니다.

컴포넌트 버전#

우선순위가 높은 순서대로, 컴포넌트 버전은 다음과 같을 수 있습니다:

• 커밋 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 카탈로그 컴포넌트를 참조할 때 부분 시맨틱 버전 번호와 ~latest 키워드를 사용하여 사양과 일치하는 최신 게시된 버전을 선택할 수 있습니다.

이 형식은 일반 프로젝트 컴포넌트가 아닌 게시된 CI/CD 카탈로그 컴포넌트에서만 작동합니다. 이를 통해 1.2 또는 ~latest와 같은 형식을 사용할 때 검증되어 카탈로그에 게시된 컴포넌트만 가져오도록 하며, 저장소의 테스트되지 않은 코드를 가져오지 않습니다.

이 접근 방식은 컴포넌트의 소비자와 작성자 모두에게 중요한 이점을 제공합니다:

• 사용자의 경우, 부분 버전 사용은 주요 릴리스의 중단 변경 위험 없이 마이너 또는 패치 업데이트를 자동으로 받는 훌륭한 방법입니다. 이를 통해 파이프라인이 안정성을 유지하면서 최신 버그 수정 및 보안 패치로 최신 상태를 유지할 수 있습니다.
• 컴포넌트 작성자의 경우, 부분 버전 지원을 통해 기존 파이프라인을 즉시 중단할 위험 없이 주요 버전을 릴리스할 수 있습니다. 부분 버전을 지정한 사용자는 계속해서 최신 호환 마이너 또는 패치 버전을 사용하여 자신의 속도로 파이프라인을 업데이트할 시간을 가질 수 있습니다.

사용:

• 최신 1.2.* 버전을 선택하려면 1.2 사용
• 최신 1.*.* 버전을 선택하려면 1 사용
• 최신 릴리스 버전을 선택하려면 ~latest 사용

예를 들어, 컴포넌트에 다음 버전이 있다고 가정합니다: 1.0.0, 1.1.0, 1.1.1, 1.2.0, 2.0.0, 2.0.1, 2.1.0

컴포넌트를 참조할 때:

• 1은 1.2.0을 선택
• 1.1은 1.1.1을 선택
• ~latest는 2.1.0을 선택

부분 버전 선택을 사용할 때 프리릴리스 버전은 가져오지 않습니다. 프리릴리스 버전을 가져오려면 전체 버전(예: 1.0.1-rc)을 지정하십시오.

컴포넌트에서 컴포넌트 컨텍스트 사용#

히스토리

• GitLab 18.6에서 ci_component_context_interpolation이라는 플래그와 함께 베타로 도입. 기본적으로 활성화됨.
• GitLab 18.7에서 일반 공급(GA). 기능 플래그 ci_component_context_interpolation 제거.

컴포넌트는 컴포넌트 컨텍스트 CI/CD 표현식을 사용하여 자신에 대한 메타데이터에 액세스할 수 있습니다. 컴포넌트 템플릿에서 이 표현식을 사용하여 버전, 커밋 SHA 및 기타 메타데이터를 동적으로 참조할 수 있습니다.

컴포넌트에서 컴포넌트 컨텍스트를 사용하려면:

1. spec:component 헤더에서 컴포넌트가 필요로 하는 컴포넌트 컨텍스트 필드를 선언합니다. spec:component는 name, sha, version, reference 필드를 지원합니다.
2. 컴포넌트 템플릿에서 CI/CD 표현식 $[[ component.field-name ]]을 사용하여 컨텍스트 필드를 참조합니다.

예를 들어, 동일한 버전으로 빌드된 Docker 이미지를 참조하는 컴포넌트:

spec:
  component: [name, version, reference]
  inputs:
    image_tag:
      default: latest
---

build-image:
  image: registry.example.com/$[[ component.name ]]:$[[ component.version ]]
  script:
    - echo "Building with component version $[[ component.version ]]"
    - echo "Component reference: $[[ component.reference ]]"

컴포넌트 컨텍스트를 사용하여 버전이 지정된 리소스를 참조할 수도 있습니다.

컴포넌트 spec 섹션#

컴포넌트 템플릿의 spec 섹션은 컴포넌트의 구성 및 입력을 정의합니다. spec 섹션에서 다음 키워드를 사용할 수 있습니다:

• description: CI/CD 카탈로그에 표시되는 컴포넌트의 간단한 설명을 제공합니다.
• inputs: 사용자가 컴포넌트 구성을 사용자 정의할 수 있는 입력 파라미터를 정의합니다.
• component: 보간에 사용할 수 있는 컴포넌트 컨텍스트 필드(name, sha, version, reference 등)를 선언합니다.

컴포넌트 작성#

이 섹션에서는 고품질 컴포넌트 프로젝트 생성을 위한 몇 가지 모범 사례를 설명합니다.

의존성 관리#

컴포넌트가 다른 컴포넌트를 사용하는 것이 가능하지만, 의존성을 신중하게 선택해야 합니다. 의존성을 관리하려면:

• 의존성을 최소화하세요. 약간의 중복이 의존성을 갖는 것보다 일반적으로 더 낫습니다.
• 가능한 경우 로컬 의존성을 사용하세요. 예를 들어, include:local을 사용하는 것은 여러 파일에서 동일한 Git SHA를 사용하도록 하는 좋은 방법입니다.
• 다른 프로젝트의 컴포넌트에 의존할 때, ~latest나 Git 참조와 같은 이동하는 대상 버전 대신 카탈로그 릴리스에 버전을 고정하세요. 릴리스나 Git SHA를 사용하면 항상 동일한 리비전을 가져오고 컴포넌트 소비자가 일관된 동작을 얻도록 보장합니다.
• 의존성을 최신 릴리스에 고정하여 정기적으로 업데이트하세요. 그런 다음 업데이트된 의존성으로 컴포넌트의 새 릴리스를 게시하세요.
• 의존성의 권한을 평가하고, 최소 권한이 필요한 의존성을 사용하세요. 예를 들어, 이미지를 빌드해야 하는 경우 권한 있는 Docker 데몬이 있는 Runner가 필요하지 않도록 Docker 대신 Buildah를 사용하는 것을 고려하세요.

명확한 README.md 작성#

각 컴포넌트 프로젝트에는 명확하고 포괄적인 문서가 있어야 합니다. 좋은 README.md 파일을 작성하려면:

• 컴포넌트가 제공하는 기능의 요약으로 시작하세요.
• 프로젝트에 여러 컴포넌트가 포함된 경우, 목차를 사용하여 사용자가 특정 컴포넌트 세부 정보로 빠르게 이동할 수 있도록 하세요.
• 각 컴포넌트에 대한 하위 섹션(### 컴포넌트 A 등)이 있는 ## 컴포넌트 섹션을 추가하세요.
• 각 컴포넌트 섹션에서:
  • 컴포넌트가 하는 일을 설명하세요.
  • 사용 방법을 보여주는 YAML 예시를 최소 하나 추가하세요.
  • spec:inputs:description을 사용하여 컴포넌트가 사용하는 변수나 시크릿을 문서화하세요.
  • README에서 입력 문서를 중복하지 마세요. 입력은 컴포넌트 페이지에 자동으로 표시됩니다. 대신 게시된 컴포넌트로 링크하세요.
• 기여를 환영하는 경우 ## 기여 섹션을 추가하세요.

컴포넌트에 더 많은 지침이 필요한 경우, 컴포넌트 디렉터리의 마크다운 파일에 추가 문서를 추가하고 메인 README.md 파일에서 링크하세요. 예시:

README.md    # with links to the specific docs.md
templates/
├── component-1/
│   ├── template.yml
│   └── docs.md
└── component-2/
    ├── template.yml
    └── docs.md

예시는 AWS 컴포넌트 README를 참조하세요.

컴포넌트 테스트#

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

루트 디렉터리에 .gitlab-ci.yml을 만들어 CI/CD 파이프라인에서 변경 사항을 테스트합니다(다른 프로젝트와 같이). 컴포넌트의 동작과 잠재적인 부작용을 모두 테스트하는지 확인하십시오. 필요한 경우 GitLab API를 사용할 수 있습니다.

예시:

include:
  # include the component located in the current project from the current SHA
  - component: $CI_SERVER_FQDN/$CI_PROJECT_PATH/my-component@$CI_COMMIT_SHA
    inputs:
      stage: build

stages: [build, test, release]

# Check if `component job of my-component` is added.
# This example job could also test that the included component works as expected.
# You can inspect data generated by the component, use GitLab API endpoints, or third-party tools.
ensure-job-added:
  stage: test
  image: badouralix/curl-jq
  # Replace "component job of my-component" with the job name in your component.
  script:
    - |
      route="${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/pipelines/${CI_PIPELINE_ID}/jobs"
      count=`curl --silent --header "JOB-TOKEN: ${CI_JOB_TOKEN}" "$route" | jq 'map(select(.name | contains("component job of my-component"))) | length'`
      if [ "$count" != "1" ]; then
        exit 1; else
        echo "Component Job present"
      fi

# If the pipeline is for a new tag with a semantic version, and all previous jobs succeed,
# create the release.
create-release:
  stage: release
  image: registry.gitlab.com/gitlab-org/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 repository $CI_PROJECT_PATH"

변경 사항을 커밋하고 푸시하면, 파이프라인이 컴포넌트를 테스트한 다음, 이전 job이 통과하면 릴리스를 생성합니다.

샘플 파일에 대해 컴포넌트 테스트#

경우에 따라 컴포넌트는 소스 파일과 상호 작용해야 합니다. 예를 들어, Go 소스 코드를 빌드하는 컴포넌트는 테스트를 위해 일부 Go 샘플이 필요할 수 있습니다. 또는 Docker 이미지를 빌드하는 컴포넌트는 테스트를 위해 일부 샘플 Dockerfile이 필요할 수 있습니다.

컴포넌트 테스트 중에 사용하기 위해 이러한 샘플 파일을 컴포넌트 프로젝트에 직접 포함할 수 있습니다.

자세한 내용은 컴포넌트 테스트 예시를 참조하세요.

인스턴스 또는 프로젝트별 값 하드코딩 방지#

컴포넌트에서 다른 컴포넌트를 사용할 때, 인스턴스의 완전한 도메인 이름(gitlab.com 등) 대신 $CI_SERVER_FQDN을 사용하세요.

컴포넌트에서 GitLab API에 액세스할 때, 인스턴스의 전체 URL 및 경로(https://gitlab.com/api/v4 등) 대신 $CI_API_V4_URL을 사용하세요.

이 사전 정의된 변수를 사용하면 컴포넌트가 다른 인스턴스에서 사용될 때도 작동하도록 보장합니다. 예를 들어 GitLab Self-Managed 인스턴스에서 GitLab.com 컴포넌트를 사용할 때도 마찬가지입니다.

API 리소스가 항상 공개적이라고 가정하지 마세요#

컴포넌트와 테스트 파이프라인이 GitLab Self-Managed에서도 작동하는지 확인하십시오. GitLab.com의 공개 프로젝트의 일부 API 리소스는 인증되지 않은 요청으로 액세스할 수 있지만, GitLab Self-Managed 인스턴스에서는 컴포넌트 프로젝트가 비공개 또는 내부 프로젝트로 미러링될 수 있습니다.

GitLab Self-Managed 인스턴스에서 요청을 인증하기 위해 입력이나 변수를 통해 액세스 토큰을 선택적으로 제공할 수 있도록 하는 것이 중요합니다.

전역 키워드 사용 방지#

컴포넌트에서 전역 키워드 사용을 피하세요. 컴포넌트에서 이러한 키워드를 사용하면 메인 .gitlab-ci.yml에서 직접 정의된 job이나 다른 포함된 컴포넌트의 job을 포함한 파이프라인의 모든 job에 영향을 미칩니다.

전역 키워드의 대안으로:

• 컴포넌트 구성에서 일부 중복이 생기더라도 각 job에 직접 구성을 추가하세요.
• 컴포넌트에서 extends 키워드를 사용하되, 컴포넌트가 구성에 병합될 때 이름 충돌 위험을 줄이는 고유한 이름을 사용하세요.

예를 들어, default 전역 키워드 사용을 피하세요:

# Not recommended
default:
  image: ruby:3.0

rspec-1:
  script: bundle exec rspec dir1/

rspec-2:
  script: bundle exec rspec dir2/

대신 다음을 수행할 수 있습니다:

• 각 job에 명시적으로 구성 추가:

  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입니다. 컴포넌트 job의 스테이지가 하드코딩된 경우, 컴포넌트를 사용하는 모든 파이프라인은 정확히 동일한 스테이지를 정의하거나 구성을 재정의해야 합니다.

선호하는 방법은 동적 컴포넌트 구성에 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
  

입력으로 job 이름 정의#

stage 키워드의 값과 마찬가지로, CI/CD 컴포넌트에서 job 이름을 하드코딩하는 것을 피해야 합니다. 컴포넌트 사용자가 job 이름을 사용자 정의할 수 있으면, 파이프라인의 기존 이름과 충돌을 방지할 수 있습니다. 사용자는 다른 이름을 사용하여 컴포넌트를 여러 번 포함할 수도 있습니다.

inputs를 사용하여 컴포넌트 사용자가 특정 job 이름이나 job 이름 접두사를 정의할 수 있도록 하세요. 예시:

spec:
  inputs:
    job-prefix:
      description: "Define a prefix for the job name"
    job-name:
      description: "Alternatively, define the job's name"
    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 카탈로그#

히스토리

• GitLab 16.1에서 실험으로 도입.
• GitLab 16.7에서 베타로 이동.
• GitLab 17.0에서 일반 공급(GA).

CI/CD 카탈로그는 CI/CD 워크플로를 확장하는 데 사용할 수 있는 게시된 CI/CD 컴포넌트가 있는 프로젝트 목록입니다.

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

클릭스루 데모는 CI/CD 카탈로그 베타 제품 투어를 참조하세요.

CI/CD 카탈로그 보기#

CI/CD 카탈로그에 액세스하고 사용 가능한 게시된 컴포넌트를 보려면:

1. 상단 표시줄에서 검색 또는 이동을 선택합니다.
2. 탐색을 선택합니다.
3. CI/CD 카탈로그를 선택합니다.

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

CI/CD 카탈로그에서 컴포넌트의 가시성은 컴포넌트 소스 프로젝트의 가시성 설정을 따릅니다. 소스 프로젝트가 다음으로 설정된 컴포넌트:

• Private: 소스 컴포넌트 프로젝트에 Guest, Planner, Reporter, Developer, Maintainer, 또는 Owner 권한이 할당된 사용자만 볼 수 있습니다. 컴포넌트를 사용하려면 Reporter, Developer, Maintainer, 또는 Owner 권한이 있어야 합니다.
• Internal: GitLab 인스턴스에 로그인한 사용자만 볼 수 있습니다.
• Public: GitLab 인스턴스에 액세스할 수 있는 모든 사람이 볼 수 있습니다.

카탈로그 리소스 분석 보기#

히스토리

• GitLab 18.9에서 도입.

CI/CD 카탈로그 리소스를 관리하는 경우, 프로젝트 전반에서 컴포넌트가 어떻게 채택되고 있는지 이해하기 위해 사용 분석을 볼 수 있습니다.

사전 요구 사항:

• 하나 이상의 카탈로그 리소스 프로젝트에 Maintainer 또는 Owner 권한이 있어야 합니다.

카탈로그 리소스 분석을 보려면:

1. 상단 표시줄에서 검색 또는 이동 > 탐색을 선택합니다.
2. CI/CD 카탈로그를 선택합니다.
3. 분석 탭을 선택합니다.

분석 보기는 Maintainer 또는 Owner 권한이 있는 카탈로그 리소스를 표시합니다. 이 보기는 다음을 보여줍니다:

• 프로젝트: 카탈로그 리소스 이름 및 최신 릴리스 버전.
• 사용 통계: 지난 30일 동안 파이프라인에서 이 카탈로그 리소스의 컴포넌트를 사용한 고유 프로젝트 수.
• 컴포넌트: 카탈로그 리소스의 최신 버전에서 사용 가능한 컴포넌트 목록.

이 정보를 사용하여:

• 가장 널리 채택된 카탈로그 리소스를 식별합니다.
• 시간이 지남에 따른 컴포넌트 사용 추세를 추적합니다.
• 카탈로그 리소스를 사용하는 프로젝트를 이해합니다.
• 컴포넌트 유지 관리 및 사용 중단에 대한 정보에 입각한 결정을 내립니다.

컴포넌트 프로젝트 게시#

CI/CD 카탈로그에 컴포넌트 프로젝트를 게시하려면:

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

컴포넌트 프로젝트를 카탈로그 프로젝트로 설정#

컴포넌트 프로젝트의 게시된 버전을 CI/CD 카탈로그에 표시하려면, 프로젝트를 카탈로그 프로젝트로 설정해야 합니다.

사전 요구 사항:

• 프로젝트에 Owner 권한이 있어야 합니다.

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

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

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

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

새 릴리스 게시#

CI/CD 컴포넌트는 CI/CD 카탈로그에 나열되지 않고도 사용할 수 있습니다. 그러나 카탈로그에 컴포넌트의 릴리스를 게시하면 다른 사용자가 검색할 수 있게 됩니다.

사전 요구 사항:

• 프로젝트에 Maintainer 또는 Owner 권한이 있어야 합니다.
• 프로젝트는:
  • 카탈로그 프로젝트로 설정되어 있어야 합니다.
  • 프로젝트 설명이 정의되어 있어야 합니다.
  • 릴리스되는 태그의 커밋 SHA에 대해 루트 디렉터리에 README.md 파일이 있어야 합니다.
  • 릴리스되는 태그의 커밋 SHA에 대해 templates/ 디렉터리에 최소 하나의 CI/CD 컴포넌트가 있어야 합니다.
• Releases API가 아닌 CI/CD job에서 release 키워드를 사용하여 릴리스를 생성해야 합니다.

카탈로그에 컴포넌트의 새 버전을 게시하려면:

1. 태그가 생성될 때 새 릴리스를 생성하기 위해 release 키워드를 사용하는 job을 프로젝트의 .gitlab-ci.yml 파일에 추가합니다. 릴리스 job을 실행하기 전에 컴포넌트를 테스트하도록 태그 파이프라인을 구성해야 합니다. 예시:

   create-release:
     stage: release
     image: registry.gitlab.com/gitlab-org/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"
   

2. 릴리스에 대한 새 태그를 생성합니다. 이는 릴리스 생성을 담당하는 job이 포함된 태그 파이프라인을 트리거해야 합니다. 태그는 시맨틱 버전을 사용해야 합니다.

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

시맨틱 버전#

히스토리

• GitLab 16.10에서 도입.

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

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

컴포넌트 프로젝트 게시 취소#

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

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

인증된 컴포넌트 제작자#

히스토리

• GitLab 16.11에서 GitLab.com에 대해 도입
• GitLab 18.1에서 GitLab Self-Managed 및 GitLab Dedicated에 대해 도입

일부 CI/CD 컴포넌트에는 GitLab 또는 인스턴스 관리자가 인증한 사용자가 생성하고 유지 관리한다는 것을 표시하는 아이콘이 배지로 표시됩니다:

• GitLab 유지 관리 ([tanuki-verified]): GitLab에서 생성하고 유지 관리하는 GitLab.com 컴포넌트.

• GitLab 파트너 ([partner-verified]): GitLab 인증 파트너가 독립적으로 생성하고 유지 관리하는 GitLab.com 컴포넌트.

  GitLab 파트너는 GitLab 파트너 얼라이언스 구성원에게 연락하여 GitLab.com의 네임스페이스를 GitLab 인증으로 플래그 지정할 수 있습니다. 그러면 해당 네임스페이스의 프로젝트에 있는 모든 CI/CD 컴포넌트에 GitLab 파트너 컴포넌트로 배지가 표시됩니다. 파트너 얼라이언스 구성원은 인증된 파트너를 대신하여 내부 요청 이슈(GitLab 팀원 전용)를 생성합니다.

  [!warning] GitLab 파트너가 생성한 컴포넌트는 어떠한 종류의 보증도 없이 있는 그대로 제공됩니다. 최종 사용자의 GitLab 파트너 생성 컴포넌트 사용은 자신의 위험 부담이며, GitLab은 최종 사용자의 컴포넌트 사용과 관련하여 어떠한 배상 의무도 없으며 어떠한 종류의 책임도 없습니다. 그러한 콘텐츠의 최종 사용자 사용 및 이와 관련된 모든 책임은 콘텐츠 게시자와 최종 사용자 간의 문제입니다.

• 인증된 제작자 ([check-sm]): 관리자가 인증한 사용자가 생성하고 유지 관리하는 컴포넌트.

인증된 제작자가 관리하는 컴포넌트로 설정#

히스토리

• GitLab 18.1에서 GitLab Self-Managed 및 GitLab Dedicated에 대해 도입

GitLab 관리자는 CI/CD 컴포넌트를 인증된 제작자가 생성하고 유지 관리하는 것으로 설정할 수 있습니다:

1. 관리자 계정으로 인스턴스에서 GraphiQL을 열고, 예를 들어: https://gitlab.example.com/-/graphql-explorer.

2. 다음 쿼리를 실행하고, root-level-group을 인증할 컴포넌트의 루트 네임스페이스로 대체합니다:

   mutation {
     verifiedNamespaceCreate(input: { namespacePath: "root-level-group",
       verificationLevel: VERIFIED_CREATOR_SELF_MANAGED
       }) {
       errors
     }
   }
   

쿼리가 완료되면, 루트 네임스페이스의 프로젝트에 있는 모든 컴포넌트가 인증됩니다. 인증된 제작자 배지가 CI/CD 카탈로그의 컴포넌트 이름 옆에 표시됩니다.

컴포넌트에서 배지를 제거하려면, verificationLevel에 UNVERIFIED를 사용하여 쿼리를 반복하세요.

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 컴포넌트를 GitLab Self-Managed에서 사용#

GitLab 인스턴스의 새 설치의 CI/CD 카탈로그는 게시된 CI/CD 컴포넌트 없이 시작됩니다. 인스턴스의 카탈로그를 채우려면:

• 자체 컴포넌트를 게시합니다.
• GitLab Self-Managed 인스턴스에서 GitLab.com의 컴포넌트를 미러링합니다.

GitLab Self-Managed 인스턴스에서 GitLab.com 컴포넌트를 미러링하려면:

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

CI/CD 컴포넌트 보안 모범 사례#

컴포넌트 사용자를 위해#

누구나 카탈로그에 컴포넌트를 게시할 수 있으므로, 프로젝트에서 컴포넌트를 사용하기 전에 신중하게 검토해야 합니다. GitLab CI/CD 컴포넌트 사용은 자신의 위험 부담이며, GitLab은 타사 컴포넌트의 보안을 보장할 수 없습니다.

타사 CI/CD 컴포넌트를 사용할 때 다음 보안 모범 사례를 고려하세요:

• 컴포넌트 소스 코드 감사 및 검토: 악의적인 콘텐츠가 없는지 코드를 주의 깊게 검사합니다.
• 자격 증명 및 토큰에 대한 액세스 최소화:
  • 자격 증명이나 토큰이 예상하고 승인한 작업을 수행하는 데만 사용되는지 확인하기 위해 컴포넌트의 소스 코드를 감사합니다.
  • 최소 범위의 액세스 토큰을 사용합니다.
  • 수명이 긴 액세스 토큰이나 자격 증명 사용을 피합니다.
  • CI/CD 컴포넌트가 사용하는 자격 증명 및 토큰 사용을 감사합니다.
• 고정된 버전 사용: CI/CD 컴포넌트를 특정 커밋 SHA(선호) 또는 릴리스 버전 태그에 고정하여 파이프라인에서 사용되는 컴포넌트의 무결성을 보장합니다. 컴포넌트 유지 관리자를 신뢰하는 경우에만 릴리스 태그를 사용합니다. latest 사용을 피합니다.
• 시크릿 안전하게 저장: CI/CD 구성 파일에 시크릿을 저장하지 않습니다. 외부 시크릿 관리 솔루션을 사용할 수 있는 경우 프로젝트 설정에 시크릿과 자격 증명을 저장하는 것을 피합니다.
• 임시적이고 격리된 러너 환경 사용: 가능한 경우 임시적이고 격리된 환경에서 컴포넌트 job을 실행합니다. 자체 관리 러너의 보안 위험에 유의합니다.
• 캐시 및 아티팩트 안전하게 처리: 절대적으로 필요하지 않은 한 파이프라인의 다른 job에서 CI/CD 컴포넌트 job으로 캐시나 아티팩트를 전달하지 않습니다.
• CI_JOB_TOKEN 액세스 제한: CI/CD 컴포넌트를 사용하는 프로젝트에 대해 CI/CD job 토큰(CI_JOB_TOKEN) 프로젝트 액세스 및 권한을 제한합니다.
• CI/CD 컴포넌트 변경 사항 검토: 컴포넌트의 업데이트된 커밋 SHA 또는 릴리스 태그를 사용하도록 변경하기 전에 CI/CD 컴포넌트 구성의 모든 변경 사항을 주의 깊게 검토합니다.
• 사용자 지정 컨테이너 이미지 감사: CI/CD 컴포넌트가 사용하는 사용자 지정 컨테이너 이미지가 악의적인 콘텐츠가 없는지 주의 깊게 검토합니다.

컴포넌트 유지 관리자를 위해#

보안적이고 신뢰할 수 있는 CI/CD 컴포넌트를 유지 관리하고 사용자에게 제공하는 파이프라인 구성의 무결성을 보장하려면 다음 모범 사례를 따르세요:

• 이중 인증(2FA) 사용: 모든 CI/CD 컴포넌트 프로젝트 유지 관리자와 소유자가 2FA를 활성화하거나, 그룹의 모든 사용자에 대해 2FA를 적용하세요.
• 보호된 브랜치 사용:
  • 컴포넌트 프로젝트 릴리스에 보호된 브랜치를 사용하세요.
  • 기본 브랜치를 보호하고 와일드카드 규칙을 사용하여 모든 릴리스 브랜치를 보호하세요.
  • 보호된 브랜치에 대한 변경을 위해 머지 리퀘스트를 제출하도록 모든 사람에게 요구하세요. 보호된 브랜치에 대해 푸시 및 머지 허용 옵션을 No one으로 설정하세요.
  • 보호된 브랜치로의 강제 푸시를 차단하세요.
• 모든 커밋 서명: 컴포넌트 프로젝트에 대한 모든 커밋에 서명하세요.
• latest 사용 억제: @latest를 사용하는 예시를 README.md에 포함하지 마세요.
• 다른 job의 캐시 및 아티팩트에 대한 의존성 제한: 절대적으로 필요한 경우에만 CI/CD 컴포넌트에서 다른 job의 캐시 및 아티팩트를 사용하세요.
• CI/CD 컴포넌트 의존성 업데이트: 의존성 업데이트를 정기적으로 확인하고 적용하세요.
• 변경 사항 신중하게 검토:
  • 기본 또는 릴리스 브랜치에 머지하기 전에 CI/CD 컴포넌트 파이프라인 구성의 모든 변경 사항을 주의 깊게 검토합니다.
  • CI/CD 컴포넌트 카탈로그 프로젝트에 대한 사용자 대면 변경 사항 모두에 대해 머지 리퀘스트 승인을 사용하세요.

문제 해결#

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에서 업데이트되었습니다. 이제 카탈로그 리소스의 최신 시맨틱 버전을 참조합니다. 이 문제를 해결하려면 새 릴리스를 생성하세요.

오류: Build component error: Spec must be a valid json schema#

컴포넌트의 형식이 잘못된 경우, 릴리스를 생성할 수 없고 Build component error: Spec must be a valid json schema와 같은 오류를 받을 수 있습니다.

이 오류는 spec:inputs 섹션이 비어 있는 경우 발생할 수 있습니다. 구성이 입력을 사용하지 않는 경우, 대신 spec 섹션을 비워 둘 수 있습니다. 예시:

spec:
---

my-component:
  script: echo