다른 파일의 CI/CD 설정 사용

요약

include를 사용하면 CI/CD job에 외부 YAML 파일을 포함할 수 있습니다. 단일 설정 파일을 포함하려면 다음 두 문법 중 하나를 사용해 include를 단독으로 사용합니다. 배열의 단일 항목으로 작성하는 방식:

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

단일 설정 파일 포함#

단일 설정 파일을 포함하려면 다음 두 문법 중 하나를 사용해 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 섹션을 사용하면 해당 기본값이 파이프라인의 모든 job에 적용됩니다.

예를 들어 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 job 모두에서 script 명령보다 먼저 실행됩니다.

포함된 설정 값 재정의#

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

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

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 job의 environment:url은 autodevops-template.yml 파일에 정의된 값을 재정의합니다. 다른 키워드는 변경되지 않습니다. 이 방식을 merging(병합) 이라고 합니다.

`include`의 병합 방식#

include 설정은 다음 과정을 거쳐 메인 설정 파일과 병합됩니다.

포함된 파일은 설정 파일에 정의된 순서대로 읽히며, 포함된 설정은 같은 순서로 함께 병합됩니다.
포함된 파일이 다시 include를 사용하는 경우, 해당 중첩된 include 설정이 먼저 (재귀적으로) 병합됩니다.
파라미터가 겹치는 경우, 포함된 파일에서 설정을 병합할 때 마지막에 포함된 파일이 우선합니다.
include로 추가된 모든 설정이 함께 병합된 뒤, 메인 설정이 포함된 설정과 병합됩니다.

이 병합 방식은 deep merge(깊은 병합) 로, 설정의 어느 깊이에서든 해시 맵이 병합됩니다. 해시 맵 "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

이 예시에서는:

변수는 모든 파일이 병합된 후에만 평가됩니다. 포함된 파일의 job 이 다른 파일에서 정의된 변수 값을 사용하게 될 수도 있습니다. 병합 후, CI/CD 변수 우선순위가 각 변수의 최종 값을 결정합니다.
rules는 배열이므로 병합할 수 없습니다. 최상위 파일이 우선합니다.
artifacts는 해시 맵이므로 깊은 병합이 가능합니다.

포함된 설정 배열 재정의#

병합을 사용하면 포함된 템플릿의 설정을 확장하고 재정의할 수 있지만, 배열의 개별 항목을 추가하거나 수정할 수는 없습니다. 예를 들어 확장된 production job의 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 job의 script에는 notify_owner만 남게 됩니다.

중첩 include 사용#

다른 설정에 포함되는 설정 파일 안에서 include 섹션을 중첩할 수 있습니다. 예를 들어 include 키워드가 3단계로 중첩된 경우는 다음과 같습니다.

.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 항목이 있는 중첩 include 사용#

메인 설정 파일과 중첩된 include 모두에서 동일한 설정 파일을 여러 번 포함할 수 있습니다.

어떤 파일이든 재정의를 사용해 포함된 설정을 변경하면, include 항목의 순서가 최종 설정에 영향을 줄 수 있습니다. 해당 설정이 마지막으로 포함된 시점이 이전에 그 파일이 포함됐던 시점을 모두 재정의합니다. 예를 들면:

defaults.gitlab-ci.yml 파일의 콘텐츠:

default:
  before_script: echo "Default before script"

unit-tests.gitlab-ci.yml 파일의 콘텐츠:

include:
  - template: defaults.gitlab-ci.yml

default:  # 포함된 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:  # 포함된 default 를 재정의
  before_script: echo "Smoke test default override"

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 "Smoke test default override"
 script: unit-test.sh

smoke-test-job:
 before_script: echo "Smoke 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 "Unit 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'

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

사전 정의 변수를 포함하는 방법과 해당 변수가 CI/CD job에 미치는 영향에 대한 예시는 이 CI/CD 변수 데모를 참조합니다.

동적 자식 파이프라인 설정의 include 섹션에서는 CI/CD 변수를 사용할 수 없습니다. 이슈 378717에서 이 문제를 해결하는 방안을 제안하고 있습니다.

`include`와 함께 `rules` 사용#

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

rules는 특정 변수와 다음 키워드에 한해서만 사용할 수 있습니다.

`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` 사용#

히스토리

regexp: 지원이 GitLab 19.2에서 도입되었습니다.

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 파일에서 include를 rules:exists와 함께 사용하는 경우, 설정을 주의 깊게 검토합니다. GitLab은 해당 다른 프로젝트에서 파일의 존재 여부를 확인합니다. 예시:

# my-group/my-project 의 파이프라인 설정
include:
  - project: my-group/other-project
    ref: other_branch
    file: other-file.yml

test:
  script: exit 0

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

이 예시에서 GitLab은 파이프라인이 실행되는 프로젝트/ref가 아니라, my-group/other-project의 커밋 ref other_branch에서 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

`rules:changes`와 함께 `include` 사용#

히스토리

