🦊
GitLab CI/CD 치트시트

GitLab 내장 CI/CD 파이프라인 완벽 가이드: GitLab Runner 설치 및 등록, .gitlab-ci.yml 문법 구조, Stages·Jobs 아키텍처, Artifacts vs Cache 차이점, Rules 조건부 실행, Docker-in-Docker(dind) 컨테이너 빌드, 수동 승인(Manual) 배포, 템플릿 상속(extends/include) 및 프로덕션 운영 체크리스트
#gitlab-ci#gitlab#cicd#devops#pipeline#docker#runner#automation#yaml#deployment최종 업데이트: 2026-10-08
GitLab CI/CD 치트시트 핵심 명령어 및 실전 가이드

## 1. 필수 사전 설치 요건 & 개발 환경 구성 (Prerequisites)

GitLab CI/CD는 GitLab 저장소에 기본 내장된 강력한 지속적 통합/지속적 배포 시스템입니다. 별도의 CI 서버(Jenkins 등)를 설치할 필요 없이, 저장소 루트에 `.gitlab-ci.yml` 파일을 작성하고 **GitLab Runner**를 연결하는 것만으로 동작합니다.

### 🦊 1. GitLab 호스팅 환경
- **GitLab.com (SaaS)**: 가입 즉시 무료 공유 러너(Shared Runner)가 제공되므로 별도 러너 설치 없이 즉시 파이프라인을 실행할 수 있습니다.
- **GitLab Self-Managed (온프레미스 CE/EE)**: 회사 사내망 서버에 설치된 GitLab 인스턴스를 사용하는 경우 전용 GitLab Runner 설치가 필수입니다.

### 🏃 2. GitLab Runner 설치 & 등록 (Docker Executor 권장)
사내 서버나 로컬 PC를 빌드 실행기(Runner)로 등록합니다:

```bash
# 1. Docker 환경에서 GitLab Runner 컨테이너 실행
docker run -d \
  --name gitlab-runner \
  --restart always \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v gitlab-runner-config:/etc/gitlab-runner \
  gitlab/gitlab-runner:latest

# 2. GitLab 인스턴스에 Runner 등록 (Registration)
# ※ GitLab 프로젝트 -> Settings -> CI/CD -> Runners -> Registration Token 확인
docker run --rm -it \
  -v gitlab-runner-config:/etc/gitlab-runner \
  gitlab/gitlab-runner:latest register \
  --non-interactive \
  --url "https://gitlab.com/" \
  --registration-token "GLRT-xxxxxxxxxxxxxxxxxxxx" \
  --executor "docker" \
  --docker-image "alpine:latest" \
  --description "my-docker-runner" \
  --tag-list "docker,linux" \
  --run-untagged="true" \
  --locked="false"
```

### ⚙️ 3. 파일 규격 및 환경변수(Variables) 설정
1. **파일 위치**: 저장소 최상위 루트에 `.gitlab-ci.yml` 이름으로 생성합니다.
2. **비밀 환경변수 설정**:
   - 경로: `Settings` ➔ `CI/CD` ➔ `Variables` ➔ **Add variable**
   - **Type**: `Variable` (일반 문자열) 또는 `File` (인증서, pem 키)
   - **Flags**:
     - **Protect variable**: `Protected` 브랜치/태그에서만 노출
     - **Mask variable**: 작업 콘솔 로그에 평문 노출 방지 (`[MASKED]` 치환)

---

## 2. GitLab CI/CD 핵심 아키텍처 & 멘탈 모델 (Mental Model)

GitLab CI/CD는 중앙 코디네이터(GitLab Server)와 분산 작업 실행기(GitLab Runner) 간의 협업으로 동작합니다.

