• 단일 구성 파일 포함하기
• 구성 파일 배열 포함하기
• 포함된 구성 파일의 default 구성 사용하기
• 포함된 구성 값 재정의
  • include에 대한 병합 방법
• 포함된 구성 배열 재정의
• 중첩 포함 사용하기
  • 중첩 포함에 중복 include 항목 사용하기
• include와 변수 사용하기
• include와 rules 사용하기
  • rules:if와 함께 include 사용하기
  • include 및 rules:exists
  • include 및 rules:changes
• include:local을 와일드카드 파일 경로와 함께 사용하기
• 문제 해결
  • Maximum of 150 nested includes are allowed! 오류
  • SSL_connect SYSCALL returned=5 errno=0 state=SSLv3/TLS write client hello 및 기타 네트워크 실패

다른 파일에서 CI/CD 구성을 사용하기

CI/CD 작업에 외부 YAML 파일을 포함하려면 include를 사용할 수 있습니다.

단일 구성 파일 포함하기

단일 구성 파일을 포함하려면 include를 단독으로 사용하여 다음 중 하나의 구문 옵션으로 단일 파일을 지정하세요:

• 같은 줄에:

  include: 'my-config.yml'  
  

• 배열의 단일 항목으로:

  include:  
    - 'my-config.yml'  
  

파일이 로컬 파일인 경우 동작은 include:local과 동일합니다.
파일이 원격 파일인 경우 include:remote와 동일합니다.

구성 파일 배열 포함하기

구성 파일 배열을 포함할 수 있습니다:

• include 유형을 지정하지 않으면 각 배열 항목은 필요에 따라 include:local 또는 include:remote로 기본값이 설정됩니다:

  include:  
    - 'https://gitlab.com/awesome-project/raw/main/.before-script-template.yml'  
    - 'templates/.after-script-template.yml'  
  

• 단일 항목 배열을 정의할 수 있습니다:

  include:  
    - remote: 'https://gitlab.com/awesome-project/raw/main/.before-script-template.yml'  
  

• 배열을 정의하고 여러 include 유형을 명시적으로 지정할 수 있습니다:

  include:  
    - remote: 'https://gitlab.com/awesome-project/raw/main/.before-script-template.yml'  
    - local: 'templates/.after-script-template.yml'  
    - template: Auto-DevOps.gitlab-ci.yml  
  

• 기본 및 특정 include 유형을 결합한 배열을 정의할 수 있습니다:

  include:  
    - 'https://gitlab.com/awesome-project/raw/main/.before-script-template.yml'  
    - 'templates/.after-script-template.yml'  
    - template: Auto-DevOps.gitlab-ci.yml  
    - project: 'my-group/my-project'  
      ref: main  
      file: 'templates/.gitlab-ci-template.yml'  
  

포함된 구성 파일의 default 구성 사용하기

구성 파일에 default 섹션을 정의할 수 있습니다.
include 키워드가 있는 default 섹션을 사용하면 기본값이 파이프라인의 모든 작업에 적용됩니다.

예를 들어, before_script와 함께 default 섹션을 사용할 수 있습니다.

사용자 정의 구성 파일 /templates/.before-script-template.yml의 내용:

default:  
  before_script:  
    - apt-get update -qq && apt-get install -y -qq sqlite3 libsqlite3-dev nodejs  
    - gem install bundler --no-document  
    - bundle install --jobs $(nproc)  "${FLAGS[@]}"  

.gitlab-ci.yml의 내용:

include: 'templates/.before-script-template.yml'  
  
rspec1:  
  script:  
    - bundle exec rspec  
  
rspec2:  
  script:  
    - bundle exec rspec  

기본 before_script 명령은 rspec 작업 모두에서 script 명령 전에 실행됩니다.

포함된 구성 값 재정의

include 키워드를 사용할 때, 파이프라인 요구 사항에 맞게 포함된 구성 값을 재정의할 수 있습니다.

다음 예시는 .gitlab-ci.yml 파일에서 커스터마이즈된 include 파일을 보여줍니다. 특정 YAML 정의 변수와 production 작업의 세부 사항이 재정의됩니다.

커스텀 구성 파일 autodevops-template.yml의 내용:

