CI/CD 카탈로그의 도입으로 인해, GitLab은 더 이상 코드베이스에 새로운 CI/CD 템플릿 기여를 수락하지 않습니다. 대신, 팀원들이 카탈로그를 위한 CI/CD 컴포넌트를 생성하도록 권장합니다. 이 전환은 공유 CI/CD 리소스의 모듈성과 유지보수성을 향상시키고, 새로운 CI/CD 템플릿 기여의 복잡성을 방지합니다. 기존 템플릿을 업데이트해야 하는 경우, 일치하는 CI/CD 컴포넌트도 함께 업데이트해야 합니다. CI/CD 템플릿과 일치하는 컴포넌트가 아직 존재하지 않는 경우, 일치하는 컴포넌트 생성을 고려하세요. 이를 통해 템플릿과 컴포넌트 기능이 동기화 상태를 유지하며, 새로운 개발 관행에 부합하게 됩니다.

이 문서에서는 GitLab CI/CD 템플릿을 개발하는 방법을 설명합니다.

CI/CD 템플릿 요건#

새 CI/CD 템플릿을 추가하거나 기존 템플릿을 업데이트하는 머지 리퀘스트를 제출하기 전에 다음 사항을 완료해야 합니다:

• 올바른 디렉터리에 템플릿을 배치합니다.

• CI/CD 템플릿 작성 가이드라인을 따릅니다.

• *.gitlab-ci.yml 형식으로 템플릿 이름을 지정합니다.

• 유효한 .gitlab-ci.yml 문법을 사용합니다. CI/CD lint 도구로 유효성을 검증하세요.

• 템플릿 메트릭을 추가합니다.

• 머지 리퀘스트가 사용자 대면 변경 사항을 도입하는 경우 변경 이력(changelog)을 포함합니다.

• 템플릿 검토 프로세스를 따릅니다.

• (선택 사항이지만 강력히 권장) 검토자가 접근할 수 있는 예시 GitLab 프로젝트에서 템플릿을 테스트합니다. 검토자가 템플릿에 필요한 데이터나 구성을 직접 만들지 못할 수 있으므로, 예시 프로젝트는 검토자가 템플릿의 정확성을 확인하는 데 도움이 됩니다. 머지 리퀘스트를 검토를 위해 제출하기 전에 예시 프로젝트의 파이프라인이 성공해야 합니다.

템플릿 디렉터리#

모든 템플릿 파일은 lib/gitlab/ci/templates에 저장됩니다. 일반 템플릿은 이 디렉터리에 저장하되, 특정 템플릿 유형은 별도로 예약된 디렉터리가 있습니다. 새 파일 UI에서 템플릿을 선택할 수 있는지 여부는 템플릿이 있는 디렉터리에 따라 결정됩니다:

템플릿 작성 가이드라인#

다음 가이드라인을 사용하여 템플릿 제출이 표준을 따르는지 확인하세요:

템플릿 유형#

템플릿에는 두 가지 유형이 있으며, 이는 템플릿을 작성하고 사용하는 방식에 영향을 미칩니다. 템플릿의 스타일은 다음 두 가지 유형 중 하나와 일치해야 합니다:

파이프라인 템플릿은 프로젝트의 구조, 언어 등에 맞는 엔드투엔드 CI/CD 워크플로를 제공합니다. 이는 보통 다른 .gitlab-ci.yml 파일이 없는 프로젝트에서 단독으로 사용해야 합니다.

파이프라인 템플릿을 작성할 때:

• image나 before_script 같은 전역 키워드는 템플릿 상단의 default 섹션에 배치합니다.

• 템플릿이 기존 .gitlab-ci.yml 파일에서 includes 키워드와 함께 사용하도록 설계되었는지 여부를 코드 주석에 명확하게 기재합니다.

job 템플릿은 특정 작업을 수행하기 위해 기존 CI/CD 워크플로에 추가할 수 있는 특정 job을 제공합니다. 보통 includes 키워드를 사용하여 기존 .gitlab-ci.yml 파일에 추가하여 사용해야 합니다. 기존 .gitlab-ci.yml 파일에 내용을 복사하여 붙여넣을 수도 있습니다.

