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

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

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 명령은 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 파일에서 정의된 값이 재정의됩니다. 다른 키워드는 변경되지 않습니다. 이 방법을 Merge이라고 합니다.

include에 대한 Merge 방법

include 구성은 다음 과정으로 기본 구성 파일과 병함됩니다:

  • 포함된 파일은 구성 파일에 정의된 순서대로 읽혀지며, 포함된 구성은 동일한 순서로 Merge됩니다.
  • 포함된 파일이 include를 사용하는 경우, 해당 중첩된 include 구성은 먼저 Merge됩니다 (재귀적으로).
  • 매개 변수가 겹치는 경우, 마지막으로 포함된 파일이 포함된 파일의 구성을 Merge할 때 우선합니다.
  • include로 추가된 모든 구성을 모두 Merge한 후, 주 구성이 포함된 구성과 Merge됩니다.

이 Merge 방법은 _깊은 Merge_으로, 해시 맵이 구성의 어떠한 깊이에서도 Merge됩니다. 지금까지 Merge된 구성을 포함한 해시 맵 “A”와 “B”를 Merge하려면 키와 값은 다음과 같이 처리됩니다:

  • 키가 A에만 있는 경우, A에서 키와 값 사용.
  • 키가 A와 B에 모두 있는 경우, 값이 모두 해시 맵인 경우, 이러한 해시 맵을 Merge합니다.
  • 키가 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

Merge된 결과는 다음과 같습니다: 

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

이 예에서 변수는 모든 파일이 Merge된 후에 평가됩니다. 포함된 파일에서 정의된 변수 값 중 하나가 포함된 파일과 다른 파일에서 사용될 수 있습니다. rules는 배열이므로 Merge될 수 없습니다. 최상위 파일이 우선합니다. artifacts는 해시 맵이므로 깊은 Merge이 가능합니다.

포함된 구성 배열 재정의

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

중첩된 포함에서 중복된 include 항목 사용

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

예를 들어, 다음과 같이 중첩된 포함이 있는 경우, 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-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 이후에는 다음을 사용할 수도 있습니다:

예를 들어: 

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

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

사전 정의된 변수를 포함하는 방법과 변수가 CI/CD 작업에 미치는 영향에 대한 예제는 이 CI/CD 변수 데모를 참조하세요.

include와 rules 함께 사용

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

rules와 특정 변수만 사용할 수 있으며, 이러한 키워드를 사용할 수 있습니다:

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이 제거됨.

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

  • 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

변경된 파일에 기반하여 다른 구성 파일을 조건부로 포함하기 위해 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이 변경되고 파이프라인 소스가 merge request 이벤트인 경우 builds3.yml이 포함됩니다.

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

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

예: 

include: 'configs/*.yml'

파이프라인이 실행될 때 GitLab은:

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

  • configs 디렉터리의 하위 폴더의 .yml 파일은 추가하지 않습니다. 이를 허용하려면 다음 구성을 추가하세요: 

    # 이 구성은 `configs` 및 그 하위 폴더의 모든 `.yml` 파일에 일치합니다.
include: 'configs/**.yml'
  
# 이 구성은 `configs`의 하위 폴더에서만 모든 `.yml` 파일에 일치합니다.
include: 'configs/**/*.yml'

문제 해결

최대 150개의 중첩된 include가 허용됨! 오류

파이프라인의 중첩된 포함된 파일의 최대 수는 150입니다. 파이프라인에서 최대 150개의 include가 허용됨 오류 메시지를 받으면 다음 중 하나일 수 있습니다:

  • 일부 중첩된 구성이 지나치게 많은 추가 중첩된 include 구성을 포함합니다.
  • 중첩된 포함에서 우연히 루프가 있습니다. 예를 들어 include1.yml가 include2.yml를 포함하고 include2.yml가 include1.yml를 포함하여 재귀적 루프를 만듭니다.

이러한 상황을 줄일 수 있도록 도와주는 파이프라인 구성 파일을 파이프라인 편집기에서 편집하세요. 이를 통해 제한이 도달되었을 때 알려줍니다. 루프 또는 과도한 포함된 파일의 원래인 파일을 확인하기 위해 하나씩 포함된 파일을 제거할 수 있습니다.

GitLab 16.0 및 이후의 영구적 사용자는 최대 포함 수 값을 변경할 수 있습니다.