variables:
  POSTGRES_USER: user
  POSTGRES_PASSWORD: testing_password
  POSTGRES_DB: $CI_ENVIRONMENT_SLUG

production:
  stage: production
  script:
    - install_dependencies
    - deploy
  environment:
    name: production
    url: https://$CI_PROJECT_PATH_SLUG.$KUBE_INGRESS_BASE_DOMAIN
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

.gitlab-ci.yml의 내용:

include: 'https://company.com/autodevops-template.yml'

default:
  image: alpine:latest

variables:
  POSTGRES_USER: root
  POSTGRES_PASSWORD: secure_password

stages:
  - build
  - test
  - production

production:
  environment:
    url: https://domain.com

.gitlab-ci.yml 파일의 POSTGRES_USER 및 POSTGRES_PASSWORD 변수와 production 작업의 environment:url은 autodevops-template.yml 파일에 정의된 값을 재정의합니다. 다른 키워드는 변경되지 않습니다. 이 방법을 병합이라고 합니다.

include에 대한 병합 방법

include 구성은 다음 프로세스를 통해 주요 구성 파일과 병합됩니다:

• 포함된 파일은 구성 파일에 정의된 순서에 따라 읽히며, 포함된 구성은 같은 순서로 함께 병합됩니다.
• 포함된 파일이 또 다른 include를 사용할 경우, 그 중첩된 include 구성이 먼저 병합됩니다(재귀적으로).
• 매개변수가 겹칠 경우, 마지막으로 포함된 파일이 병합할 때 우선합니다.
• 모든 include로 추가된 구성이 함께 병합된 후, 주요 구성은 포함된 구성과 병합됩니다.

이 병합 방법은 구성에서 어느 깊이에서도 해시 맵이 병합되는 _깊은 병합_입니다. 해시 맵 “A”(현재까지 병합된 구성을 포함)를 “B”(다음 구성 조각)와 병합할 때, 키와 값은 다음과 같이 처리됩니다:

• 키가 A에만 존재할 경우, A의 키와 값을 사용합니다.
• 키가 A와 B에 모두 존재하고, 두 값이 모두 해시 맵일 경우, 그 해시 맵들을 병합합니다.
• 키가 A와 B에 모두 존재하고, 값 중 하나가 해시 맵이 아닐 경우, B의 값을 사용합니다.
• 그렇지 않으면 B의 키와 값을 사용합니다.

예를 들어, 두 개의 파일로 구성된 설정이 있을 경우:

• .gitlab-ci.yml 파일:

  include: 'common.yml'
  
  variables:
    POSTGRES_USER: username
  
  test:
    rules:
      - if: $CI_PIPELINE_SOURCE == "merge_request_event"
        when: manual
    artifacts:
      reports:
        junit: rspec.xml
  

• common.yml 파일:

  variables:
    POSTGRES_USER: common_username
    POSTGRES_PASSWORD: testing_password
  
  test:
    rules:
      - when: never
    script:
      - echo LOGIN=${POSTGRES_USER} > deploy.env
      - rake spec
    artifacts:
      reports:
        dotenv: deploy.env
  

병합된 결과는 다음과 같습니다:

variables:
  POSTGRES_USER: username
  POSTGRES_PASSWORD: testing_password

test:
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
      when: manual
  script:
    - echo LOGIN=${POSTGRES_USER} > deploy.env
    - rake spec
  artifacts:
    reports:
      junit: rspec.xml
      dotenv: deploy.env

이 예제에서:

• 변수는 모든 파일이 병합된 후에만 평가됩니다. 포함된 파일의 작업은 다른 파일에 정의된 변수 값을 사용할 수 있습니다.
• rules는 배열이므로 병합할 수 없습니다. 최상위 파일이 우선합니다.
• artifacts는 해시 맵이므로 깊은 병합이 가능합니다.

포함된 구성 배열 재정의

병합을 사용하여 포함된 템플릿의 구성을 확장하고 재정의할 수 있지만, 배열 내의 개별 항목을 추가하거나 수정할 수는 없습니다. 예를 들어, 확장된 production 작업의 script 배열에 추가 notify_owner 명령을 추가하려면:

autodevops-template.yml의 내용:

production:
  stage: production
  script:
    - install_dependencies
    - deploy

.gitlab-ci.yml의 내용:

include: 'autodevops-template.yml'

stages:
  - production

production:
  script:
    - install_dependencies
    - deploy
    - notify_owner

.gitlab-ci.yml 파일에 install_dependencies와 deploy가 반복되지 않으면, production 작업의 스크립트에는 오직 notify_owner만 포함됩니다.

중첩 포함 사용하기

구성 파일에서 include 섹션을 중첩할 수 있으며, 그런 다음 다른 구성에서 포함될 수 있습니다. 예를 들어, 세 번 중첩된 include 키워드에 대해:

.gitlab-ci.yml의 내용:

include:
  - local: /.gitlab-ci/another-config.yml

/.gitlab-ci/another-config.yml의 내용:

include:
  - local: /.gitlab-ci/config-defaults.yml

/.gitlab-ci/config-defaults.yml의 내용:

default:
  after_script:
    - echo "작업 완료."

중첩 포함에 중복 include 항목 사용하기

주 구성 파일과 중첩 포함에서 동일한 구성 파일을 여러 번 포함할 수 있습니다.

포함된 구성을 오버라이드를 사용하여 변경하는 파일이 있는 경우, include 항목의 순서가 최종 구성에 영향을 미칠 수 있습니다. 구성 파일이 마지막으로 포함될 때 그것이 이전에 포함된 모든 내용을 재정의합니다. 예를 들어:

• defaults.gitlab-ci.yml 파일의 내용:

  default:
    before_script: echo "기본 이전 스크립트"
  

• unit-tests.gitlab-ci.yml 파일의 내용:

  include:
    - template: defaults.gitlab-ci.yml
  
  default:  # 포함된 기본값 재정의
    before_script: echo "단위 테스트 기본값 재정의"
  
  unit-test-job:
    script: unit-test.sh
  

• smoke-tests.gitlab-ci.yml 파일의 내용:

  include:
    - template: defaults.gitlab-ci.yml
  
  default:  # 포함된 기본값 재정의
    before_script: echo "스모크 테스트 기본값 재정의"
  
  smoke-test-job:
    script: smoke-test.sh
  

이 세 개의 파일로, 포함되는 순서가 최종 구성에 영향을 줍니다.

• unit-tests가 먼저 포함되면, .gitlab-ci.yml 파일의 내용은 다음과 같습니다:

  include:
    - local: unit-tests.gitlab-ci.yml
    - local: smoke-tests.gitlab-ci.yml
  

  최종 구성은 다음과 같습니다:

  unit-test-job:
   before_script: echo "스모크 테스트 기본값 재정의"
   script: unit-test.sh
  
  smoke-test-job:
   before_script: echo "스모크 테스트 기본값 재정의"
   script: smoke-test.sh
  

• unit-tests가 마지막에 포함되면, .gitlab-ci.yml 파일의 내용은 다음과 같습니다:

  include:
    - local: smoke-tests.gitlab-ci.yml
    - local: unit-tests.gitlab-ci.yml
  

• 최종 구성은 다음과 같습니다:

  unit-test-job:
   before_script: echo "단위 테스트 기본값 재정의"
   script: unit-test.sh
  
  smoke-test-job:
   before_script: echo "단위 테스트 기본값 재정의"
   script: smoke-test.sh
  

포함된 구성을 재정의하는 파일이 없으면, include 항목의 순서가 최종 구성에 영향을 미치지 않습니다.

include와 변수 사용하기

.gitlab-ci.yml 파일의 include 섹션에서 다음을 사용할 수 있습니다:

• 프로젝트 변수.
• 그룹 변수.
• 인스턴스 변수.
• 프로젝트 미리 정의된 변수 (CI_PROJECT_*).
• 트리거 변수.
• 스케줄된 파이프라인 변수.
• 수동 파이프라인 실행 변수.
• CI_PIPELINE_SOURCE 및 CI_PIPELINE_TRIGGERED 미리 정의된 변수.
• $CI_COMMIT_REF_NAME 미리 정의된 변수.

예를 들어:

include:
  project: '$CI_PROJECT_PATH'
  file: '.compliance-gitlab-ci.yml'

작업에서 정의된 변수나 모든 작업에 대한 기본 변수를 정의하는 전역 variables 섹션에서 정의된 변수를 사용할 수 없습니다. 포함은 작업보다 먼저 평가되므로 이러한 변수는 include와 함께 사용할 수 없습니다.

미리 정의된 변수를 포함하는 방법과 이러한 변수들이 CI/CD 작업에 미치는 영향을 확인하려면 이 CI/CD 변수 데모를 참조하세요.

동적 자식 파이프라인 구성의 include 섹션에서 CI/CD 변수를 사용할 수 없습니다. 문제 378717에서는 이 문제를 수정할 것을 제안합니다.

include와 rules 사용하기

• GitLab 15.11에서 도입된 needs 작업 종속성 지원.

include와 함께 rules를 사용하여 다른 구성 파일을 조건부로 포함할 수 있습니다.

rules는 특정 변수들 및 다음 키워드와 함께만 사용할 수 있습니다:

• rules:if.
• rules:exists.
• rules:changes.

rules:if와 함께 include 사용하기

• when: never 및 when:always에 대한 지원이 GitLab 16.1에서 도입되었습니다. 기본적으로 비활성화됨.
• GitLab 16.2에서 when: never 및 when:always가 일반적으로 제공됩니다. 기능 플래그 ci_support_include_rules_when_never가 제거되었습니다.

CI/CD 변수의 상태에 따라 다른 구성 파일을 조건부로 포함하기 위해 rules:if를 사용합니다. 예를 들어:

include:
  - local: builds.yml
    rules:
      - if: $DONT_INCLUDE_BUILDS == "true"
        when: never
  - local: builds.yml
    rules:
      - if: $ALWAYS_INCLUDE_BUILDS == "true"
        when: always
  - local: builds.yml
    rules:
      - if: $INCLUDE_BUILDS == "true"
  - local: deploys.yml
    rules:
      - if: $CI_COMMIT_BRANCH == "main"

test:
  stage: test
  script: exit 0

include 및 rules:exists

• when: never 및 when:always에 대한 지원이 도입됨 GitLab 16.1에서 ci_support_include_rules_when_never라는 플래그가 포함됨. 기본값으로 비활성화됨.
• when: never 및 when:always에 대한 지원이 일반적으로 사용 가능 GitLab 16.2에서. 기능 플래그 ci_support_include_rules_when_never가 제거됨.

rules:exists를 사용하여 파일의 존재 여부에 따라 다른 구성 파일을 조건부로 포함하세요. 예를 들어:

include:
  - local: builds.yml
    rules:
      - exists:
          - exception-file.md
        when: never
  - local: builds.yml
    rules:
      - exists:
          - important-file.md
        when: always
  - local: builds.yml
    rules:
      - exists:
          - file.md

test:
  stage: test
  script: exit 0

이 예제에서 GitLab은 현재 프로젝트에서 file.md의 존재를 확인합니다.

다른 프로젝트의 포함 파일에서 include와 rules:exists를 사용할 경우 구성 파일을 신중하게 검토하세요.

GitLab은 다른 프로젝트에서 파일의 존재 여부를 확인합니다. 예를 들어:

# 내 그룹/my-project의 파이프라인 구성
include:
  - project: my-group/other-project
    ref: other_branch
    file: other-file.yml

test:
  script: exit 0

# other_branch의 my-group/other-project에 있는 other-file.yml
include:
  - project: my-group/my-project
    ref: main
    file: my-file.yml
    rules:
      - exists:
          - file.md

이 예제에서 GitLab은 other_branch 커밋 참조의 my-group/other-project에서 file.md의 존재 여부를 검색합니다. 파이프라인이 실행되는 프로젝트/참조가 아닙니다.

검색 컨텍스트를 변경하려면 rules:exists:paths와 rules:exists:project를 사용할 수 있습니다. 예를 들어:

include:
  - project: my-group/my-project
    ref: main
    file: my-file.yml
    rules:
      - exists:
          paths:
            - file.md
          project: my-group/my-project
          ref: main

include 및 rules:changes