job 템플릿은 사용자가 현재 파이프라인에 수정 없이 또는 최소한의 수정으로 추가할 수 있도록 구성합니다. 다른 파이프라인 구성과의 충돌 위험을 줄이도록 구성해야 합니다.

job 템플릿을 작성할 때:

• 전역 또는 default 키워드를 사용하지 않습니다. 루트 .gitlab-ci.yml이 템플릿을 포함할 때, 전역 또는 default 키워드가 재정의되어 예기치 않은 동작을 일으킬 수 있습니다. job 템플릿에 특정 Stage가 필요한 경우, 사용자가 메인 .gitlab-ci.yml 구성에 해당 Stage를 수동으로 추가해야 함을 코드 주석에 설명합니다.

• 템플릿이 includes 키워드와 함께 사용하거나 기존 구성에 복사하도록 설계되었음을 코드 주석에 명확하게 기재합니다.

• 하위 호환성 문제를 방지하기 위해 최신(latest) 버전과 안정(stable) 버전으로 템플릿의 버전 관리를 고려합니다. 이 유형의 템플릿 유지보수는 더 복잡한데, includes로 가져온 템플릿의 변경 사항이 해당 템플릿을 사용하는 모든 프로젝트의 파이프라인을 깨뜨릴 수 있기 때문입니다.

템플릿을 작성할 때 추가로 고려해야 할 사항:

문법 가이드라인#

템플릿을 더 쉽게 이해할 수 있도록, 모든 템플릿은 일관된 형식으로 명확한 문법 스타일을 사용해야 합니다.

모든 job의 before_script, script, after_script 키워드는 ShellCheck을 사용하여 린트되며, 가능한 한 셸 스크립팅 표준 및 스타일 가이드라인을 따라야 합니다.

ShellCheck은 스크립트가 Bash를 사용하여 실행되도록 설계되었다고 가정합니다. Bash ShellCheck 규칙과 호환되지 않는 셸용 스크립트를 사용하는 템플릿은 ShellCheck 린트에서 제외할 수 있습니다. 스크립트를 제외하려면 scripts/lint_templates_bash.rb의 EXCLUDED_TEMPLATES 목록에 추가합니다.

기본 브랜치를 하드코딩하지 않기#

하드코딩된 main 브랜치 대신 $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH를 사용하고, master는 절대 사용하지 않습니다:

job:
  rules:
    if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
  script:
    echo "example job"

only나 except 대신 rules 사용#

가능하면 only 또는 except 사용을 피합니다. only와 except는 더 이상 개발되지 않으며, rules가 현재 권장되는 문법입니다:

job2:
  script:
    - echo
  rules:
    - if: $CI_COMMIT_BRANCH

긴 명령 분할#

명령이 매우 길거나 -o 또는 --option과 같은 많은 커맨드라인 플래그가 있는 경우:

• 명령의 각 부분을 쉽게 볼 수 있도록 여러 줄 명령으로 분할합니다.

• 가능한 경우 플래그의 긴 이름을 사용합니다.

예를 들어, docker run --e SOURCE_CODE="$PWD" -v "$PWD":/code -v /var/run/docker.sock:/var/run/docker.sock "$CODE_QUALITY_IMAGE" /code와 같이 짧은 CLI 플래그가 있는 긴 명령의 경우:

job1:
  script:
    - docker run
        --env SOURCE_CODE="$PWD"
        --volume "$PWD":/code
        --volume /var/run/docker.sock:/var/run/docker.sock
        "$CODE_QUALITY_IMAGE" /code

| 및 > YAML 연산자를 사용하여 여러 줄 명령을 분할할 수도 있습니다.

주석으로 템플릿 설명하기#

새 파일 메뉴에서 템플릿 내용에 접근할 수 있으며, 이것이 사용자가 템플릿에 대한 정보를 볼 수 있는 유일한 곳일 수 있습니다. 템플릿의 동작을 템플릿 자체에 명확하게 문서화하는 것이 중요합니다.

