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 섹션을 정의할 수 있습니다. 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 명령이 script 명령 전에 두 rspec job 모두에서 실행됩니다.

포함된 구성 값 재정의#

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

다음 예시는 .gitlab-ci.yml 파일에서 사용자 정의된 include 파일을 보여줍니다. 특정 YAML로 정의된 변수와 production job의 세부 정보가 재정의됩니다.

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 job의 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

이 예시에서:

• 변수는 모든 파일이 병합된 후에만 평가됩니다. 포함된 파일의 job은 다른 파일에 정의된 변수 값을 사용하게 될 수 있습니다.

• 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은 스크립트에 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'

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

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

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

include와 함께 rules 사용#

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

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

• rules:if.

• rules:exists.

• rules:changes.

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

rules:exists와 함께 include 사용#

History

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

다른 프로젝트의 포함 파일에서 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 사용#

History

• 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

이 예시에서:

• builds1.yml은 Dockerfile이 변경된 경우 포함됩니다.

• builds2.yml은 Dockerfile이 refs/heads/branch1에 대해 변경된 경우 포함됩니다.

• builds3.yml은 Dockerfile이 변경되고 파이프라인 소스가 머지 리퀘스트 이벤트인 경우 포함됩니다. builds3.yml의 job은 머지 리퀘스트 파이프라인에서 실행되도록 구성되어야 합니다.

와일드카드 파일 경로와 함께 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 Self-Managed 사용자는 최대 포함 값을 변경할 수 있습니다.

include:local 사용 시 Error: 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 연결을 설정할 수 없을 때 발생합니다. 이 문제는 원격 호스트가 서버 과부하를 방지하기 위한 속도 제한이 있는 경우에 발생할 수 있습니다.

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

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