• 단일 구성 파일 포함
• 구성 파일 배열 포함
• 포함된 구성 파일의 default 구성 사용하기
• 포함된 구성 값 재정의
  • include의 병합 방법
• 포함된 구성 배열 재정의
• 중첩 포함 사용
  • 중복 include 항목으로 중첩 포함 사용
• include와 함께 변수 사용
• include와 함께 rules 사용
  • rules:if와 함께 include
  • rules:exists로 include 사용
  • rules:changes로 include 사용
• 와일드카드 파일 경로로 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 작업에는 script에 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 "Job complete."

중복 include 항목으로 중첩 포함 사용

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

포함된 구성을 변경하는 파일이 있으면 overrides를 사용하여, include 항목의 순서는 최종 구성에 영향을 줄 수 있습니다. 구성이 마지막으로 포함되면, 포함된 파일이 이전에 포함된 것보다 우선합니다. 예를 들어:

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

  default:
    before_script: echo "Default before script"
  

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

  include:
    - template: defaults.gitlab-ci.yml
  
  default:  # 포함된 기본값을 재정의
    before_script: echo "Unit test default override"
  
  unit-test-job:
    script: unit-test.sh
  

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

  include:
    - template: defaults.gitlab-ci.yml
  
  default:  # 포함된 기본값을 재정의
    before_script: echo "Smoke test default override"
  
  smoke-test-job:
    script: smoke-test.sh
  

이 세 파일로 include를 사용하는 경우, include 항목의 순서가 최종 설정을 변경합니다. unit-tests가 먼저 포함 된 경우,.gitlab-ci.yml 파일의 내용은 다음과 같습니다:

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

최종 구성은 다음과 같을 것입니다:

unit-test-job:
  before_script: echo "Unit test default override"
  script: unit-test.sh

smoke-test-job:
  before_script: echo "Unit test default override"
  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 "Unit test default override"
  script: unit-test.sh

smoke-test-job:
  before_script: echo "Smoke test default override"
  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 변수를 동적 하위 파이프라인의 구성에 사용할 수 없습니다. Issue 378717에서 이 문제를 수정하는 것을 제안하고 있습니다.

include와 함께 rules 사용

• GitLab 15.11에서 needs 작업 종속성을 지원합니다.

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

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

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

rules:if와 함께 include

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

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

rules:exists로 include 사용

• 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의 존재 여부를 확인합니다.

다른 프로젝트의 포함 파일에서 rules:exists를 사용하는 경우 구성을 신중하게 검토하십시오. GitLab은 파일의 존재 여부를 다른 프로젝트에서 확인합니다. 예를 들어:

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

test:
  script: exit 0

# other-project의 other-branch에서의 other-file.yml
include:
  - project: my-group/my-project
    ref: main
    file: my-file.yml
    rules:
      - exists:
          - file.md

이 예에서, GitLab은 my-group/other-project에서 other_branch 커밋에 대해 file.md의 존재 여부를 확인하고, 파이프라인이 실행되는 프로젝트/ref가 아닙니다.

검색 문맥을 변경하려면 rules:exists:paths를 사용할 수 있습니다. 예를 들어:

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

rules:changes로 include 사용

• 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이 포함됩니다.
• refs/heads/branch1을 기준으로 Dockerfile이 변경되었을 때 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 Pages 서버는 GitLab.com에서 속도 제한을 가지고 있습니다. GitLab Pages 사이트에 호스팅되는 CI/CD 구성 파일을 반복적으로 가져오는 시도는 속도 제한을 초과할 수 있으며 오류를 발생시킬 수 있습니다. GitLab Pages 사이트에서 CI/CD 구성 파일을 호스팅하는 것을 피해야 합니다.

가능한 경우, 외부 HTTP(S) 요청 없이 GitLab 인스턴스 내의 다른 프로젝트에서 구성 파일을 가져오기 위해 include:project를 사용하십시오.