### 🏗️ GitLab CI/CD 아키텍처
```text
┌────────────────────────────────────────────────────────┐
│               GitLab Coordinator (Server)              │
│  - Git 커밋 / MR 이벤트 감지 및 .gitlab-ci.yml 파싱     │
│  - Pipeline 생성, Stage 스케줄링, Job 상태 관리        │
│  - 웹 대시보드 그래프 UI, Artifacts & Cache 스토리지 저장│
└───────────────────────────┬────────────────────────────┘
                            │ (HTTPS REST API / gRPC 폴링)
            ┌───────────────┴───────────────┐
            ▼                               ▼
┌───────────────────────┐       ┌───────────────────────┐
│ GitLab Runner #1      │       │ GitLab Runner #2      │
│ (Docker Executor)     │       │ (Kubernetes Executor) │
│ - Maven / Gradle 빌드 │       │ - 대규모 병렬 테스트   │
│ - 단위 테스트 실행    │       │ - 운영 클러스터 배포   │
└───────────────────────┘       └───────────────────────┘
```

### 🔄 파이프라인 계층 구조 (Pipeline Hierarchy)
```text
[Pipeline]
   │
   ├─► [Stage: build]
   │      ├─ Job: compile-frontend  (동시 병렬 실행)
   │      └─ Job: compile-backend   (동시 병렬 실행)
   │
   ├─► [Stage: test] (build 단계의 모든 Job이 성공해야 진입)
   │      ├─ Job: unit-tests
   │      └─ Job: security-scan
   │
   ├─► [Stage: package]
   │      └─ Job: build-docker-image
   │
   └─► [Stage: deploy]
          ├─ Job: deploy-dev (자동 실행)
          └─ Job: deploy-prod (수동 승인 버튼 대기: when: manual)
```

---

## 3. [초보자 1단계] 헬로월드: 최소 동작 예제

저장소 루트에 `.gitlab-ci.yml` 파일을 만들고 즉시 동작을 검증할 수 있는 최소 파이프라인입니다.

### 📄 파일 생성: `.gitlab-ci.yml`
```yaml
# 1. 기본 실행 도커 이미지 정의
default:
  image: alpine:latest

# 2. 파이프라인 단계 순서 정의
stages:
  - build
  - test
  - deploy

# 3. 첫 번째 단계 Job: 빌드 시뮬레이션
job_build:
  stage: build
  script:
    - echo "=== [Stage 1] 애플리케이션 빌드 시작 ==="
    - uname -a
    - mkdir -p dist
    - echo "LuckyTechWorld App v1.0.0" > dist/app.txt
    - echo "빌드 산출물 생성 완료: dist/app.txt"
  artifacts:
    paths:
      - dist/
    expire_in: 1 hour

# 4. 두 번째 단계 Job: 테스트 시뮬레이션
job_test:
  stage: test
  script:
    - echo "=== [Stage 2] 테스트 단계 수행 중 ==="
    - cat dist/app.txt
    - echo "모든 테스트 케이스 통과!"

# 5. 세 번째 단계 Job: 배포 시뮬레이션
job_deploy:
  stage: deploy
  script:
    - echo "=== [Stage 3] 헬로월드 배포 완료 ==="
    - echo "배포 성공: 서비스 정상 운영 중"
```

### 💻 실행 및 웹 콘솔 출력 확인
코드를 Git 커밋하고 원격 저장소로 `git push`하면 파이프라인이 자동 트리거됩니다:

1. GitLab 웹 UI 좌측 메뉴 ➔ **Build** ➔ **Pipelines** 이동
2. 생성된 최신 파이프라인 클릭 ➔ `job_build` 클릭하여 콘솔 로그 확인:

```text
Running with gitlab-runner 16.8.0 (xxxxxxxx)
  on my-docker-runner xxxxxxxx
Preparing the "docker" executor
Using Docker executor with image alpine:latest ...
Pulling docker image alpine:latest ...
Using docker image sha256:xxxxxxxx for alpine:latest ...
$ echo "=== [Stage 1] 애플리케이션 빌드 시작 ==="
=== [Stage 1] 애플리케이션 빌드 시작 ===
$ uname -a
Linux runner-xxxx 5.15.0 #1 SMP Linux
$ mkdir -p dist
$ echo "LuckyTechWorld App v1.0.0" > dist/app.txt
$ echo "빌드 산출물 생성 완료: dist/app.txt"
빌드 산출물 생성 완료: dist/app.txt
Uploading artifacts...
dist/: found 1 matching files and directories
Uploading artifacts as "archive" to coordinator... 201 Created
Job succeeded
```

---

## 4. [초보자 2단계] 핵심 기능 & 파이프라인 문법

