• 단일 구성 파일 포함
• 구성 파일 배열 포함
• 포함된 구성 파일의 default 구성 사용
• 포함된 구성 값 재정의
  • include에 대한 병합 방법
• 포함된 구성 배열 재정의
• 중첩된 포함 사용
  • 중첩된 포함과 중복 포함 항목 사용
• include와 함께 변수 사용
• rules 및 include 사용
  • rules:if로 include 사용
  • rules:exists로 include 사용
  • rules:changes로 include 사용
• include:local를 와일드카드 파일 경로와 함께 사용하기
• 문제 해결
  • Maximum of 150 nested includes are allowed! 오류

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

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

단일 구성 파일 포함

단일 구성 파일을 포함하려면 다음 구문 중 하나를 사용하십시오:

• include를 단독으로 사용하여 단일 파일을 포함합니다. 이 파일이 로컬 파일이면 include:local과 같습니다. 원격 파일이면 include:remote와 같습니다.

  include: '/templates/.after-script-template.yml'
  

구성 파일 배열 포함

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

• 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 명령은 script 명령보다 먼저 rspec 작업에서 실행됩니다.

포함된 구성 값 재정의

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

포함된 구성 배열 재정의

포함된 템플릿의 구성을 확장하고 재정의하기 위해 병합을 사용할 수 있지만, 배열에 개별 항목을 추가하거나 수정할 수는 없습니다. 예를 들어, 확장된 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

install_dependencies 및 deploy가 .gitlab-ci.yml 파일에서 반복되지 않는 경우, 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 "Job complete."

중첩된 포함과 중복 포함 항목 사용

• GitLab 14.8에서 도입됨

중첩된 포함은 동일한 구성 파일을 포함할 수 있습니다. 중복 구성 파일은 여러 번 포함되지만 한 번만 포함된 것과 같은 효과가 있습니다.

예를 들어, 다음과 같이 중첩된 포함이 있는 경우, defaults.gitlab-ci.yml가 여러 번 포함됩니다:

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

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

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

  default:
    before_script: default-before-script.sh
    retry: 2
  

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

  include:
    - template: defaults.gitlab-ci.yml
  
  unit-test-job:
    script: unit-test.sh
    retry: 0
  

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

  include:
    - template: defaults.gitlab-ci.yml
  
  smoke-test-job:
    script: smoke-test.sh
  

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

unit-test-job:
  before_script: default-before-script.sh
  script: unit-test.sh
  retry: 0

smoke-test-job:
  before_script: default-before-script.sh
  script: smoke-test.sh
  retry: 2

include와 함께 변수 사용

• GitLab 13.8에서 도입됨
• GitLab 13.9에서 기능 플래그가 제거됨
• GitLab 14.2에서 프로젝트, 그룹 및 인스턴스 변수 지원이 추가됨
• GitLab 14.5에서 파이프라인 변수 지원이 추가됨

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

• 프로젝트 변수.
• 그룹 변수.
• 인스턴스 변수.
• 프로젝트 미리 정의된 변수(CI_PROJECT_*).

• GitLab 14.2 이상에서 $CI_COMMIT_REF_NAME 미리 정의된 변수.

  include에서 CI_COMMIT_REF_NAME 변수를 사용하면 refs/heads/branch-name과 같이 전체 ref 경로가 반환됩니다. include:rules에서 if: $CI_COMMIT_REF_NAME =~ /main/ (== main이 아님)을 사용해야 할 수도 있습니다. 이 동작은 GitLab 14.5에서 해결됩니다.

GitLab 14.5 이상에서 다음을 사용할 수도 있습니다:

• 트리거 변수.
• 예약된 파이프라인 변수.
• 수동으로 실행하는 파이프라인 변수.
• CI_PIPELINE_SOURCE 및 CI_PIPELINE_TRIGGERED 미리 정의된 변수.

예를 들어:

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

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

미리 정의된 변수를 포함하고 이러한 변수가 CI/CD 작업에 미치는 영향에 대한 예시는 이 CI/CD 변수 데모를 참조하세요.

rules 및 include 사용

• GitLab 14.2에서 ci_include_rules라는 플래그로 도입되었습니다. 기본 설정은 비활성화되어 있습니다.(링크)
• GitLab 14.3에서 GitLab.com 및 자체 관리 버전에서 활성화되었습니다.
• GitLab 14.4에서 일반적으로 사용 가능합니다. ci_include_rules 기능 플래그가 제거되었습니다.
• GitLab 14.5에서 exists 키워드의 지원이 도입되었습니다.
• GitLab 15.11에서 needs 작업 종속성의 지원이 도입되었습니다.

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

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

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

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

include를 rules:exists와 함께 구성하여 다른 프로젝트에서 구성 파일을 추가하도록 할 경우 알려진 문제점이 있습니다. GitLab은 파일의 존재 여부를 다른 프로젝트에서 확인합니다. 예를 들어:

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

test:
  stage: test
  script: exit 0

이 예에서 GitLab은 my-group/my-project-2의 test-file.yml의 존재 여부를 확인하고 현재 프로젝트가 아닙니다. 이 동작을 개선하기 위한 정보는 이슈 386040을 참고하세요.

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이 포함됩니다.
• Dockerfile이 refs/heads/branch1에 상대적으로 변경될 때 builds2.yml이 포함됩니다.
• Dockerfile이 변경되고 파이프라인 소스가 병합 요청 이벤트인 경우 builds3.yml이 포함됩니다.

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

• GitLab 13.11에서 도입됨.
• 기능 플래그 제거 - GitLab 14.2.

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 및 이후에서, 자체 관리 사용자는 최대 포함 수를 변경할 수 있습니다.