GitLab CI/CD 파이프라인의 핵심인 .gitlab-ci.yml 파일은 프로젝트의 빌드, 테스트, 배포 과정을 정의합니다. 이 파일을 효율적으로 관리하고 유지 보수하려면, GitLab의 다양한 문법과 YAML 기능을 적절히 활용해야 합니다. 이 글에서는 .gitlab-ci.yml 파일의 유지 보수성을 높이는 5가지 핵심 방법을 소개하겠습니다.

include 사용한 파일 분할​

include 키워드는 GitLab CI/CD에서 파이프라인 설정을 여러 파일로 분할해 관리하는 기능입니다. 이 키워드를 사용해 복잡한 파이프라인을 여러 파일로 나눠 정의하면 설정 파일의 가독성과 유지 보수성을 크게 향상할 수 있습니다.

include 사용법​

include 키워드는 .gitlab-ci.yml 파일에서 다른 YAML 파일을 파이프라인에 포함하는 데 사용됩니다. 이 키워드를 사용하면 로컬 파일, 원격 파일, 다른 프로젝트의 파일을 가져올 수 있습니다. 그 결과, 파이프라인 구성의 모듈화와 재사용성을 개선할 수 있습니다. 구체적인 사용법을 살펴보겠습니다.

로컬 파일 포함

이는 프로젝트 내의 다른 YAML 파일을 포함하는 가장 간단하고 직접적인 방법입니다. 프로젝트의 루트 디렉터리를 기준으로 포함할 파이프라인 파일의 상대 경로를 아래와 같이 지정합니다.

# .gitlab-ci.yml

include:
  # Local 파일 포함
  - local: "workflow/workflow.gitlab-ci.yml"
  - local: "template/build/build.gitlab-ci.yml"

원격 파일 포함

GitLab에서는 원격 YAML 파일도 포함할 수 있습니다. 이 방법은 공용 템플릿이나 외부 리소스를 사용할 때 유용합니다. 아래 예시를 참고하세요.

# .gitlab-ci.yml

include:
  # Remote 파일 포함
  - remote: 'https://gitlab.com/chad_infograb/pipeline-template/-/raw/main/template/test/test.gitlab-ci.yml'
참고

원격 파일을 remote로 포함할 때 브라우저에서 파일을 보는 Blob URL이 아닌, 파일 원본 내용을 그대로 표시하는 Raw URL을 사용해야 합니다.

파일을 위치한 경로로 이동한 후, 오른쪽 상단의 **Open raw** 버튼을 클릭하면 Raw URL을 얻을 수 있습니다. | 인포그랩 GitLab
파일을 위치한 경로로 이동한 후, 오른쪽 상단의 Open raw 버튼을 클릭하면 Raw URL을 얻을 수 있습니다.


다른 프로젝트 파일 포함

같은 GitLab 인스턴스 내에 있는 다른 프로젝트의 YAML 파일도 포함할 수 있습니다. 아래 예시를 참고하세요.

# .gitlab-ci.yml

include:
  # Project 파일 포함 (다른 GitLab 프로젝트의 파일)
  - project: "infograb/personal/chad/poc/pipeline-template"
    file: 
      - "/template/deploy/deploy.gitlab-ci.yml"
    ref: main

위 예시에서는 infograb/personal/chad/poc/pipeline-template 프로젝트의 main 브랜치에 있는 deploy.gitlab-ci.yml 파일을 현재 프로젝트의 CI/CD 파이프라인에 포함합니다.


include와 inputs 사용법​

include 키워드와 함께 inputs 키워드를 사용하면 포함된 파일에 매개변수를 전달해 더 유연하게 설정할 수 있습니다. 아래 예시를 참고하세요.

# .gitlab-ci.yml

include:
  # Local 파일 포함
  - local: 'workflow/workflow.gitlab-ci.yml'
    inputs:
      default_branch: main

위 예시에서는 workflow/workflow.gitlab-ci.yml 파일을 포함하면서 default_branch 변숫값을 main으로 설정합니다.

