GitLab CI 디자인 패턴 고급 가이드

GitLab CI/CD 파이프라인을 효율적으로 구성하는 고급 디자인 패턴을 소개합니다. 재사용 가능한 템플릿, 동적 파이프라인, 병렬 처리 등 실전에서 바로 활용할 수 있는 패턴들을 다룹니다.

---

---

들어가며

이 글에서는 GitLab CI 디자인 패턴 고급 가이드에 대해 상세히 알아보겠습니다. 총 12가지 주요 개념을 다루며, 각각의 개념에 대한 설명과 실제 코드 예제를 함께 제공합니다.

목차

1. 템플릿_확장_패턴
2. 동적_차일드_파이프라인
3. 매트릭스_병렬_빌드
4. 조건부_needs_DAG
5. 규칙_기반_실행_제어
6. 캐시_레이어링_전략
7. 환경별_변수_관리
8. 앵커_재사용_패턴
9. 실패_허용_실험적_Job
10. 시크릿_검증_게이트
11. 멀티_프로젝트_파이프라인
12. 커버리지_리포팅_패턴

---

1. 템플릿 확장 패턴

개요

공통 CI 설정을 템플릿으로 분리하고 extends 키워드로 재사용하는 패턴입니다. 코드 중복을 줄이고 유지보수성을 높입니다.

코드 예제

# .gitlab/templates/base.yml
.base_deploy:
  stage: deploy
  before_script:
    - echo "Setting up environment"
  only:
    - main

# .gitlab-ci.yml
include:
  - local: '.gitlab/templates/base.yml'

deploy_prod:
  extends: .base_deploy
  script:
    - npm run deploy

설명

base.yml에 공통 설정을 정의하고, 실제 job에서 extends로 상속받아 사용합니다. 여러 job에서 동일한 설정을 반복하지 않아도 됩니다.

---

2. 동적 차일드 파이프라인

개요

런타임에 동적으로 생성된 YAML을 기반으로 하위 파이프라인을 실행하는 패턴입니다. 변경된 서비스만 선택적으로 빌드할 수 있습니다.

코드 예제

generate_pipeline:
  stage: prepare
  script:
    - node scripts/generate-pipeline.js > pipeline.yml
  artifacts:
    paths:
      - pipeline.yml

trigger_pipeline:
  stage: build
  trigger:
    include:
      - artifact: pipeline.yml
        job: generate_pipeline
    strategy: depend

설명

스크립트로 pipeline.yml을 동적 생성하고, trigger로 해당 파이프라인을 실행합니다. 모노레포에서 변경된 패키지만 빌드할 때 유용합니다.

---

3. 매트릭스 병렬 빌드

개요

parallel:matrix를 사용해 여러 환경 조합을 병렬로 테스트하는 패턴입니다. 다양한 버전 호환성을 효율적으로 검증합니다.

코드 예제

test:
  stage: test
  parallel:
    matrix:
      - NODE_VERSION: ['16', '18', '20']
        OS: ['ubuntu', 'alpine']
  image: node:${NODE_VERSION}-${OS}
  script:
    - npm test
  tags:
    - docker

설명

NODE_VERSION 3개 × OS 2개 = 총 6개 job이 병렬로 실행됩니다. 여러 환경에서의 호환성을 빠르게 확인할 수 있습니다.

---

4. 조건부 needs DAG

개요

needs를 활용해 job 간 의존성을 정의하는 DAG(방향성 비순환 그래프) 패턴입니다. 불필요한 대기 시간을 제거합니다.

코드 예제

build:
  stage: build
  script: npm run build

unit_test:
  stage: test
  needs: ['build']
  script: npm run test:unit

e2e_test:
  stage: test
  needs: ['build']
  script: npm run test:e2e

deploy:
  stage: deploy
  needs: ['unit_test', 'e2e_test']
  script: npm run deploy

설명

unit_test와 e2e_test가 build 완료 후 병렬 실행되고, 둘 다 성공하면 deploy가 실행됩니다. 전체 stage가 끝나기를 기다리지 않아 속도가 빨라집니다.

---

5. 규칙 기반 실행 제어

개요

rules를 사용해 복잡한 조건에 따라 job 실행을 제어하는 패턴입니다. if, changes, exists를 조합해 정교한 제어가 가능합니다.

코드 예제

deploy_backend:
  stage: deploy
  script: deploy backend
  rules:
    - if: '$CI_COMMIT_BRANCH == "main"'
      changes:
        - "backend/**/*"
      when: on_success
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
      changes:
        - "backend/**/*"
      when: manual
    - when: never

설명

main 브랜치에서 backend 파일이 변경되면 자동 실행, MR에서는 수동 실행, 그 외에는 실행 안 함을 정의합니다. 불필요한 파이프라인 실행을 방지합니다.

---

6. 캐시 레이어링 전략

개요

cache와 artifacts를 계층적으로 구성해 빌드 속도를 최적화하는 패턴입니다. 의존성과 빌드 결과물을 효율적으로 관리합니다.

코드 예제

variables:
  CACHE_KEY: ${CI_COMMIT_REF_SLUG}

.node_cache:
  cache:
    key: ${CACHE_KEY}-node
    paths:
      - node_modules/
    policy: pull

install:
  extends: .node_cache
  cache:
    policy: pull-push
  script:
    - npm ci