다음 가이드라인은 모든 템플릿 제출에서 기대되는 기본 주석을 다룹니다. 주석이 사용자나 템플릿 검토자에게 도움이 될 것이라고 생각되면 추가 주석을 더합니다.

요건 및 기대 사항 설명#

파일 상단의 # 주석에 템플릿 사용 방법에 대한 세부 정보를 제공합니다. 여기에는 다음이 포함됩니다:

• 리포지터리/프로젝트 요건.

• 예상 동작.

• 템플릿을 사용하기 전에 사용자가 편집해야 하는 곳.

• 템플릿을 구성 파일에 복사하여 붙여넣어야 하는지, 아니면 기존 파이프라인에서 include 키워드와 함께 사용해야 하는지 여부.

• 프로젝트의 CI/CD 설정에 저장해야 하는 변수가 있는지 여부.

# Use this template to publish an application that uses the ABC server.
# You can copy and paste this template into a new `.gitlab-ci.yml` file.
# You should not add this template to an existing `.gitlab-ci.yml` file by using the `include:` keyword.
#
# Requirements:
# - An ABC project with content saved in /content and tests in /test
# - A CI/CD variable named ABC-PASSWORD saved in the project CI/CD settings. The value
#   should be the password used to deploy to your ABC server.
# - An ABC server configured to listen on port 12345.
#
# You must change the URL on line 123 to point to your ABC server and port.
#
# For more information, see https://gitlab.com/example/abcserver/README.md

job1:
  ...

변수가 템플릿 동작에 미치는 영향 설명#

템플릿이 변수를 사용하는 경우, 처음 정의되는 곳에 # 주석으로 설명합니다. 변수가 명백히 이해되는 경우에는 주석을 생략할 수 있습니다:

variables:                        # Good to have a comment here, for example:
  TEST_CODE_PATH: <path/to/code>  # Update this variable with the relative path to your Ruby specs

job1:
  variables:
    ERROR_MESSAGE: "The $TEST_CODE_PATH path is invalid"  # (No need for a comment here, it's already clear)
  script:
    - echo ${ERROR_MESSAGE}

비로컬 변수에 대문자 이름 사용#

CI/CD 설정이나 variables 키워드를 통해 제공될 것으로 예상되는 변수는 단어를 구분하는 밑줄(_)과 함께 대문자 이름을 사용해야 합니다.

.with_login:
  before_script:
    # SECRET_TOKEN should be provided via the project settings
    - echo "$SECRET_TOKEN" | docker login -u my-user --password-stdin my-registry

script 키워드 중 하나에서 로컬로 정의된 변수에는 소문자 이름을 선택적으로 사용할 수 있습니다:

job1:
  script:
    - response="$(curl "https://example.com/json")"
    - message="$(echo "$response" | jq -r .message)"
    - 'echo "Server responded with: $message"'

하위 호환성#

템플릿은 include:template: 키워드로 동적으로 포함될 수 있습니다. 기존 템플릿을 변경하는 경우, 기존 프로젝트의 CI/CD가 깨지지 않는지 반드시 확인해야 합니다.

예를 들어, 템플릿에서 job 이름을 변경하면 기존 프로젝트의 파이프라인이 깨질 수 있습니다. 이 예에서 Performance.gitlab-ci.yml이라는 템플릿에는 다음 내용이 있습니다:

performance:
  image: registry.gitlab.com/gitlab-org/verify-tools/performance:v0.1.0
  script: ./performance-test $TARGET_URL

사용자는 performance job에 인수를 전달하여 이 템플릿을 포함합니다. 이는 자신의 .gitlab-ci.yml에서 CI/CD 변수 TARGET_URL을 지정하여 수행할 수 있습니다:

include:
  template: Performance.gitlab-ci.yml

performance:
  variables:
    TARGET_URL: https://awesome-app.com