regexp: 지원이 GitLab 19.2에서 도입되었습니다.

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 이 포함됩니다. builds3.yml의 job 들은 머지 리퀘스트 파이프라인에서도 실행되도록 설정되어 있어야 합니다.

와일드카드 파일 경로로 `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 설정을 포함하고 있습니다.
중첩 include에 의도치 않은 루프가 있습니다. 예를 들어 include1.yml 이 include2.yml을 포함하고, include2.yml 이 다시 include1.yml을 포함해 재귀 루프가 만들어지는 경우입니다.

이런 상황이 발생할 위험을 줄이려면, 한도 도달 여부를 검증하는 파이프라인 편집기로 파이프라인 설정 파일을 편집합니다. 포함된 파일을 하나씩 제거해 가면서 어떤 설정 파일이 루프나 과도한 포함 파일의 원인인지 좁혀 나갈 수 있습니다.

GitLab Self-Managed 사용자는 최대 include 수 값을 변경할 수 있습니다.

오류: `include:local`에서 `Local file <file> does not exist!`#

리포지터리에 파일이 존재함에도 불구하고 include:local을 사용할 때 Local file <file> does not exist! 오류가 발생할 수 있습니다.

이 오류는 CI/CD 설정 문제가 아니라 알려진 시스템 수준의 이슈입니다. 분산된 Gitaly 또는 Praefect 구성에서 간헐적으로 발생하는 것이 관찰되었습니다. 이 오류가 발생하면 파이프라인을 다시 시도합니다.

자세한 내용은 이슈 336789를 참조합니다.

`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 연결을 수립할 수 없을 때 발생합니다. 이 문제는 원격 호스트가 서버 과부하를 방지하기 위해 요청 속도를 제한(rate limit)하는 경우에도 발생할 수 있습니다.

예를 들어 GitLab.com 용 GitLab Pages 서버는 요청 속도가 제한되어 있습니다. GitLab Pages에 호스팅된 CI/CD 설정 파일을 반복적으로 가져오려고 시도하면 속도 제한에 도달해 오류가 발생할 수 있습니다. CI/CD 설정 파일을 GitLab Pages 사이트에 호스팅하는 것은 피해야 합니다.

가능하다면 외부 HTTP(S) 요청 없이 GitLab 인스턴스 내 다른 프로젝트에서 설정 파일을 가져오도록 include:project를 사용합니다.

다른 파일의 CI/CD 설정 사용

GitLab v19.5

Tier: Free, Premium, Ultimate
Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

원문 보기

번역일: 2026-09-18

요약

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

단일 설정 파일 포함#

단일 설정 파일을 포함하려면 다음 두 문법 중 하나를 사용해 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 섹션을 사용하면 해당 기본값이 파이프라인의 모든 job에 적용됩니다.

예를 들어 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 job 모두에서 script 명령보다 먼저 실행됩니다.

포함된 설정 값 재정의#

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

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

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

`include`의 병합 방식#

include 설정은 다음 과정을 거쳐 메인 설정 파일과 병합됩니다.

포함된 파일은 설정 파일에 정의된 순서대로 읽히며, 포함된 설정은 같은 순서로 함께 병합됩니다.
포함된 파일이 다시 include를 사용하는 경우, 해당 중첩된 include 설정이 먼저 (재귀적으로) 병합됩니다.
파라미터가 겹치는 경우, 포함된 파일에서 설정을 병합할 때 마지막에 포함된 파일이 우선합니다.
include로 추가된 모든 설정이 함께 병합된 뒤, 메인 설정이 포함된 설정과 병합됩니다.

키가 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

이 예시에서는:

변수는 모든 파일이 병합된 후에만 평가됩니다. 포함된 파일의 job 이 다른 파일에서 정의된 변수 값을 사용하게 될 수도 있습니다. 병합 후, CI/CD 변수 우선순위가 각 변수의 최종 값을 결정합니다.
rules는 배열이므로 병합할 수 없습니다. 최상위 파일이 우선합니다.
artifacts는 해시 맵이므로 깊은 병합이 가능합니다.

포함된 설정 배열 재정의#

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 job의 script에는 notify_owner만 남게 됩니다.

중첩 include 사용#

다른 설정에 포함되는 설정 파일 안에서 include 섹션을 중첩할 수 있습니다. 예를 들어 include 키워드가 3단계로 중첩된 경우는 다음과 같습니다.

.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 항목이 있는 중첩 include 사용#

메인 설정 파일과 중첩된 include 모두에서 동일한 설정 파일을 여러 번 포함할 수 있습니다.

defaults.gitlab-ci.yml 파일의 콘텐츠:

default:
  before_script: echo "Default before script"

unit-tests.gitlab-ci.yml 파일의 콘텐츠:

include:
  - template: defaults.gitlab-ci.yml

default:  # 포함된 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:  # 포함된 default 를 재정의
  before_script: echo "Smoke test default override"

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 "Smoke test default override"
 script: unit-test.sh

smoke-test-job:
 before_script: echo "Smoke 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 "Unit 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'