참고

inputs 키워드를 사용하려면 include 대상 파일에 아래와 같이 spec 섹션을 추가해야 합니다.

# workflow/workflow.gitlab-ci.yml

# Input spec 정의
spec:
  inputs:
    default_branch:
      description: "The default branch name to use for workflow rules"
      type: string
      default: main
---

# Workflow 설정

...(중략)...

!reference와 extends 사용한 파이프라인 상속​

!reference 키워드와 extends 키워드는 GitLab CI/CD에서 설정 재사용성을 높이는 강력한 도구입니다. 두 키워드를 활용하면 파이프라인 구성을 모듈화하고 중복을 최소화해 복잡한 파이프라인도 쉽게 관리하고 확장할 수 있습니다.

!reference 사용법​

!reference 키워드는 이미 정의된 다른 항목 내용의 일부(예:before_script)를 참조하고 가져오는 데 사용됩니다. 아래 예시를 참고하세요.

# template/build/build.gitlab-ci.yml

# 기본 before_script 정의 1
.before_script_1:
  before_script:
    - echo "Running before_script_1 tasks..."

# 기본 before_script 정의 2
.before_script_2:
  before_script:
    - !reference [.before_script_1, before_script]
    - echo "Running before_script_2 tasks..."

위 예시에서 .before_script_2는 .before_script_1의 내용 중 before_script 구성을 현재 섹션에 재사용하면서 추가 동작("Running before_script_2 tasks...")을 실행합니다.


extends 사용법​

GitLab CI/CD YAML 파일에서 extends 키워드를 사용하면 기존의 작업(job)이나 설정을 기반으로 새로운 작업을 만들면서 일부를 수정하거나 추가할 수 있습니다. 다음 순서대로 사용하세요.

기본 설정 정의

먼저 공통된 설정을 위해 점(.)으로 시작하는 숨은 작업 템플릿을 정의합니다. 이 템플릿은 다른 작업에서 참조할 수 있습니다. 아래 예시를 참고하세요.

# template/build/build.gitlab-ci.yml

# 기본 before_script 정의 1
.before_script_1:
  before_script:
    - echo "Running before_script_1 tasks..."

# 기본 before_script 정의 2
.before_script_2:
  before_script:
    - !reference [.before_script_1, before_script]
    - echo "Running before_script_2 tasks..."
참고

‘숨은 작업(Hidden Job)’이란?
GitLab CI/CD의 숨은 작업은 다른 작업에서 참조하는 템플릿 역할을 합니다. 이 작업은 파이프라인에서 직접 실행되지 않으며, 대신 다른 작업에서 재사용됩니다. 점(.)으로 시작하는 이름으로 정의되며, 예를 들어 .before_script_1, .before_script_2는 파이프라인에서 직접 실행되지 않고, 다른 작업에서 설정을 재사용하거나 확장할 때 활용됩니다.


템플릿 상속

이제 다른 작업에서 extends 키워드를 사용해 이 템플릿을 상속받아 사용할 수 있습니다. 아래 예시를 참고하세요.

# template/build/build.gitlab-ci.yml

# Build Job 정의
build_job:
  stage: build
  extends: .before_script_2
  script:
    - echo "Starting the build process..."
    - echo "Compiling the code..."
    - echo "Running unit tests..."
    - echo "Packaging the application..."
    - echo "Build process completed successfully."
    - echo "This is the build artifact file" > ./output.txt
  artifacts:
    paths:
      - ./output.txt

위 예시에서 파이프라인은 .before_script_2에서 정의된 before_script를 확장해 빌드 작업을 수행합니다.


workflow 사용한 파이프라인 전역 제어​

workflow 키워드를 사용하면 GitLab CI/CD 파이프라인의 실행 조건을 전역적으로 설정할 수 있습니다. 이 기능을 활용해 특정 상황에서만 파이프라인을 실행하도록 제어할 수 있습니다. 그 결과, 리소스를 효율적으로 사용하고 불필요한 빌드를 방지할 수 있습니다.