템플릿에서 job 이름 performance가 browser-performance로 변경되면, 포함된 템플릿에 performance라는 이름의 job이 더 이상 없기 때문에 사용자의 .gitlab-ci.yml이 즉시 린트 오류를 일으킵니다. 따라서 사용자는 자신의 워크플로를 방해할 수 있는 .gitlab-ci.yml을 수정해야 합니다.

안전하게 호환성을 깨는 변경 사항을 도입하는 방법은 버전 관리 섹션을 읽어보세요.

버전 관리#

현재 템플릿에 의존하는 기존 프로젝트에 영향을 주지 않고 호환성을 깨는 변경 사항을 도입하려면, 안정(stable) 및 최신(latest) 버전 관리를 사용합니다.

안정 템플릿은 보통 주요(major) 버전 릴리즈에서만 호환성을 깨는 변경 사항을 받는 반면, 최신 템플릿은 모든 릴리즈에서 호환성을 깨는 변경 사항을 받을 수 있습니다. 주요 릴리즈 마일스톤에서는 최신 템플릿이 새로운 안정 템플릿이 됩니다(최신 템플릿은 삭제될 수 있습니다).

최신 템플릿을 추가하는 것은 안전하지만 유지보수 부담이 따릅니다:

• GitLab은 다음 주요 GitLab 릴리즈 시 안정 템플릿을 최신 템플릿의 내용으로 덮어쓸 DRI(Directly Responsible Individual)를 선택해야 합니다. DRI는 변경으로 인해 문제를 겪는 사용자를 지원할 책임이 있습니다.

• 새로운 비호환성 변경 사항을 적용할 때, 안정 및 최신 템플릿 모두 가능한 한 일치하도록 업데이트해야 합니다.

• 많은 사용자가 최신 템플릿이 계속 존재하는 것에 직접 의존할 수 있기 때문에, 최신 템플릿이 계획보다 오래 유지될 수 있습니다.

새 최신 템플릿을 추가하기 전에, 호환성을 깨는 변경 사항이더라도 안정 템플릿에 해당 변경 사항을 적용할 수 있는지 확인합니다. 템플릿이 복사-붙여넣기 사용 전용인 경우, 안정 버전을 직접 변경할 수 있을 수도 있습니다. 마이너 마일스톤에서 호환성을 깨는 변경 사항으로 안정 템플릿을 변경하기 전에 다음을 확인합니다:

• 파이프라인 템플릿이고 includes와 함께 사용하도록 설계되지 않았음을 설명하는 코드 주석이 있는 경우.

• CI/CD 템플릿 사용 메트릭이 사용량을 보여주지 않는 경우. 메트릭이 템플릿의 사용량이 0임을 보여주면, 해당 템플릿은 include와 함께 활발하게 사용되지 않는 것입니다.

안정 버전#

안정 CI/CD 템플릿은 주요 릴리즈 마일스톤에서만 호환성을 깨는 변경 사항을 도입하는 템플릿입니다. 템플릿의 안정 버전 이름을 <template-name>.gitlab-ci.yml로 지정합니다. 예를 들어 Jobs/Deploy.gitlab-ci.yml.

15.0과 같은 GitLab 주요 마일스톤 릴리즈에서 사용 가능한 최신 템플릿을 복사하여 새 안정 템플릿을 만들 수 있습니다. 모든 호환성을 깨는 변경 사항은 버전별 지원 중단 및 제거 페이지에 공지되어야 합니다.

다음과 같은 경우 15.1과 같은 마이너 GitLab 릴리즈에서 안정 템플릿 버전을 변경할 수 있습니다:

• 변경이 호환성을 깨는 변경이 아닌 경우.

• 최신 템플릿이 존재하는 경우 해당 변경이 최신 템플릿에도 반영된 경우.

최신 버전#

latest로 표시된 템플릿은 호환성을 깨는 변경 사항이 있어도 모든 릴리즈에서 업데이트될 수 있습니다. 최신 버전인 경우 템플릿 이름에 .latest를 추가합니다. 예를 들어 Jobs/Deploy.latest.gitlab-ci.yml.