사전 정의 변수를 포함하는 방법과 해당 변수가 CI/CD job에 미치는 영향에 대한 예시는 이 CI/CD 변수 데모를 참조합니다.

동적 자식 파이프라인 설정의 include 섹션에서는 CI/CD 변수를 사용할 수 없습니다. 이슈 378717에서 이 문제를 해결하는 방안을 제안하고 있습니다.

`include`와 함께 `rules` 사용#

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

rules는 특정 변수와 다음 키워드에 한해서만 사용할 수 있습니다.

`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` 사용#

히스토리

regexp: 지원이 GitLab 19.2에서 도입되었습니다.

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가 존재하는지 확인합니다.

# my-group/my-project 의 파이프라인 설정
include:
  - project: my-group/other-project
    ref: other_branch
    file: other-file.yml

test:
  script: exit 0

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

이 예시에서 GitLab은 파이프라인이 실행되는 프로젝트/ref가 아니라, my-group/other-project의 커밋 ref other_branch에서 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

`rules:changes`와 함께 `include` 사용#

히스토리

regexp: 지원이 GitLab 19.2에서 도입되었습니다.

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 이 포함됩니다. builds3.yml의 job 들은 머지 리퀘스트 파이프라인에서도 실행되도록 설정되어 있어야 합니다.

와일드카드 파일 경로로 `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!` 오류#

중첩 설정 중 일부가 지나치게 많은 추가 중첩 include 설정을 포함하고 있습니다.
중첩 include에 의도치 않은 루프가 있습니다. 예를 들어 include1.yml 이 include2.yml을 포함하고, include2.yml 이 다시 include1.yml을 포함해 재귀 루프가 만들어지는 경우입니다.

GitLab Self-Managed 사용자는 최대 include 수 값을 변경할 수 있습니다.

오류: `include:local`에서 `Local file <file> does not exist!`#

리포지터리에 파일이 존재함에도 불구하고 include:local을 사용할 때 Local file <file> does not exist! 오류가 발생할 수 있습니다.

자세한 내용은 이슈 336789를 참조합니다.

`SSL_connect SYSCALL returned=5 errno=0 state=SSLv3/TLS write client hello` 및 기타 네트워크 오류#

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

가능하다면 외부 HTTP(S) 요청 없이 GitLab 인스턴스 내 다른 프로젝트에서 설정 파일을 가져오도록 include:project를 사용합니다.

다른 파일의 CI/CD 설정 사용

단일 설정 파일 포함#

설정 파일 배열 포함#

포함된 설정 파일의 default 설정 사용#

포함된 설정 값 재정의#

include의 병합 방식#

포함된 설정 배열 재정의#

중첩 include 사용#

중복된 include 항목이 있는 중첩 include 사용#

include와 함께 변수 사용#

include와 함께 rules 사용#

rules:if와 함께 include 사용#

rules:exists와 함께 include 사용#

rules:changes와 함께 include 사용#

와일드카드 파일 경로로 include:local 사용#

문제 해결#

Maximum of 150 nested includes are allowed! 오류#

오류: include:local에서 Local file <file> does not exist!#

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

다른 파일의 CI/CD 설정 사용

단일 설정 파일 포함#

설정 파일 배열 포함#

포함된 설정 파일의 default 설정 사용#

포함된 설정 값 재정의#

include의 병합 방식#

포함된 설정 배열 재정의#

중첩 include 사용#

중복된 include 항목이 있는 중첩 include 사용#

include와 함께 변수 사용#

include와 함께 rules 사용#

rules:if와 함께 include 사용#

rules:exists와 함께 include 사용#

rules:changes와 함께 include 사용#

와일드카드 파일 경로로 include:local 사용#

문제 해결#

Maximum of 150 nested includes are allowed! 오류#

오류: include:local에서 Local file <file> does not exist!#

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

포함된 설정 파일의 `default` 설정 사용#

`include`의 병합 방식#

`include`와 함께 변수 사용#

`include`와 함께 `rules` 사용#

`rules:if`와 함께 `include` 사용#

`rules:exists`와 함께 `include` 사용#

`rules:changes`와 함께 `include` 사용#

와일드카드 파일 경로로 `include:local` 사용#

`Maximum of 150 nested includes are allowed!` 오류#

오류: `include:local`에서 `Local file <file> does not exist!`#

`SSL_connect SYSCALL returned=5 errno=0 state=SSLv3/TLS write client hello` 및 기타 네트워크 오류#

포함된 설정 파일의 `default` 설정 사용#

`include`의 병합 방식#

`include`와 함께 변수 사용#

`include`와 함께 `rules` 사용#

`rules:if`와 함께 `include` 사용#

`rules:exists`와 함께 `include` 사용#

`rules:changes`와 함께 `include` 사용#

와일드카드 파일 경로로 `include:local` 사용#

`Maximum of 150 nested includes are allowed!` 오류#

오류: `include:local`에서 `Local file <file> does not exist!`#

`SSL_connect SYSCALL returned=5 errno=0 state=SSLv3/TLS write client hello` 및 기타 네트워크 오류#