build:
  extends: .node_cache
  script:
    - npm run build
  artifacts:
    paths:
      - dist/

설명

install job은 node_modules를 캐시에 저장(push)하고, build job은 캐시를 가져와(pull) 사용합니다. artifacts로 빌드 결과물을 다음 stage에 전달합니다.

---

7. 환경별 변수 관리

개요

environment와 variables를 활용해 배포 환경별로 다른 설정을 적용하는 패턴입니다. 안전한 배포 워크플로우를 구성합니다.

코드 예제

.deploy_template:
  stage: deploy
  script:
    - echo "Deploying to $DEPLOY_ENV"
    - deploy --env=$DEPLOY_ENV

deploy_staging:
  extends: .deploy_template
  variables:
    DEPLOY_ENV: staging
  environment:
    name: staging
    url: https://staging.example.com

deploy_prod:
  extends: .deploy_template
  variables:
    DEPLOY_ENV: production
  environment:
    name: production
    url: https://example.com
  when: manual

설명

템플릿을 상속받아 환경별 변수만 오버라이드합니다. environment로 배포 이력을 추적하고, production은 수동 승인으로 안전하게 배포합니다.

---

8. 앵커 재사용 패턴

개요

YAML 앵커(&)와 별칭(*)을 사용해 중복 설정을 제거하는 패턴입니다. 복잡한 설정을 간결하게 관리합니다.

코드 예제

.docker_config: &docker_config
  image: node:18-alpine
  services:
    - docker:dind
  before_script:
    - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY

build_api:
  <<: *docker_config
  stage: build
  script:
    - docker build -t api:latest ./api

build_web:
  <<: *docker_config
  stage: build
  script:
    - docker build -t web:latest ./web

설명

docker_config 앵커에 공통 Docker 설정을 정의하고, <<: *docker_config로 재사용합니다. 설정 변경 시 한 곳만 수정하면 됩니다.

---

9. 실패 허용 실험적 Job

개요

allow_failure를 활용해 실험적인 테스트나 불안정한 job의 실패가 파이프라인을 중단하지 않도록 하는 패턴입니다.

코드 예제

experimental_test:
  stage: test
  script:
    - npm run test:experimental
  allow_failure: true

flaky_e2e:
  stage: test
  script:
    - npm run test:e2e:flaky
  retry:
    max: 2
    when:
      - runner_system_failure
      - stuck_or_timeout_failure
  allow_failure:
    exit_codes: [2, 137]

설명

experimental_test는 실패해도 파이프라인이 통과되고, flaky_e2e는 특정 종료 코드만 허용합니다. 불안정한 테스트가 전체 파이프라인을 막지 않습니다.

---

10. 시크릿 검증 게이트

개요

배포 전 필수 환경 변수와 시크릿을 검증하는 게이트키퍼 패턴입니다. 설정 누락으로 인한 배포 실패를 사전에 방지합니다.

코드 예제

validate_secrets:
  stage: .pre
  script:
    - |
      if [ -z "$DATABASE_URL" ]; then
        echo "DATABASE_URL is not set"
        exit 1
      fi
      if [ -z "$API_KEY" ]; then
        echo "API_KEY is not set"
        exit 1
      fi
      echo "All required secrets are configured"
  only:
    - main

설명

.pre stage에서 배포에 필요한 환경 변수를 검증합니다. 필수 변수가 없으면 파이프라인을 즉시 중단해 불필요한 빌드/테스트 시간을 절약합니다.

---

11. 멀티 프로젝트 파이프라인

개요

trigger를 사용해 다른 프로젝트의 파이프라인을 연쇄적으로 실행하는 패턴입니다. 마이크로서비스 간 의존성을 관리합니다.

코드 예제

trigger_downstream:
  stage: deploy
  trigger:
    project: mygroup/downstream-project
    branch: main
    strategy: depend
  rules:
    - if: '$CI_COMMIT_BRANCH == "main"'

trigger_parallel:
  stage: deploy
  trigger:
    - project: mygroup/service-a
    - project: mygroup/service-b
    - project: mygroup/service-c
  parallel: 3

설명

상위 프로젝트 배포 후 하위 프로젝트들을 자동으로 트리거합니다. strategy: depend로 하위 파이프라인 완료를 대기하거나, parallel로 여러 프로젝트를 동시에 트리거합니다.

---

12. 커버리지 리포팅 패턴

개요

coverage 정규식을 사용해 테스트 커버리지를 추출하고 GitLab UI에 표시하는 패턴입니다. 코드 품질 지표를 시각화합니다.

코드 예제

test_with_coverage:
  stage: test
  script:
    - npm run test:coverage
  coverage: '/Coverage: \d+\.\d+%/'
  artifacts:
    reports:
      coverage_report:
        coverage_format: cobertura
        path: coverage/cobertura-coverage.xml
    paths:
      - coverage/
    expire_in: 30 days

설명

정규식으로 콘솔 출력에서 커버리지를 파싱하고, cobertura 리포트를 GitLab에 업로드합니다. MR에서 커버리지 변화를 자동으로 확인할 수 있습니다.

---

마치며

이번 글에서는 GitLab CI 디자인 패턴 고급 가이드에 대해 알아보았습니다. 총 12가지 개념을 다루었으며, 각각의 사용법과 예제를 살펴보았습니다.

관련 태그

#GitLab #CI/CD #Pipeline #DevOps #Automation