실무 프로젝트에서 매일 사용하는 캐싱, 아티팩트, 조건 제어(`rules`), 사전 정의 환경변수 문법입니다.

### 📦 1. Artifacts(산출물) vs Cache(캐시) 완벽 비교
| 구분 | Artifacts (산출물) | Cache (캐시) |
| :--- | :--- | :--- |
| **주요 목적** | 다음 Stage의 Job으로 컴파일 결과물(바이너리, jar, dist) 전달 | 패키지 의존성(`node_modules`, `.m2`, `.gradle`)을 재사용하여 빌드 가속 |
| **보장성** | 동일 파이프라인 내에서 다운스트림 Job에 **100% 전달 보장** | 다운로드 실패 시에도 빌드는 계속 진행 (Best-effort 보장) |
| **GitLab UI** | 웹 브라우저에서 zip 파일로 직접 다운로드 가능 | UI 다운로드 불가, 러너 간 S3/로컬 디스크에 공유 보관 |

```yaml
build_app:
  stage: build
  image: node:20-alpine
  # 패키지 매니저 캐시 설정 (재다운로드 방지)
  cache:
    key:
      files:
        - package-lock.json
    paths:
      - .npm/
  script:
    - npm ci --cache .npm --prefer-offline
    - npm run build
  # 빌드 결과물 전달 설정
  artifacts:
    name: "build-$CI_COMMIT_SHORT_SHA"
    paths:
      - dist/
    expire_in: 1 week
```

### 🚦 2. Rules: 모던 파이프라인 실행 조건 제어
레거시 `only/except`를 대체하는 현대적인 조건문 시스템입니다.

```yaml
deploy_staging:
  stage: deploy
  script:
    - ./deploy-staging.sh
  rules:
    # 1. develop 브랜치로 푸시될 때만 자동 실행
    - if: '$CI_COMMIT_BRANCH == "develop"'
      when: on_success

deploy_production:
  stage: deploy
  script:
    - ./deploy-prod.sh
  rules:
    # 2. main 브랜치일 때는 웹 UI에서 사람이 수동 승인 버튼을 눌러야 실행
    - if: '$CI_COMMIT_BRANCH == "main"'
      when: manual
      allow_failure: false # 승인 없이 다음 단계로 넘어가지 못하도록 방지
    # 3. 그 외 다른 브랜치는 이 Job을 아예 생성하지 않음
    - when: never
```

### 🔑 3. 유용한 사전 정의 환경변수 (Predefined CI Variables)
GitLab이 파이프라인 런타임에 자동으로 제공하는 핵심 변수들입니다:

| 환경 변수명 | 값 예시 | 설명 |
| :--- | :--- | :--- |
| `$CI_COMMIT_BRANCH` | `main`, `feat/login` | 현재 커밋이 위치한 브랜치 이름 |
| `$CI_COMMIT_SHORT_SHA` | `7b3f12a` | 커밋 해시 앞 8자리 (도커 이미지 태그에 최적) |
| `$CI_PIPELINE_IID` | `42` | 현재 프로젝트 내 파이프라인 순차 증가 번호 |
| `$CI_REGISTRY_IMAGE` | `registry.gitlab.com/group/project` | GitLab 프로젝트 내장 도커 레지스트리 URL |
| `$CI_REGISTRY_USER` | `gitlab-ci-token` | GitLab 레지스트리 로그인용 임시 시스템 유저 |
| `$CI_JOB_TOKEN` | `[MASKED]` | 러너가 GitLab API 및 패키지 레지스트리에 인증하는 임시 토큰 |

### 🔀 4. 병렬 매트릭스 빌드 (Parallel Matrix)
여러 Node/Java 버전이나 OS 환경에서 테스트를 동시에 수행합니다.

```yaml
matrix_tests:
  stage: test
  image: node:${NODE_VERSION}-alpine
  parallel:
    matrix:
      - NODE_VERSION: ['18', '20', '22']
  script:
    - node -v
    - npm test
```

---

## 5. [초보자 3단계] 실무 응용 패턴 & 프로덕션 파이프라인

