• 워크플로우 규칙
  • $FORCE_GITLAB_CI 피하기
    • $FORCE_GITLAB_CI의 대안
• 기본 이미지
• 기본 변수
• 단계
• 의존성 프록시
  • 프로젝트 접근 토큰 사용자가 파이프라인을 시작할 때의 우회 방법
• 일반적인 작업 정의
• rules, if: 조건 및 changes: 패턴
  • if: 조건
  • changes: 패턴
• 모범 사례
  • extends:, <<: *xyz (YAML 앵커) 또는 !reference를 사용할 때
    • 주요 요점
    • extends와 YAML 앵커가 할 수 있는 일은 무엇인가요?
      • extends
      • YAML 앵커
    • 훌륭한 예시
  • .fast-no-clone-job 작업 확장
    • 시나리오 1: 작업에 before_script가 정의되지 않은 경우
    • 시나리오 2: 작업에 before_script 블록이 이미 정의된 경우 (또는 확장하는 작업에)
    • 주의사항
    • 이 패턴은 어디에 사용되나요?
  • 러너 태그
  • 기준 프로젝트에서 gitlab 루비 보석 사용
    • 1 - 보석의 조건부 요구
    • 2 - 사양에서 gitlab 보석 완전히 모의하기
    • 3 - bundle exec로 스크립트를 호출하지 마세요
• CI 구성 테스트
  • 테스트는 어떻게 작동하나요

CI 구성 내부

워크플로우 규칙

GitLab 프로젝트의 파이프라인은 workflow:rules 키워드 기능을 사용하여 생성됩니다.

파이프라인은 다음 시나리오에 대해 항상 생성됩니다:

• main 브랜치, 일정, 푸시, 병합 등 포함.
• 병합 요청.
• 태그.
• 안정적인, auto-deploy, 및 보안 브랜치.

파이프라인 생성은 다음 CI/CD 변수의 영향을 받습니다:

• $FORCE_GITLAB_CI가 설정되어 있으면, 파이프라인이 생성됩니다. 사용하지 않는 것이 좋습니다. Avoid $FORCE_GITLAB_CI를 참조하세요.
• $GITLAB_INTERNAL이 설정되어 있지 않으면, 파이프라인이 생성되지 않습니다.

기타 어떤 경우(예: 이에 대한 MR이 없는 브랜치를 푸시할 때)에는 파이프라인이 생성되지 않습니다.

이 워크플로우 규칙의 진실의 원천은 .gitlab-ci.yml에서 정의됩니다.

$FORCE_GITLAB_CI 피하기

파이프라인은 매우 복잡하며 우리가 트리거하고자 하는 파이프라인의 종류를 명확하게 이해해야 합니다.

어떤 작업을 실행해야 하고 어떤 작업을 실행하지 말아야 하는지 알아야 합니다.

파이프라인을 강제로 트리거하기 위해 $FORCE_GITLAB_CI를 사용하면, 우리는 실제로 그 파이프라인이 어떤 것인지 알지 못합니다. 결과적으로 우리가 원하는 작업을 실행하지 않거나 우리가 신경 쓰지 않는 작업을 너무 많이 실행할 수 있습니다.

더 많은 맥락과 배경 정보는 다음에서 확인할 수 있습니다: Avoid blanket changes to avoid unexpected run

현재 우리가 이 방식을 사용하고 있는 목록이며, $FORCE_GITLAB_CI 사용에서 벗어나기 위해 노력해야 합니다.

• JiHu 검증 파이프라인

다음 섹션에서는 $FORCE_GITLAB_CI를 사용하지 않고 파이프라인을 활성화할 수 있는 방법을 설명합니다.

$FORCE_GITLAB_CI의 대안

본질적으로, 우리는 서로 다른 파이프라인을 활성화하기 위해 서로 다른 변수를 사용합니다.

