GitLab CI 완벽 가이드

GitLab CI/CD를 활용한 자동화된 파이프라인 구축 방법을 소개합니다. 고급 기능인 캐싱, 아티팩트 관리, 병렬 실행, 환경별 배포 전략까지 실무에 바로 적용 가능한 패턴을 다룹니다.

---

---

들어가며

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

목차

1. 기본_파이프라인_구성
2. Docker_이미지_활용
3. 캐시_최적화_전략
4. 아티팩트_관리
5. 병렬_실행_최적화
6. 조건부_실행_규칙
7. 환경별_배포_전략
8. 시크릿_변수_관리
9. 재사용_가능한_템플릿
10. 다운스트림_파이프라인
11. 실패_처리_및_재시도
12. 성능_모니터링_통합

---

1. 기본 파이프라인 구성

개요

.gitlab-ci.yml 파일을 통해 빌드, 테스트, 배포 단계를 정의하는 기본 파이프라인 구조입니다.

코드 예제

stages:
  - build
  - test
  - deploy

build-job:
  stage: build
  script:
    - npm install
    - npm run build

설명

stages에서 실행 순서를 정의하고, 각 job에서 stage를 지정하여 순차적으로 실행됩니다. build-job은 build 단계에서 의존성 설치와 빌드를 수행합니다.

---

2. Docker 이미지 활용

개요

Docker 이미지를 사용하여 일관된 빌드 환경을 구성하고, 서비스 컨테이너를 연결합니다.

코드 예제

test-job:
  image: node:18-alpine
  services:
    - postgres:14
  variables:
    POSTGRES_DB: testdb
  script:
    - npm test

설명

node:18-alpine 이미지로 Node.js 환경을 제공하고, services로 PostgreSQL 컨테이너를 연결하여 통합 테스트를 실행합니다.

---

3. 캐시 최적화 전략

개요

의존성 파일을 캐싱하여 파이프라인 실행 속도를 크게 향상시키는 방법입니다.

코드 예제

cache:
  key: ${CI_COMMIT_REF_SLUG}
  paths:
    - node_modules/
    - .npm/
  policy: pull-push

build-job:
  script:
    - npm ci --cache .npm

설명

브랜치별로 node_modules와 npm 캐시를 저장하여 재사용하며, npm ci 명령으로 빠르고 안정적인 설치를 수행합니다.

---

4. 아티팩트 관리

개요

빌드 결과물을 아티팩트로 저장하고 다음 단계에서 재사용하여 효율성을 높입니다.

코드 예제

build-job:
  script:
    - npm run build
  artifacts:
    paths:
      - dist/
    expire_in: 1 week

deploy-job:
  dependencies:
    - build-job

설명

dist/ 디렉토리를 아티팩트로 저장하고 1주일 동안 보관합니다. deploy-job은 dependencies로 build-job의 아티팩트를 자동으로 받아 사용합니다.

---

5. 병렬 실행 최적화

개요

테스트를 여러 작업으로 분할하여 병렬 실행함으로써 전체 파이프라인 시간을 단축합니다.

코드 예제

test-job:
  parallel: 4
  script:
    - npm run test -- --shard=${CI_NODE_INDEX}/${CI_NODE_TOTAL}

lint-job:
  parallel:
    matrix:
      - LINT_TARGET: [js, css, html]
  script:
    - npm run lint:${LINT_TARGET}

설명

parallel로 4개의 테스트 샤드를 동시 실행하고, matrix를 사용해 여러 린트 작업을 병렬로 처리합니다.

---

6. 조건부 실행 규칙

개요

rules를 활용하여 특정 조건에서만 job을 실행하도록 제어합니다.

코드 예제

deploy-prod:
  stage: deploy
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
      when: manual
    - when: never
  script:
    - npm run deploy:prod

설명

main 브랜치에서만 실행되며 수동 승인이 필요합니다. 조건에 맞지 않으면 절대 실행되지 않습니다.

---

7. 환경별 배포 전략

개요

environment를 정의하여 staging과 production 환경을 분리하고 배포 이력을 추적합니다.

코드 예제

deploy-staging:
  stage: deploy
  environment:
    name: staging
    url: https://staging.example.com
    on_stop: stop-staging
  script:
    - kubectl apply -f k8s/staging/

설명

staging 환경으로 배포하며 환경 URL과 중지 작업을 연결합니다. GitLab UI에서 배포 상태와 이력을 시각적으로 확인할 수 있습니다.

---

8. 시크릿 변수 관리

개요

CI/CD 변수를 사용하여 API 키와 같은 민감한 정보를 안전하게 관리합니다.

코드 예제

deploy-job:
  script:
    - echo "Deploying with key"
    - |
      curl -X POST https://api.example.com/deploy \
        -H "Authorization: Bearer $DEPLOY_TOKEN" \
        -d '{"version":"'$CI_COMMIT_SHA'"}'

설명

GitLab 설정에서 보호된 변수 $DEPLOY_TOKEN을 등록하고, 스크립트에서 안전하게 참조하여 API 호출에 사용합니다.

---

9. 재사용 가능한 템플릿

개요

extends와 YAML 앵커를 활용하여 중복을 제거하고 유지보수성을 높입니다.

코드 예제

.deploy-template: &deploy
  script:
    - npm run deploy
  only:
    - main

deploy-aws:
  <<: *deploy
  variables:
    DEPLOY_TARGET: aws

deploy-gcp:
  <<: *deploy
  variables:
    DEPLOY_TARGET: gcp

설명

공통 배포 설정을 템플릿으로 정의하고, 각 job에서 상속받아 변수만 변경하여 재사용합니다.

---

10. 다운스트림 파이프라인

개요

trigger를 사용하여 다른 프로젝트의 파이프라인을 연쇄적으로 실행합니다.

코드 예제

trigger-microservice:
  stage: deploy
  trigger:
    project: team/microservice-api
    branch: main
    strategy: depend
  variables:
    PARENT_PIPELINE_ID: $CI_PIPELINE_ID

설명

현재 파이프라인에서 다른 프로젝트의 파이프라인을 트리거하고, strategy: depend로 완료를 대기합니다. 마이크로서비스 아키텍처에서 유용합니다.

---

11. 실패 처리 및 재시도

개요

retry와 allow_failure를 사용하여 일시적 오류를 처리하고 파이프라인 안정성을 높입니다.

코드 예제

integration-test:
  script:
    - npm run test:integration
  retry:
    max: 2
    when:
      - runner_system_failure
      - stuck_or_timeout_failure
  allow_failure:
    exit_codes: 137

설명

시스템 오류 시 최대 2번 재시도하며, 특정 종료 코드(메모리 부족)는 실패로 처리하지 않아 파이프라인 전체가 중단되지 않습니다.

---

12. 성능 모니터링 통합

개요

파이프라인 성능 메트릭을 수집하고 GitLab에서 시각화합니다.

코드 예제

test-job:
  script:
    - npm test -- --coverage
  coverage: '/Lines\s*:\s*(\d+\.\d+)%/'
  artifacts:
    reports:
      coverage_report:
        coverage_format: cobertura
        path: coverage/cobertura.xml

설명

정규식으로 커버리지 비율을 추출하고, cobertura 형식의 리포트를 아티팩트로 저장하여 GitLab UI에서 커버리지 추세를 확인할 수 있습니다.

---

마치며

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

관련 태그

#GitLab #CI/CD #Pipeline #Docker #Automation