실무 프로덕션 환경에서 사용하는 Docker 이미지 빌드(dind), GitLab 레지스트리 푸시, K8s 배포 및 재사용 템플릿을 포함한 완전한 `.gitlab-ci.yml` 예제입니다.

### 📄 실전 프로덕션 `.gitlab-ci.yml` (복사해서 바로 사용 가능)
```yaml
# ==========================================
# 🦊 LuckyTech Enterprise Production Pipeline
# ==========================================

# 전역 설정
stages:
  - lint
  - build
  - test
  - package
  - deploy

variables:
  DOCKER_DRIVER: overlay2
  DOCKER_TLS_CERTDIR: "/certs"
  IMAGE_TAG: "$CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA"
  LATEST_TAG: "$CI_REGISTRY_IMAGE:latest"

# 🧩 1. 재사용 가능한 공통 잡 템플릿 (Hidden Job)
.node_template:
  image: node:20-alpine
  cache:
    key:
      files:
        - package-lock.json
    paths:
      - .npm/
  before_script:
    - npm ci --cache .npm --prefer-offline

# ------------------------------------------
# Stage 1: 코드 정적 분석
# ------------------------------------------
lint_code:
  extends: .node_template
  stage: lint
  script:
    - npm run lint
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
    - if: '$CI_COMMIT_BRANCH == "main" || $CI_COMMIT_BRANCH == "develop"'

# ------------------------------------------
# Stage 2: 애플리케이션 빌드
# ------------------------------------------
compile_app:
  extends: .node_template
  stage: build
  script:
    - npm run build
  artifacts:
    name: "dist-$CI_COMMIT_SHORT_SHA"
    paths:
      - dist/
    expire_in: 2 days

# ------------------------------------------
# Stage 3: 단위 테스트 & 커버리지 수집
# ------------------------------------------
unit_test:
  extends: .node_template
  stage: test
  script:
    - npm test -- --coverage
  coverage: '/All files[^|]*\|[^|]*\s+([\d\.]+)/'
  artifacts:
    reports:
      junit: junit.xml

# ------------------------------------------
# Stage 4: Docker 이미지 빌드 및 Registry 푸시
# ------------------------------------------
docker_build_push:
  stage: package
  image: docker:24.0.5
  services:
    - docker:24.0.5-dind # Docker-in-Docker 데몬 서비스 실행
  before_script:
    # GitLab 내장 컨테이너 레지스트리 자동 로그인
    - docker login -u "$CI_REGISTRY_USER" -p "$CI_JOB_TOKEN" "$CI_REGISTRY"
  script:
    - echo "도커 이미지 빌드 중: $IMAGE_TAG"
    - docker build -t "$IMAGE_TAG" -t "$LATEST_TAG" .
    - docker push "$IMAGE_TAG"
    - docker push "$LATEST_TAG"
  rules:
    - if: '$CI_COMMIT_BRANCH == "main" || $CI_COMMIT_BRANCH == "develop"'

# ------------------------------------------
# Stage 5-1: 개발 환경(Dev) 자동 배포
# ------------------------------------------
deploy_development:
  stage: deploy
  image: bitnami/kubectl:latest
  environment:
    name: development
    url: https://dev.luckytech.world
  script:
    - kubectl config set-cluster k8s --server="$KUBE_DEV_SERVER" --insecure-skip-tls-verify=true
    - kubectl config set-credentials admin --token="$KUBE_DEV_TOKEN"
    - kubectl config set-context default --cluster=k8s --user=admin
    - kubectl config use-context default
    - kubectl set image deployment/lucky-app lucky-app="$IMAGE_TAG" -n dev
    - kubectl rollout status deployment/lucky-app -n dev --timeout=3m
  rules:
    - if: '$CI_COMMIT_BRANCH == "develop"'

# ------------------------------------------
# Stage 5-2: 운영 환경(Prod) 관리자 수동 승인 배포
# ------------------------------------------
deploy_production:
  stage: deploy
  image: bitnami/kubectl:latest
  environment:
    name: production
    url: https://luckytech.world
  script:
    - kubectl config set-cluster k8s --server="$KUBE_PROD_SERVER" --insecure-skip-tls-verify=true
    - kubectl config set-credentials admin --token="$KUBE_PROD_TOKEN"
    - kubectl config set-context default --cluster=k8s --user=admin
    - kubectl config use-context default
    - kubectl set image deployment/lucky-app lucky-app="$IMAGE_TAG" -n prod
    - kubectl rollout status deployment/lucky-app -n prod --timeout=5m
  rules:
    - if: '$CI_COMMIT_BRANCH == "main"'
      when: manual             # 웹 대시보드에서 수동 [Play 버튼] 클릭 시 실행
      allow_failure: false
```