예를 들어 $START_AS_IF_FOSS가 있습니다. 교차 프로젝트 FOSS 파이프라인을 트리거하고자 할 때, 우리는 $START_AS_IF_FOSS를 설정하고, $ENABLE_RSPEC_UNIT, $ENABLE_RSPEC_SYSTEM 등과 같은 다른 변수 세트를 함께 설정하여 as-if-foss 교차 프로젝트 하위 파이프라인에서 실행하고자 하는 각 작업을 활성화합니다.

이 방식의 장점은 $FORCE_GITLAB_CI에 비해 우리가 파이프라인을 실행하는 방식을 완전히 제어할 수 있다는 점입니다. $START_AS_IF_FOSS는 오직 이 목적을 위해서만 사용되며, 이 변수를 통한 파이프라인의 동작 방식 변경이 다른 유형의 파이프라인에 영향을 미치지 않기 때문입니다. 반면에 $FORCE_GITLAB_CI를 사용할 경우 파이프라인이 정확히 어떤 것인지 알 수 없습니다. 이는 여러 용도로 사용되기 때문입니다.

기본 이미지

기본 이미지는 .gitlab-ci.yml에서 정의됩니다.

Ruby, Go, Git, Git LFS, Chrome, Node, Yarn, PostgreSQL, 및 Graphics Magick이 포함되어 있습니다.

우리의 파이프라인에서 사용되는 이미지는 gitlab-org/gitlab-build-images 프로젝트에서 구성되며, 이는 gitlab/gitlab-build-images로 푸시 미러링 되어 가용성을 보장합니다.

현재 빌드 이미지의 버전은 “Used by GitLab section”에서 확인할 수 있습니다.

기본 변수

미리 정의된 CI/CD 변수 외에도,

각 파이프라인에는 .gitlab-ci.yml에서 정의된 기본 변수가 포함됩니다.

단계

현재 단계는 다음과 같습니다:

• sync: 이 단계는 gitlab-org/gitlab에서 gitlab-org/gitlab-foss로 변경 사항을 동기화하는 데 사용됩니다.

• prepare: 이 단계에는 후속 단계에서 작업에 필요한 아티팩트를 준비하는 작업이 포함됩니다.

• build-images: 이 단계에는 후속 단계의 작업이나 하위 파이프라인에 필요한 Docker 이미지를 준비하는 작업이 포함됩니다.

• fixtures: 이 단계에는 프론트엔드 테스트에 필요한 픽스처를 준비하는 작업이 포함됩니다.

• lint: 이 단계에는 린트 및 정적 분석 작업이 포함됩니다.

• test: 이 단계에는 대부분의 테스트와 DB/마이그레이션 작업이 포함됩니다.

• post-test: 이 단계에는 test 단계의 작업에서 보고서를 생성하거나 데이터를 수집하는 작업이 포함됩니다 (예: 커버리지, Knapsack 메타데이터 등).

• review: 이 단계에는 CNG 이미지를 빌드하고 배포하며, 리뷰 앱에 대한 종단 간 테스트를 실행하는 작업이 포함됩니다 (자세한 내용은 리뷰 앱을 참조하십시오).

  또한 문서 리뷰 앱 작업이 포함됩니다.

• qa: 이 단계에는 review 단계에 배포된 리뷰 앱에 대한 QA 작업을 수행하는 작업이 포함됩니다.

• post-qa: 이 단계에는 qa 단계의 작업에서 보고서를 생성하거나 데이터를 수집하는 작업이 포함됩니다 (예: 리뷰 앱 성능 보고서).

