- 단일 구성 파일 포함하기
- 구성 파일 배열 포함하기
- 포함된 구성 파일의
default
구성 사용하기 - 포함된 구성 값 재정의
- 포함된 구성 배열 재정의
- 중첩 포함 사용하기
include
와 변수 사용하기-
include
와rules
사용하기 include:local
을 와일드카드 파일 경로와 함께 사용하기- 문제 해결
다른 파일에서 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
와 함께 include
사용하기
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 인스턴스 내 다른 프로젝트에서 구성 파일을 가져오세요.