---

## 6. 실무 주의사항 & 프로덕션 체크리스트

### ⚠️ 1. 초보자가 가장 흔히 겪는 실수 & 해결법

| 번호 | 흔한 에러 및 증상 | 근본 원인 | 해결 방법 |
| :---: | :--- | :--- | :--- |
| **1** | `docker: command not found` 또는 데몬 연결 실패 | `image: docker`를 사용하면서 `services: [docker:dind]`를 누락했거나 Runner에 `privileged = true` 설정 없음 | `.gitlab-ci.yml`에 `services: [docker:dind]` 추가 및 러너 설정 파일(`/etc/gitlab-runner/config.toml`)에 `privileged = true` 부여 |
| **2** | 이전 Stage에서 만든 파일이 다음 Stage에서 사라짐 | `artifacts: paths` 지시어를 지정하지 않음 (각 Job은 격리된 컨테이너에서 새로 시작됨) | 생성된 파일이 담긴 디렉토리를 `artifacts: paths: [dist/]`로 등록 |
| **3** | Masked 변수 등록 시 에러 (`is invalid: regex match`) | 마스킹할 비밀키에 줄바꿈(엔터)이나 특수문자가 포함됨 | Base64로 인코딩하여 변수에 저장 후(`echo -n "secret" \| base64`), 스크립트 실행 시 `echo "$VAR" \| base64 -d` 디코딩하여 사용 |
| **4** | 레거시 `only/except`와 모던 `rules` 혼용 | 한 파이프라인 내에서 두 방식을 섞어 쓰면 예상치 못한 동작 발생 | 모든 Job을 모던 표준인 `rules:` 블록으로 일관되게 통일 |

### 🚀 2. 프로덕션 파이프라인 성능 최적화 팁
1. **Interruptible 플래그 활성화**:
   동일 브랜치에 새 커밋이 푸시되었을 때 이전의 불필요한 진행 중 파이프라인을 자동 취소하여 러너 자원을 절약합니다:
   ```yaml
   default:
     interruptible: true
   ```
2. **Docker 빌드 캐싱 (`--cache-from`)**:
   `docker build --cache-from $LATEST_TAG` 옵션을 사용하면 소스코드가 변경되지 않은 레이어의 재빌드를 건너뜁니다.
3. **루트리스(Rootless) Kaniko 도입**:
   Kubernetes 환경에서 보안 위험이 있는 privileged dind 대신 구글의 **Kaniko**를 사용하면 데몬 없이 안전하게 도커 이미지를 빌드할 수 있습니다.

### 📋 3. `.gitlab-ci.yml` 최상위 핵심 지시어 빠른 요약

```yaml
default:           # 모든 Job에 적용될 기본 설정 (image, cache, before_script)
variables:         # 전역 환경변수 선언
stages:            # 파이프라인 실행 단계 순서 선언
include:           # 외부/공통 YAML 템플릿 포함 (local, project, remote)

<job_name>:        # 개별 작업 선언
  stage:           # 소속될 stage 지정
  image:           # 작업 실행 도커 이미지
  services:        # 보조 컨테이너 (postgres, redis, dind 등)
  before_script:   # 메인 스크립트 실행 전 실행할 명령어
  script:          # 실행할 메인 셸 명령어 리스트 (필수)
  after_script:    # 작업 성공/실패 무관하게 종료 후 실행
  artifacts:       # 보관 및 다운스트림 전달 파일
  cache:           # 빌드 가속용 종속성 캐시
  rules:           # 실행 여부 조건문
  tags:            # 실행할 러너 태그 필터링
```
💬
GitLab CI/CD 치트시트

의견 및 질문

댓글 수정

댓글 삭제