workflow 사용법​

# workflow/workflow.gitlab-ci.yml

workflow:
  rules:
    - if: '$CI_COMMIT_REF_NAME == "develop"'
    - if: '$CI_COMMIT_REF_NAME =~ /^release\/.*$/'
    - if: '$CI_COMMIT_REF_NAME =~ "$[[ inputs.default_branch ]]"'
    - when: never  # 위 조건에 해당하지 않는 브랜치에서는 파이프라인 실행 안 함

workflow 키워드는 위 예시와 같이 다음 조건을 설정합니다:

  • 브랜치 이름이 develop일 때 파이프라인을 실행합니다.
  • release/* 패턴과 일치하는 모든 브랜치(예:release/v0.1.0)에서 파이프라인을 실행합니다.
  • inputs.default_branch로 정의된 값과 브랜치 이름이 일치할 때 파이프라인을 실행합니다. 이 변수는 파이프라인 설정 외부에서 전달됩니다.
  • 위의 if 조건에 해당하지 않으면, 파이프라인을 실행하지 않습니다.

이러한 워크플로 설정은 develop 브랜치, release/* 패턴의 브랜치, 외부에서 전달된 기본 브랜치(inputs.default_branch로 정의)에서만 파이프라인을 실행합니다. 다른 모든 브랜치에서는 파이프라인이 실행되지 않습니다. 이 방식을 사용하면 작업마다 개별적으로 규칙(rules)을 정의할 필요가 없습니다.


YAML Anchors와 Aliases 사용한 설정 재사용​

YAML은 Anchor(&)와 Alias(*) 기능을 기본으로 제공합니다. 이를 활용해 동일한 설정을 여러 곳에서 재사용할 수 있습니다. 이 기능은 GitLab CI/CD의 .gitlab-ci.yml 파일에도 동일하게 적용돼 중복된 설정을 줄이고 더 쉽게 유지 보수하도록 지원합니다. 다음 순서대로 사용하세요.

참고

Anchors와 Aliases는 YAML 문법 일부로, 동일한 파일 내에서만 사용할 수 있습니다. 따라서 include 키워드로 외부 파일을 가져올 때는 사용할 수 없습니다.

Anchor 정의​

먼저 Anchor로 재사용할 설정을 정의합니다. Anchor는 & 기호를 사용해 정의합니다. 아래 예시를 참고하세요.

# template/deploy/deploy.gitlab-ci.yml

.deploy_template: &deploy_template
  stage: deploy
  script:
    - echo "Starting the deployment process to $CI_COMMIT_REF_NAME..."
    - echo "Deploying application for $CI_COMMIT_REF_NAME..."
    - echo "Deployment completed successfully."

위 예시에서는 &deploy_template이라는 이름으로 배포 작업의 공통 설정을 정의합니다. 이 Anchor는 배포 단계(stage: deploy)와 배포 스크립트(script)를 포함하며, 배포 작업에서 수행될 일련의 명령어를 정의합니다.


Alias로 재사용​

이제 다른 작업에서 * 기호를 사용해 위에서 정의한 Anchor를 참조할 수 있습니다. 아래 예시를 참고하세요.

# template/deploy/deploy.gitlab-ci.yml

deploy_dev:
  <<: *deploy_template
  rules:
    - if: '$CI_COMMIT_REF_NAME == "develop"'

deploy_stg:
  <<: *deploy_template
  rules:
    - if: '$CI_COMMIT_REF_NAME =~ /^release\/.*$/'

deploy_prd:
  <<: *deploy_template
  rules:
    - if: '$CI_COMMIT_REF_NAME == "main"'

위 예시에서 각 배포 작업(deploy_dev, deploy_stg, deploy_prd)은 *deploy_template Alias를 사용해 앞서 정의한 &deploy_template Anchor를 참조합니다. 이로써 모든 배포 작업이 동일한 배포 스크립트를 효율적으로 재사용할 수 있습니다.

참고

<< (Merge Key Language-Independent Type)
YAML은 위 표현을 사용해 하나 이상 지정된 map의 모든 키를 현재 map에 병합할 수 있습니다. 이미 존재하는 키에서 Alias는 병합되지 않습니다.


동적 파이프라인 구성​

GitLab CI/CD에서는 다양한 조건에 따라 파이프라인 변수를 동적으로 설정할 수 있습니다. 이로써 파이프라인 유연성이 높아지며, 특정 상황에 맞게 동작을 조정할 수 있습니다. GitLab의 variables 키워드와 rules 키워드를 함께 사용하면, 파이프라인 실행 중 특정 조건에 따라 변숫값을 동적으로 변경할 수 있습니다.

조건에 맞게 동적으로 변수 설정​

파이프라인 내에서 변수를 동적으로 설정하기 위해 rules 키워드를 사용합니다. rules 키워드로 특정 조건이 충족될 때 변숫값을 변경해 파이프라인 유연성을 높일 수 있습니다. 설정 방법은 아래와 같습니다.

브랜치에 따라 빌드 명령어 변경

다음 예시는 커밋이 발생한 브랜치에 따라 BUILD_ENV 변수를 동적으로 설정하는 방법을 보여줍니다.

# template/build/build.gitlab-ci.yml

# Build Job 정의
build_job:
  stage: build
  extends: .before_script_2
  script:
    - echo "Starting the build process..."
    - echo "Compiling the code..."
    - echo "Running unit tests..."
    - echo "Packaging the application..."

    # 브랜치에 따라 다른 결과물 생성
    - echo "This is the build artifact for $BUILD_ENV environment" > ./output_$BUILD_ENV.txt
  artifacts:
    paths:
      - ./output_*.txt
  rules:
    - if: '$CI_COMMIT_REF_NAME == "develop"'
      variables:
        BUILD_ENV: "develop"
    - if: '$CI_COMMIT_REF_NAME =~ /^release\/.*$/'
      variables:
        BUILD_ENV: "release"
    - if: '$CI_COMMIT_REF_NAME == "main" || $CI_COMMIT_REF_NAME == "master"'
      variables:
        BUILD_ENV: "production"

위 예시에서 파이프라인은 rules 섹션에서 BUILD_ENV 변수를 정의해 브랜치에 따라 빌드 환경을 다르게 설정합니다.

각 브랜치에 BUILD_ENV 변수가 아래와 같이 설정됩니다.

  • develop 브랜치: BUILD_ENV는 "develop"
  • release/* 패턴의 브랜치: BUILD_ENV는 "release"
  • main 또는 master 브랜치: BUILD_ENV는 "production"

브랜치별로 다음과 같이 빌드 결과물을 생성합니다.

  • 파이프라인 실행 시, script 섹션에서 BUILD_ENV 값에 따라 다른 빌드 결과물을 생성합니다.
  • 예시:
    • develop 브랜치: output_develop.txt 생성
    • release/* 브랜치: output_release.txt 생성
    • main 또는 master 브랜치: output_production.txt 생성
  • 이러한 파일은 각 환경에 맞춘 빌드 결과물로, artifacts 섹션에 지정된 경로에 저장됩니다.

맺음말​

위에서 소개한 방법을 활용하면 GitLab CI/CD 파이프라인을 더 효율적이고 쉽게 유지 보수하도록 구성할 수 있습니다. 본문에서 언급한 코드 예시는 다음 링크를 클릭하면 자세히 확인하실 수 있습니다. 감사합니다.

build, test, deploy 파이프라인이 실행된 모습 | 인포그랩 GitLab
build, test, deploy 파이프라인이 실행된 모습

참고 자료​

  1. Optimize GitLab CI/CD configuration files
  2. Use CI/CD configuration from other files
  3. GitLab CI/CD workflow keyword

완벽한 GitLab 구축부터 성공적인 DevOps 도입까지! 인포그랩과 DevOps 라이프사이클을 함께하세요.