• GitLab 16.4에서 도입됨.

rules:changes를 사용하여 변경된 파일에 따라 다른 구성 파일을 조건부로 포함하세요. 예를 들어:

include:
  - local: builds1.yml
    rules:
      - changes:
        - Dockerfile
  - local: builds2.yml
    rules:
      - changes:
          paths:
            - Dockerfile
          compare_to: 'refs/heads/branch1'
        when: always
  - local: builds3.yml
    rules:
      - if: $CI_PIPELINE_SOURCE == "merge_request_event"
        changes:
          paths:
            - Dockerfile

test:
  stage: test
  script: exit 0

이 예제에서:

• Dockerfile이 변경될 때 builds1.yml이 포함됩니다.
• Dockerfile이 refs/heads/branch1에 대해 변경되면 builds2.yml이 포함됩니다.
• Dockerfile이 변경되고 파이프라인 소스가 머지 요청 이벤트인 경우 builds3.yml이 포함됩니다.

include:local을 와일드카드 파일 경로와 함께 사용하기

include:local과 함께 와일드카드 경로(* 및 **)를 사용할 수 있습니다.

예시:

include: 'configs/*.yml'

파이프라인이 실행될 때, GitLab:

• configs 디렉토리의 모든 .yml 파일을 파이프라인 구성에 추가합니다.

• configs 디렉토리의 하위 폴더에 있는 .yml 파일은 추가하지 않습니다. 이를 허용하려면, 다음 구성을 추가하세요:

  # 이것은 `configs`와 그 하위 폴더의 모든 `.yml` 파일에 일치합니다.
  include: 'configs/**.yml'
  
  # 이것은 `configs`의 하위 폴더에만 있는 모든 `.yml` 파일에 일치합니다.
  include: 'configs/**/*.yml'
  

문제 해결

Maximum of 150 nested includes are allowed! 오류

파이프라인의 최대 중첩 포함 파일 수는 150입니다. 파이프라인에서 Maximum 150 includes are allowed 오류 메시지를 받으면, 이는 다음 중 하나일 가능성이 높습니다:

• 중첩 구성 중 일부가 지나치게 많은 추가 중첩 include 구성을 포함하고 있습니다.
• 중첩 포함에서 우연한 루프가 발생했습니다. 예를 들어, include1.yml이 include2.yml을 포함하고, include2.yml이 include1.yml을 포함하여 재귀 루프를 생성합니다.

이런 일이 발생할 위험을 줄이기 위해 파이프라인 편집기로 파이프라인 구성 파일을 편집하세요. 이 편집기는 제한에 도달했는지 검증합니다. 루프 또는 과도한 포함 파일의 원본을 좁히기 위해 한 번에 하나의 포함된 파일을 제거할 수 있습니다.

GitLab 16.0 및 이후 버전에서는 자체 관리 사용자가 최대 포함 값을 변경할 수 있습니다.

SSL_connect SYSCALL returned=5 errno=0 state=SSLv3/TLS write client hello 및 기타 네트워크 실패

include:remote를 사용할 때, GitLab은 HTTP(S)를 통해 원격 파일을 가져오려고 시도합니다. 이 과정은 다양한 연결 문제로 인해 실패할 수 있습니다.

SSL_connect SYSCALL returned=5 errno=0 state=SSLv3/TLS write client hello 오류는 GitLab이 원격 호스트에 HTTPS 연결을 설정할 수 없을 때 발생합니다. 이 문제는 원격 호스트에 서버에 요청 과부하를 방지하기 위한 비율 제한이 있을 경우 발생할 수 있습니다.

예를 들어, GitLab.com의 GitLab Pages 서버는 비율 제한이 있습니다. GitLab Pages에 호스팅된 CI/CD 구성 파일을 가져오기 위한 반복 시도가 비율 제한에 도달하고 오류를 발생시킬 수 있습니다. CI/CD 구성 파일을 GitLab Pages 사이트에 호스팅하는 것은 피해야 합니다.

가능한 경우, include:project를 사용하여 외부 HTTP(S) 요청을 하지 않고 GitLab 인스턴스 내 다른 프로젝트에서 구성 파일을 가져오세요.