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

요약

include를 사용하여 CI/CD 잡에 외부 YAML 파일을 포함할 수 있습니다. 단일 구성 파일을 포함하려면 다음 구문 옵션 중 하나를 사용하여 단일 파일과 함께 include를 사용합니다: 파일이 로컬 파일인 경우 동작은 include:local과 동일합니다.

include를 사용하여 CI/CD 잡에 외부 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 섹션을 사용하면 기본값이 파이프라인의 모든 잡에 적용됩니다.

예를 들어, 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 파일에 정의된 production 잡의 POSTGRES_USER 및 POSTGRES_PASSWORD 변수와 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

install_dependencies와 deploy가 .gitlab-ci.yml 파일에서 반복되지 않으면, production 잡은 스크립트에 notify_owner만 포함됩니다.

중첩 포함 사용#

다른 구성에 포함되는 구성 파일에 include 섹션을 중첩할 수 있습니다. 예를 들어, 3단계로 중첩된 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` 항목이 있는 중첩 포함 사용#

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

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

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

default:
  before_script: echo "Default before script"

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

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

default:  # Override the included 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:  # Override the included 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'

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

사전 정의된 변수를 포함하는 방법과 변수가 CI/CD 잡에 미치는 영향에 대한 예시는 이 CI/CD 변수 데모를 참조하십시오.

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

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

히스토리

needs 잡 의존성에 대한 지원이 GitLab 15.11에서 도입.

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

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

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

히스토리

GitLab 16.1에서 ci_support_include_rules_when_never라는 플래그와 함께 when: never 및 when:always 지원이 도입. 기본적으로 비활성화됨.
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

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

히스토리

GitLab 16.1에서 ci_support_include_rules_when_never라는 플래그와 함께 when: never 및 when:always 지원이 도입. 기본적으로 비활성화됨.
GitLab 16.2에서 when: never 및 when:always 지원이 일반 공개. 기능 플래그 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와 함께 include를 사용하는 경우 구성을 신중히 검토하십시오. GitLab은 다른 프로젝트에서 파일의 존재 여부를 확인합니다. 예를 들어:

# Pipeline configuration in my-group/my-project
include:
  - project: my-group/other-project
    ref: other_branch
    file: other-file.yml

test:
  script: exit 0

# other-file.yml in my-group/other-project on ref other_branch
include:
  - project: my-group/my-project
    ref: main
    file: my-file.yml
    rules:
      - exists:
          - file.md

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

검색 컨텍스트를 변경하려면 rules:exists:project와 함께 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

이 예시에서:

builds1.yml은 Dockerfile이 변경된 경우 포함됩니다.
builds2.yml은 Dockerfile이 refs/heads/branch1에 대해 변경된 경우 포함됩니다.
builds3.yml은 Dockerfile이 변경되고 파이프라인 소스가 머지 리퀘스트 이벤트인 경우 포함됩니다. builds3.yml의 잡은 머지 리퀘스트 파이프라인에서 실행되도록 구성되어야 합니다.

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

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

예시:

include: 'configs/*.yml'

파이프라인이 실행되면 GitLab은:

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

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

# This matches all `.yml` files in `configs` and any subfolder in it.
include: 'configs/**.yml'

# This matches all `.yml` files only in subfolders of `configs`.
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 이후 GitLab Self-Managed 사용자는 최대 포함 값을 변경할 수 있습니다.

`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 사이트에 호스팅하는 것을 피해야 합니다.

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

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

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

원문 보기

번역일: 2026-05-22

요약

include를 사용하여 CI/CD 잡에 외부 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 섹션을 사용하면 기본값이 파이프라인의 모든 잡에 적용됩니다.

예를 들어, 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

`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

이 예시에서:

변수는 모든 파일이 병합된 후에만 평가됩니다. 포함된 파일의 잡은 다른 파일에 정의된 변수 값을 사용하게 될 수 있습니다.
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 잡은 스크립트에 notify_owner만 포함됩니다.

중첩 포함 사용#

다른 구성에 포함되는 구성 파일에 include 섹션을 중첩할 수 있습니다. 예를 들어, 3단계로 중첩된 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` 항목이 있는 중첩 포함 사용#

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

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

default:
  before_script: echo "Default before script"

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

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

default:  # Override the included 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:  # Override the included 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 잡에 미치는 영향에 대한 예시는 이 CI/CD 변수 데모를 참조하십시오.

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

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

히스토리

needs 잡 의존성에 대한 지원이 GitLab 15.11에서 도입.

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

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

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

히스토리

GitLab 16.1에서 ci_support_include_rules_when_never라는 플래그와 함께 when: never 및 when:always 지원이 도입. 기본적으로 비활성화됨.
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

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

히스토리

GitLab 16.1에서 ci_support_include_rules_when_never라는 플래그와 함께 when: never 및 when:always 지원이 도입. 기본적으로 비활성화됨.
GitLab 16.2에서 when: never 및 when:always 지원이 일반 공개. 기능 플래그 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의 존재 여부를 확인합니다.

# Pipeline configuration in my-group/my-project
include:
  - project: my-group/other-project
    ref: other_branch
    file: other-file.yml

test:
  script: exit 0

# other-file.yml in my-group/other-project on ref other_branch
include:
  - project: my-group/my-project
    ref: main
    file: my-file.yml
    rules:
      - exists:
          - file.md

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

검색 컨텍스트를 변경하려면 rules:exists:project와 함께 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

이 예시에서:

builds1.yml은 Dockerfile이 변경된 경우 포함됩니다.
builds2.yml은 Dockerfile이 refs/heads/branch1에 대해 변경된 경우 포함됩니다.
builds3.yml은 Dockerfile이 변경되고 파이프라인 소스가 머지 리퀘스트 이벤트인 경우 포함됩니다. builds3.yml의 잡은 머지 리퀘스트 파이프라인에서 실행되도록 구성되어야 합니다.

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

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

예시:

include: 'configs/*.yml'

파이프라인이 실행되면 GitLab은:

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

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

# This matches all `.yml` files in `configs` and any subfolder in it.
include: 'configs/**.yml'

# This matches all `.yml` files only in subfolders of `configs`.
include: 'configs/**/*.yml'

문제 해결#

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

중첩된 구성의 일부가 지나치게 많은 수의 추가 중첩 include 구성을 포함합니다.
중첩 포함에 우발적인 루프가 있습니다. 예를 들어, include1.yml이 include2.yml을 포함하고 include2.yml이 include1.yml을 포함하여 재귀 루프를 만드는 경우.

GitLab 16.0 이후 GitLab Self-Managed 사용자는 최대 포함 값을 변경할 수 있습니다.

`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와 함께 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 및 기타 네트워크 장애#

단일 구성 파일 포함#

구성 파일 배열 포함#

포함된 구성 파일에서 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 및 기타 네트워크 장애#

포함된 구성 파일에서 `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` 및 기타 네트워크 장애#

포함된 구성 파일에서 `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` 및 기타 네트워크 장애#