InfoGrab
InfoGrab
블로그GitLab CI/CD 파이프라인 최적화 방법

GitLab CI/CD 파이프라인 최적화 방법

.gitlab-ci.yml 유지 보수성 높이기

··21 min read
GitLab CI/CD 파이프라인 최적화 방법

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

include 사용한 파일 분할

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

include 사용법

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

로컬 파일 포함

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

yaml
# .gitlab-ci.yml

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

원격 파일 포함

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

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을 얻을 수 있습니다. 파일을 위치한 경로로 이동한 후, 오른쪽 상단의 Open raw 버튼을 클릭하면 Raw URL을 얻을 수 있습니다.


다른 프로젝트 파일 포함

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

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 키워드를 사용하면 포함된 파일에 매개변수를 전달해 더 유연하게 설정할 수 있습니다. 아래 예시를 참고하세요.

yaml
# .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 섹션을 추가해야 합니다.

yaml
# 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)를 참조하고 가져오는 데 사용됩니다. 아래 예시를 참고하세요.

yaml
# 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)이나 설정을 기반으로 새로운 작업을 만들면서 일부를 수정하거나 추가할 수 있습니다. 다음 순서대로 사용하세요.

기본 설정 정의

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

yaml
# 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 키워드를 사용해 이 템플릿을 상속받아 사용할 수 있습니다. 아래 예시를 참고하세요.

yaml
# 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 사용법

yaml
# 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는 & 기호를 사용해 정의합니다. 아래 예시를 참고하세요.

yaml
# 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를 참조할 수 있습니다. 아래 예시를 참고하세요.

yaml
# 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 변수를 동적으로 설정하는 방법을 보여줍니다.

yaml
# 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 파이프라인이 실행된 모습 build, test, deploy 파이프라인이 실행된 모습

길어지는 .gitlab-ci.yml, 관리할 수 있는 구조인가요?

include와 extends, workflow 같은 기능으로 파이프라인을 나누고 재사용하면 유지보수가 쉬워집니다. 인포그랩이 브랜치 전략부터 안전한 배포와 롤백까지 GitLab CI/CD 파이프라인 구축과 운영을 함께합니다.

CI/CD 파이프라인 구축 상담하기
자주 묻는 질문
include 키워드로 파일 분할, !reference와 extends 키워드로 파이프라인 상속, workflow 키워드로 파이프라인 전역 제어, YAML Anchors와 Aliases로 설정 재사용, variables와 rules로 동적 파이프라인 구성의 다섯 가지가 핵심입니다. 이 방법들은 복잡한 파이프라인을 모듈화하고 중복을 줄여 가독성과 유지 보수성을 높입니다. .gitlab-ci.yml은 프로젝트의 빌드, 테스트, 배포 과정을 정의하는 GitLab CI/CD 파이프라인의 핵심 파일입니다.
include 키워드는 다른 YAML 파일을 파이프라인에 포함해 설정을 여러 파일로 나눠 관리하게 해 줍니다. local로 프로젝트 루트 기준 상대 경로의 파일을, remote로 원격 파일을, project와 file, ref로 같은 GitLab 인스턴스의 다른 프로젝트 파일을 가져올 수 있으며, remote에는 Blob URL이 아니라 Raw URL을 써야 합니다. inputs 키워드를 함께 쓰면 포함한 파일에 매개변수를 넘길 수 있는데, 이때 대상 파일에는 spec 섹션으로 inputs를 정의해야 합니다.
!reference는 이미 정의된 다른 항목의 일부, 예를 들어 before_script만 가져와 현재 섹션에서 재사용할 때 씁니다. extends는 기존 작업이나 템플릿 전체를 상속받아 새 작업을 만들면서 일부를 수정하거나 추가할 때 씁니다. 공통 설정은 보통 점(.)으로 시작하는 숨은 작업(Hidden Job)으로 정의하는데, 숨은 작업은 파이프라인에서 직접 실행되지 않고 다른 작업이 참조하는 템플릿 역할만 합니다.
workflow 키워드는 파이프라인 실행 조건을 전역으로 정해, 특정 상황에서만 파이프라인이 실행되도록 제어합니다. 예를 들어 workflow의 rules에 develop 브랜치, release/ 패턴의 브랜치, inputs로 전달된 기본 브랜치일 때만 실행하고 나머지는 when: never로 막을 수 있습니다. 이렇게 하면 작업마다 규칙을 따로 정의하지 않아도 되고, 불필요한 빌드를 막아 리소스를 효율적으로 쓸 수 있습니다.
YAML의 Anchor(&)로 공통 설정을 정의하고 Alias(*)와 병합 키로 여러 작업에서 재사용할 수 있지만, YAML 문법이라 같은 파일 안에서만 쓸 수 있고 include로 가져온 파일과는 함께 쓸 수 없습니다. variables와 rules 키워드를 함께 쓰면 실행 조건에 따라 변숫값을 동적으로 바꿀 수 있습니다. 예를 들어 BUILD_ENV를 develop 브랜치에서는 develop, release 브랜치에서는 release, main·master 브랜치에서는 production으로 설정해 환경별로 다른 빌드 결과물을 만들 수 있습니다.

참고 자료

  1. Optimize GitLab CI/CD configuration files
  2. Use CI/CD configuration from other files
  3. GitLab CI/CD workflow keyword
⚠️
해당 콘텐츠는 저작권법에 의하여 보호 받는 저작물로 기고자에게 저작권이 있습니다.
사전 동의 없이 2차 가공 및 영리적인 이용을 금하며, 온·오프라인에 무단 전재 또는 유포할 수 없습니다.
Chad

DevOps Engineer

InfoGrab의 DevOps Engineer로서, 인프라 운영부터 AI 에이전트 자동화까지 폭넓게 다룹니다. Kubernetes·Teleport·GitLab CI/CD 기반 인프라 설계와 운영을 담당하며, Claude Code 스킬·MCP 서버 등 AI Native 방식의 업무 자동화를 적극 실험하고 있습니다. 반복 작업을 에이전트에게 위임하는 구조를 만드는 데 관심이 많고, 클러스터에서 직접 인프라를 구성하고 검증하는 것을 즐깁니다. 만든 것을 도구화하여 팀에 공유하는 스타일로 일합니다.

이 저자의 글 모두 보기 →

이 글이 도움이 되셨나요?

인포그랩 전문가가 맞춤 상담을 도와드립니다.

InfoGrab Infoletter

최신 DevOps·AI 트렌드를 매달 받아보세요