호환성을 깨는 변경 사항을 도입할 때는 업그레이드 경로를 반드시 테스트하고 문서화해야 합니다. 일반적으로, 최신 템플릿이 예기치 않은 문제로 사용자를 놀라게 할 수 있으므로 최신 템플릿을 최선의 옵션으로 홍보해서는 안 됩니다.

latest 템플릿이 아직 존재하지 않는 경우 안정 템플릿을 복사할 수 있습니다.

이전 안정 템플릿 포함 방법#

사용자는 현재 GitLab 패키지에 번들로 제공되지 않는 이전 안정 템플릿을 사용하고 싶을 수 있습니다. 예를 들어, GitLab 15.0과 GitLab 16.0의 안정 템플릿이 너무 달라서 GitLab 16.0으로 업그레이드한 후에도 GitLab 15.0 템플릿을 계속 사용하고 싶을 수 있습니다.

include:remote를 사용하여 이전 템플릿 버전을 포함하는 방법을 템플릿이나 문서에 메모로 추가할 수 있습니다. 다른 템플릿이 include: template으로 포함된 경우, include: remote와 결합할 수 있습니다:

# To use the v13 stable template, which is not included in v14, fetch the specific
# template from the remote template repository with the `include:remote:` keyword.
# If you fetch from the GitLab canonical project, use the following URL format:
# https://gitlab.com/gitlab-org/gitlab/-/raw/<version>/lib/gitlab/ci/templates/<template-name>
include:
  - template: Auto-DevOps.gitlab-ci.yml
  - remote: https://gitlab.com/gitlab-org/gitlab/-/raw/v13.0.1-ee/lib/gitlab/ci/templates/Jobs/Deploy.gitlab-ci.yml

추가 자료#

GitLab CI/CD 템플릿에 버전 관리 개념을 도입하는 것에 대한 공개 이슈가 있습니다. 해당 이슈에서 진행 상황을 확인할 수 있습니다.

테스트#

각 CI/CD 템플릿은 안전하게 게시될 수 있는지 테스트해야 합니다.

수동 QA#

최소한의 데모 프로젝트에서 템플릿을 테스트하는 것은 항상 좋은 관행입니다. 이를 위해 다음 단계를 따르세요:

• https://gitlab.com에 공개 샘플 프로젝트를 만듭니다.

• 제안된 템플릿으로 프로젝트에 .gitlab-ci.yml을 추가합니다.

• 파이프라인을 실행하고 모든 경우(머지 리퀘스트 파이프라인, 스케줄 등)에서 모든 것이 올바르게 실행되는지 확인합니다.

• 새 템플릿을 추가하는 머지 리퀘스트 설명에 해당 프로젝트 링크를 추가합니다.

이는 검토자가 템플릿이 안전하게 머지될 수 있는지 확인하는 데 유용한 정보입니다.

새 템플릿이 UI에서 선택 가능한지 확인#

일부 디렉터리에 위치한 템플릿은 새 파일 UI에서도 선택 가능합니다. 해당 디렉터리 중 하나에 템플릿을 추가할 때, 드롭다운 목록에 올바르게 나타나는지 확인하세요:

[

](/19.1/development/cicd/img/ci_template_selection_v13_1.png)

RSpec 테스트 작성#

파이프라인 job이 올바르게 생성되는지 확인하기 위해 RSpec 테스트를 작성해야 합니다:

• spec/lib/gitlab/ci/templates/<template-category>/<template-name>_spec.rb에 테스트 파일을 추가합니다.

• Ci::CreatePipelineService를 통해 파이프라인 job이 올바르게 생성되는지 테스트합니다.

호환성을 깨는 변경 사항 검증#

latest 템플릿에 호환성을 깨는 변경 사항을 도입할 때는 다음을 수행해야 합니다:

• 안정 템플릿에서의 업그레이드 경로를 테스트합니다.

• 사용자가 어떤 종류의 오류를 겪는지 확인합니다.

• 트러블슈팅 가이드로 문서화합니다.

이 정보는 안정 템플릿이 GitLab 주요 버전 릴리즈에서 업데이트될 때 사용자에게 중요합니다.

메트릭 추가#