• pages: 이 단계에는 다양한 보고서를 GitLab Pages로 배포하는 작업이 포함됩니다 (예: coverage-ruby,

  webpack-report는 https://gitlab-org.gitlab.io/gitlab/webpack-report/에 위치하지만 배포에 문제가 있습니다).

• notify: 이 단계에는 다양한 실패를 Slack에 알리는 작업이 포함됩니다.

의존성 프록시

일부 작업은 Docker Hub에서 이미지를 사용하고 있으며, 여기에서 우리는 ${GITLAB_DEPENDENCY_PROXY_ADDRESS}를 이미지 경로의 접두사로 사용하여

우리의 Dependency Proxy에서 이미지를 가져옵니다. 기본적으로 이 변수는 ${GITLAB_DEPENDENCY_PROXY}의 값에서 설정됩니다.

${GITLAB_DEPENDENCY_PROXY}는 gitlab-org에서 정의된 그룹 CI/CD 변수로

${CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX}/입니다. 이는 우리가 다음과 같이 정의된 이미지를 사용할 때를 의미합니다:

image: ${GITLAB_DEPENDENCY_PROXY_ADDRESS}alpine:edge

gitlab-org 그룹의 프로젝트는 Dependency Proxy에서 이미지를 가져오는 반면, 다른 개인 네임스페이스나 그룹에 있는 포크는

${GITLAB_DEPENDENCY_PROXY}가 그곳에서도 정의되어 있지 않는 한 Docker Hub로 돌아갑니다.

프로젝트 접근 토큰 사용자가 파이프라인을 시작할 때의 우회 방법

파이프라인이 프로젝트 접근 토큰 사용자(예: 메인 프로젝트에서 사용하는 Gitaly 버전을 자동으로 업데이트하는 release-tools approver bot 사용자)에 의해 시작될 때,

Dependency proxy에 접근할 수 없습니다

그리고 작업이 Preparing the "docker+machine" executor 단계에서 실패합니다.
이를 해결하기 위해 우리는 Dependency proxy가 사용되지 않도록 ${GITLAB_DEPENDENCY_PROXY_ADDRESS} 변수를 재정의하는 특별한 워크플로우 규칙을 가지고 있습니다:

- if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH && $GITLAB_USER_LOGIN =~ /project_\d+_bot\d*/'
  variables:
    GITLAB_DEPENDENCY_PROXY_ADDRESS: ""

참고:
우리는 그룹 수준 변수가 .gitlab-ci.yml 변수보다 우선순위가 높기 때문에 ${GITLAB_DEPENDENCY_PROXY} 변수를 직접 오버라이드하지 않습니다.

일반적인 작업 정의

대부분의 작업은 CI 정의에서 확장됩니다.

단일 구성 키워드에 범위가 지정된 .gitlab/ci/global.gitlab-ci.yml에서 정의된 것입니다.

rules, if: 조건 및 changes: 패턴

우리는 rules 키워드를 광범위하게 사용하고 있습니다.

모든 rules 정의는 rules.gitlab-ci.yml에서 정의되며, 각 작업에 대해 extends를 통해 포함됩니다.

rules 정의는 if: 조건과 changes: 패턴으로 구성되어 있으며, 이 또한 rules.gitlab-ci.yml에서 정의되고 YAML 앵커를 통해 rules 정의에 포함됩니다.

if: 조건

changes: 패턴

모범 사례

extends:, <<: *xyz (YAML 앵커) 또는 !reference를 사용할 때

참조

주요 요점

• 해시를 확장해야 하는 경우 extends를 사용해야 합니다.

• 배열을 확장해야 하는 경우, 마지막 수단으로 !reference 또는 YAML 앵커를 사용해야 합니다.

• 더 복잡한 경우(예: 배열 내 해시 확장, 해시 내 배열 확장 등)에는 !reference 또는 YAML 앵커를 사용해야 합니다.

extends와 YAML 앵커가 할 수 있는 일은 무엇인가요?

extends

• 해시에 대해 깊은 병합을 수행합니다.

• 배열에 대해서는 병합하지 않습니다. 덮어씌웁니다. (출처)

YAML 앵커

• 해시에 대해 깊은 병합을 수행하지 않지만, 해시를 확장하는 데 사용할 수 있습니다 (아래 예 참조).

• 배열에 대해서는 병합하지 않지만, 배열을 확장하는 데 사용할 수 있습니다 (아래 예 참조).

훌륭한 예시

이 예시는 !reference와 YAML 앵커를 사용하여 복합 YAML 데이터 구조를 확장하는 방법을 보여줍니다:

.strict-ee-only-rules:
  # `rules`는 해시의 배열입니다.
  rules:
    - if: '$CI_PROJECT_NAME !~ /^gitlab(-ee)?$/ '
      when: never

# `if-security-merge-request`는 해시입니다.
.if-security-merge-request: &if-security-merge-request
  if: '$CI_PROJECT_NAMESPACE == "gitlab-org/security"'

# `code-qa-patterns`는 배열입니다.
.code-qa-patterns: &code-qa-patterns
  - "{package.json,yarn.lock}"
  - ".browserslistrc"
  - "babel.config.js"
  - "jest.config.{base,integration,unit}.js"

.qa:rules:as-if-foss:
  rules:
    # `rules` 배열을 해시의 배열로 확장합니다.
    - !reference [".strict-ee-only-rules", rules]
    # 해시로 단일 배열 항목을 확장합니다.
    - <<: *if-security-merge-request
      # `changes`는 배열이므로 전체 배열을 전달합니다.
      changes: *code-qa-patterns

qa:selectors-as-if-foss:
  # 이 작업에서 .qa:rules:as-if-foss의 규칙을 포함합니다.
  extends:
    - .qa:rules:as-if-foss

.fast-no-clone-job 작업 확장

정식 프로젝트의 브랜치를 다운로드하는 데는 20초에서 30초가 걸립니다.

일부 작업은 필요한 파일 수가 제한적이며, 이를 GitLab API를 통해 다운로드할 수 있습니다.

작업에 다음 패턴을 추가하여 git clone/git fetch 작업을 건너뛸 수 있습니다.

시나리오 1: 작업에 before_script가 정의되지 않은 경우

이는 작업이 확장하는 상위 섹션에도 적용됩니다.

.fast-no-clone-job를 확장하면 됩니다:

이전:

  # 주의: 작업에 `extends:`가 없습니다
  a-job:
    script:
      - source scripts/rspec_helpers.sh scripts/slack
      - echo "git clone이 필요 없습니다!"

이후:

  # 주의: 작업에 `extends:`가 없습니다
  a-job:
    extends:
      - .fast-no-clone-job
    variables:
      FILES_TO_DOWNLOAD: >
        scripts/rspec_helpers.sh
        scripts/slack
    script:
      - source scripts/rspec_helpers.sh scripts/slack
      - echo "git clone이 필요 없습니다!"

시나리오 2: 작업에 before_script 블록이 이미 정의된 경우 (또는 확장하는 작업에)

이 시나리오에서는 다음과 같이 해야 합니다:

1. 첫 번째 시나리오와 같이 .fast-no-clone-job를 확장합니다(이렇게 하면 FILES_TO_DOWNLOAD 변수가 다른 변수와 병합됩니다).
2. .fast-no-clone-job의 before_script 섹션이 이 작업에서 사용하는 before_script에 참조되도록 합니다.

이전:

  .base-job:
    before_script:
      echo "안녕하세요, .base-job에서"

  a-job:
    extends:
      - .base-job
    script:
      - source scripts/rspec_helpers.sh scripts/slack
      - echo "git clone이 필요 없습니다!"

이후:

  .base-job:
    before_script:
      echo "안녕하세요, .base-job에서"

  a-job:
    extends:
      - .base-job
      - .fast-no-clone-job
    variables:
      FILES_TO_DOWNLOAD: >
        scripts/rspec_helpers.sh
        scripts/slack
    before_script:
      - !reference [".fast-no-clone-job", before_script]
      - !reference [".base-job", before_script]
    script:
      - source scripts/rspec_helpers.sh scripts/slack
      - echo "git clone이 필요 없습니다!"

주의사항

• 이 패턴은 스크립트가 저장소에 접근하기 위해 git을 필요로 하는 경우에는 작동하지 않습니다. 왜냐하면 우리는 클로닝이나 페치 없이 저장소에 접근할 수 없기 때문입니다.
• 이 패턴을 사용하는 작업에는 curl이 필요합니다.
• 작업에서 bundle install을 실행해야 하는 경우(심지어 BUNDLE_ONLY를 사용하더라도), 다음을 수행해야 합니다:
  • gitlab-org/gitlab 프로젝트에 저장된 젬을 다운로드해야 합니다.
    • 이를 위해 download_local_gems 셸 명령을 사용할 수 있습니다.
  • Gemfile, Gemfile.lock 및 (해당하는 경우) Gemfile.checksum을 포함해야 합니다.

이 패턴은 어디에 사용되나요?

• 현재 이 패턴은 다음 작업에 사용되며, 이것들은 개인 저장소를 차단하지 않습니다:
  • review-build-cng-env에 대해:
    • GITALY_SERVER_VERSION
    • GITLAB_ELASTICSEARCH_INDEXER_VERSION
    • GITLAB_KAS_VERSION
    • GITLAB_PAGES_VERSION
    • GITLAB_SHELL_VERSION
    • scripts/trigger-build.rb
    • VERSION
  • review-deploy에 대해:
    • GITALY_SERVER_VERSION
    • GITLAB_SHELL_VERSION
    • scripts/review_apps/review-apps.sh
    • scripts/review_apps/seed-dast-test-data.sh
    • VERSION
  • rspec:coverage에 대해:
    • config/bundler_setup.rb
    • Gemfile
    • Gemfile.checksum
    • Gemfile.lock
    • scripts/merge-simplecov
    • spec/simplecov_env_core.rb
    • spec/simplecov_env.rb
  • prepare-as-if-foss-env에 대해:
    • scripts/setup/generate-as-if-foss-env.rb

또한, 이 패턴이 사용될 때마다 scripts/utils.sh는 항상 API에서 다운로드됩니다(이 파일은 .fast-no-clone-job의 코드를 포함하고 있습니다).

러너 태그

GitLab.com에서는 비특권 및 특권 러너가 모두 사용할 수 있습니다.

gitlab-org 그룹에 있는 프로젝트와 해당 프로젝트의 포크에 대해, 작업에 다음 태그 중 하나만 추가해야 합니다:

• gitlab-org: 작업은 무작위로 특권 및 비특권 러너를 사용합니다.
• gitlab-org-docker: 작업은 특권 러너를 반드시 사용해야 합니다. Docker-in-Docker 지원이 필요한 경우, gitlab-org 대신 gitlab-org-docker를 사용하세요.

gitlab-org-docker 태그는 위의 .use-docker-in-docker 작업 정의에 의해 추가됩니다.

포크와의 호환성을 보장하기 위해, gitlab-org와 gitlab-org-docker를 동시에 사용하지 마세요. 인스턴스 러너는 gitlab-org와 gitlab-org-docker 태그를 모두 가지고 있지 않습니다. gitlab-org 프로젝트의 포크에서는 두 태그가 모두 제공되면 작업이 멈추게 됩니다. 왜냐하면 사용할 수 있는 일치하는 러너가 없기 때문입니다.

자세한 내용은 GitLab 리포지토리 핸드북 페이지를 참조하세요.

기준 프로젝트에서 gitlab 루비 보석 사용

기준 프로젝트에서 require 'gitlab'을 호출할 때, $LOAD_PATH에 lib가 있을 경우 lib/gitlab.rb 파일을 요구합니다. 이는 애플리케이션(config/application.rb) 또는 테스트(spec/spec_helper.rb)를 로드할 때 발생합니다.

이는 위 조건 하에서 gitlab 보석을 로드할 수 없으며, 로드할 수 있다 하더라도 상수 이름이 충돌하여 내부 가정을 깨뜨리고 무작위 오류를 발생시킬 수 있습니다.

gitlab 루비 보석을 사용하는 스크립트를 작업 중이라면 몇 가지 주의사항을 따르는 것이 필요합니다:

1 - 보석의 조건부 요구

잠재적인 충돌을 피하기 위해 Gitlab 상수가 정의되어 있지 않은 경우에만 gitlab 보석을 요구하세요:

# 나쁨
require 'gitlab'

# 좋음
if Object.const_defined?(:RSpec)
  # 괜찮습니다, 우리는 테스트 중이며 `Gitlab`을 스텁할 것이라는 걸 알고 있으므로 무시합니다.
else
  require 'gitlab'

  if Gitlab.singleton_class.method_defined?(:com?)
    abort 'lib/gitlab.rb가 로드되었습니다. 이는 클라이언트를 더 이상 로드할 수 없으며 진행할 수 없다는 의미입니다.'
  end
end

2 - 사양에서 gitlab 보석 완전히 모의하기

사양에서 require 'gitlab'은 lib/gitlab.rb 파일을 참조합니다:

# 나쁨
allow(GitLab).to receive(:a_method).and_return(...)

# 좋음
client = double('GitLab')
# 클라이언트를 쉽게 스텁하기 위해 클라이언트를 반환하는 메소드를 사용하는 것이 좋습니다.
# 그런 다음 메소드를 스텁하여 우리의 가짜 클라이언트를 반환할 수 있습니다. 
# 우리는 그 클라이언트의 메소드도 추가로 스텁할 수 있습니다.
#
# 아래에 따라 진행합니다.
let(:instance) { described_class.new }

allow(instance).to receive(:gitlab).and_return(client)
allow(client).to receive(:a_method).and_return(...)

인스턴스에 대한 작업을 쿼리해야 하는 경우, 다음 코드는 유용할 것입니다:

# 나쁨
allow(GitLab).to receive(:pipeline_jobs).and_return(...)

# 좋음
#
# rubocop:disable RSpec/VerifiedDoubles -- 우리는 Gitlab 클라이언트를 직접 로드하지 않습니다.
client = double('GitLab')
allow(instance).to receive(:gitlab).and_return(client)

jobs = ['job1', 'job2']
allow(client).to yield_jobs(:pipeline_jobs, jobs)

def yield_jobs(api_method, jobs)
  messages = receive_message_chain(api_method, :auto_paginate)

  jobs.inject(messages) do |stub, job_name|
    stub.and_yield(double(name: job_name))
  end
end
# rubocop:enable RSpec/VerifiedDoubles

3 - bundle exec로 스크립트를 호출하지 마세요

bundle exec로 실행하면 Ruby의 $LOAD_PATH가 변경되며, require 'gitlab'을 호출할 때 lib/gitlab.rb가 로드됩니다:

# 나쁨
bundle exec scripts/my-script.rb

# 좋음
scripts/my-script.rb

CI 구성 테스트

이제 우리는 업데이트된 YAML 파일로 파이프라인 생성을 시뮬레이션하여 CI 구성의 변경 사항을 검증하는 RSpec 테스트를 갖추고 있습니다. 이러한 테스트와 현재 테스트 커버리지에 대한 문서는 spec/dot_gitlab_ci/job_dependency_spec.rb에서 찾을 수 있습니다.

테스트는 어떻게 작동하나요

Ci::CreatePipelineService의 도움으로, 우리는 브랜치 이름, MR 레이블, 파이프라인 소스(일정 vs 푸시), 파이프라인 유형(병합 열차 vs 병합된 결과) 등과 같은 다양한 속성으로 파이프라인 생성을 시뮬레이션할 수 있습니다. 이는 CI/CD 구성을 검증하기 위해 GitLab CI Lint API에서 사용하는 동일한 서비스입니다.

이 테스트는 CI 구성 업데이트를 위한 병합 요청에 대해 자동으로 실행됩니다. 그러나 팀원들은 병합 요청에 ~"pipeline:skip-ci-validation" 레이블을 추가하여 이러한 테스트를 건너뛸 수 있습니다.

이 테스트를 로컬에서 실행하는 것이 권장되며, 이는 가장 빠른 피드백을 제공합니다.