모든 CI/CD 템플릿에는 사용량을 추적하기 위한 메트릭 정의가 있어야 합니다. CI/CD 템플릿 월간 사용 보고서는 Sisense (GitLab 팀원 전용)에서 확인할 수 있습니다. 템플릿을 선택하여 해당 단일 템플릿의 그래프를 볼 수 있습니다.

새 템플릿에 대한 메트릭 정의를 추가하려면:

• GitLab GDK를 설치하고 시작합니다.

• GDK의 gitlab 디렉터리에서 새 템플릿이 포함된 브랜치를 체크아웃합니다.

• 주간 및 월간 CI/CD 템플릿 총 카운트 메트릭에 새 템플릿 이벤트 이름을 추가합니다:

config/metrics/counts_7d/20210216184557_ci_templates_total_unique_counts_weekly.yml

• config/metrics/counts_28d/20210216184559_ci_templates_total_unique_counts_monthly.yml

• 새 메트릭 정의를 추가하기 위해 다음 명령의 마지막 인수로 위와 동일한 이벤트 이름을 사용합니다:

bundle exec rails generate gitlab:usage_metric_definition:redis_hll ci_templates <template_metric_event_name>

출력은 다음과 같아야 합니다:

$ bundle exec rails generate gitlab:usage_metric_definition:redis_hll ci_templates p_ci_templates_my_template_name
      create  config/metrics/counts_7d/20220120073740_p_ci_templates_my_template_name_weekly.yml
      create  config/metrics/counts_28d/20220120073746_p_ci_templates_my_template_name_monthly.yml

• 새로 생성된 두 파일을 다음과 같이 편집합니다:

name: 및 performance_indicator_type:: 삭제합니다(필요 없음).

• introduced_by_url:: 템플릿을 추가하는 MR의 URL.

• data_source:: redis_hll로 설정합니다.

• description: 이 메트릭이 측정하는 내용에 대한 간단한 설명을 추가합니다. 예: Count of pipelines using the latest Auto Deploy template

• product_*: 메트릭 사전 가이드에 따라 섹션, Stage, 그룹 및 기능 카테고리로 설정합니다. 이 키워드에 무엇을 사용할지 확실하지 않은 경우 머지 리퀘스트에서 도움을 요청할 수 있습니다.

• 각 파일의 끝에 다음을 추가합니다:

options:
  events:
    - p_ci_templates_my_template_name

• 변경 사항을 커밋하고 푸시합니다.

예를 들어, 다음은 5 Minute Production App 템플릿에 대한 메트릭 구성 파일입니다:

• 주간 및 월간 메트릭 정의:

config/metrics/counts_7d/20210901223501_p_ci_templates_5_minute_production_app_weekly.yml

• config/metrics/counts_28d/20210901223505_p_ci_templates_5_minute_production_app_monthly.yml

• 메트릭 카운트 합계:

config/metrics/counts_7d/20210216184557_ci_templates_total_unique_counts_weekly.yml#L19

• config/metrics/counts_28d/20210216184559_ci_templates_total_unique_counts_monthly.yml#L19

보안#

템플릿에 악의적인 코드가 포함될 수 있습니다. 예를 들어, job에서 export 셸 명령을 포함하는 템플릿이 job 로그에서 시크릿 프로젝트 CI/CD 변수를 실수로 노출시킬 수 있습니다. 보안 여부가 확실하지 않은 경우, 교차 검증을 위해 반드시 보안 전문가에게 요청해야 합니다.

CI/CD 템플릿 머지 리퀘스트 기여#

CI/CD 템플릿 MR이 생성되고 ci::templates 라벨이 지정되면, DangerBot이 코드를 검토할 수 있는 검토자 1명과 메인테이너 1명을 제안합니다. 머지 리퀘스트가 검토 준비가 되면, 언급 기능으로 검토자에게 알리고 CI/CD 템플릿 변경 사항을 검토해 달라고 요청합니다. 자세한 내용은 CI/CD 템플릿 MR에 대한 DangerBot 작업을 추가한 머지 리퀘스트를 참조하세요.