CI/CD 파이프라인 구축

지난 절에서는 NestJS 애플리케이션을 Docker 이미지로 만드는 방법을 알아보았습니다.

이번 절에서는 그 이미지를 임의로 다시 만들지 않고, 소스 검증부터 운영 배포까지 하나의 추적 가능한 경로로 연결합니다. 예시는 GitHub Actions와 Docker Hub, 단일 EC2 호스트를 사용하지만 핵심 원칙은 다른 레지스트리와 배포 플랫폼에서도 같습니다.

NestJS에서 CI/CD란 무엇인가?

CI/CD는 코드를 자주 합치고, 기계적인 품질 검사를 반복하며, 검증 결과와 배포 기록을 연결하는 개발 관행입니다.

지속적 통합(Continuous Integration)

Pull Request와 main push는 같은 검증 job에서 다음 단계를 순서대로 통과합니다.

• npm ci: lockfile과 일치하는 의존성 설치
• npm run lint -- --no-fix: CI에서 소스를 고치지 않는 정적 검사
• npm run test -- --runInBand: 테스트 실행
• npm run build: TypeScript 컴파일과 NestJS 빌드 확인

이 절의 테스트 명령은 8장의 Jest 설정을 사용하는 예제 프로젝트를 전제로 합니다. npm run test -- --runInBand는 Jest 옵션이며, 현재 기본 Nest starter의 Vitest 프로젝트에는 그대로 적용하지 않습니다. 다른 runner는 해당 프로젝트의 script와 CI 옵션으로 맞춥니다.

하나라도 실패하면 이후 이미지 게시와 배포는 시작되지 않습니다. PR은 이 검증 결과까지만 얻으며 레지스트리 자격 증명이나 운영 비밀에 접근하지 않습니다.

지속적 제공(Continuous Delivery)

검증을 통과한 main 커밋은 컨테이너 이미지를 한 번 빌드해 레지스트리에 게시합니다. 태그는 커밋을 찾기 위한 이름이고, 실제 배포 입력은 게시 결과가 돌려준 sha256:... digest입니다.

운영 job이 GitHub의 보호된 production environment 승인을 기다린다면 이 파이프라인은 지속적 제공입니다. 배포 가능한 산출물은 자동으로 준비하지만 운영 반영에는 명시적인 승인이 남아 있기 때문입니다.

지속적 배포(Continuous Deployment)

승인 절차까지 자동 정책으로 대체하고, 모든 검증을 통과한 변경을 사람의 개입 없이 운영에 반영할 때 지속적 배포라고 부릅니다. 이 절의 예시는 보호된 환경 승인을 사용하므로 지속적 배포라고 주장하지 않습니다.

품질 게이트와 배포 불변성

파이프라인의 중요한 경계는 다음과 같습니다.

latest 같은 가변 태그를 운영 배포 입력으로 사용하면 승인한 이미지와 실제로 내려받는 이미지가 달라질 수 있습니다. 이 절에서는 이미지 게시 job의 digest 출력을 배포 job까지 그대로 전달해 그 우회를 막습니다.

실행 전 준비

• GitHub 저장소에 NestJS 프로젝트, package-lock.json, Dockerfile, .dockerignore, compose.yml이 있어야 합니다.
• compose.yml의 app.image는 ${IMAGE:?IMAGE digest is required}처럼 외부 IMAGE 값을 참조해야 합니다.
• EC2 호스트의 /opt/nestjs-app에는 운영용 compose.yml과 서버에서 관리하는 설정이 있어야 합니다.
• EC2 호스트에는 현재 docker compose 명령과 curl이 설치되어 있어야 합니다.
• Docker Hub에는 비밀번호 대신 권한을 제한한 액세스 토큰을 사용합니다.
• SSH 호스트 키는 신뢰할 수 있는 경로에서 미리 확인하고 known_hosts 한 줄 형식으로 보관합니다. 실행 중 ssh-keyscan으로 즉석 신뢰하지 않습니다.

앞 절의 개발용 compose.yaml은 로컬 소스로 이미지를 빌드합니다. 여기서 서버가 사용하는 운영용 compose.yml은 게시된 이미지를 실행하는 별도 설정입니다. app.image에 위 IMAGE 참조를 두고, 운영 환경 변수·포트·네트워크·볼륨을 준비합니다. 파일 이름을 바꾸는 것만으로 build 설정이 불변 이미지 배포 설정으로 바뀌지는 않습니다.

아래 헬스 게이트는 GET /health가 준비 상태를 검사하여 정상일 때 2xx, 준비되지 않았을 때 실패 상태를 반환하는 계약을 전제로 합니다. Nest가 이 경로를 자동 생성하지는 않습니다. 다음 절의 세 probe를 구현한 누적 프로젝트에서는 이 경로를 readiness와 연결하거나, 별도 변형에서 요청 경로를 실제 /health/ready 계약으로 맞춥니다. 전역 접두사·URI 버전을 사용했다면 probe의 실제 URL도 확인합니다. production의 required reviewers를 실제로 설정해야 아래 job이 사람의 승인을 기다립니다.

현재 예시는 프로젝트 런타임으로 Node.js 24 LTS를 사용합니다. actions/checkout@v7과 actions/setup-node@v6도 Node 24 기반의 현재 메이저이며, Docker 공식 액션은 docker/login-action@v4, docker/build-push-action@v7을 사용합니다.

GitHub Actions 워크플로우

.github/workflows/main.yml에 다음 전체 워크플로우를 작성합니다. PR 검증과 main 이미지 게시, 보호된 운영 배포를 분리하며, 아래의 Builder 준비 조각은 해당 이미지 job에 추가하는 별도 보완입니다.

name: NestJS quality gate and deploy

on:
  pull_request:
    branches: [main]
  push:
    branches: [main]

env:
  NODE_VERSION: '24'
  IMAGE_NAME: nestjs-app

permissions:
  contents: read

jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v7
        with:
          persist-credentials: false

      - name: Set up Node.js
        uses: actions/setup-node@v6
        with:
          node-version: ${{ env.NODE_VERSION }}
          cache: npm

      - name: Install locked dependencies
        run: npm ci

      - name: Lint without rewriting source
        run: npm run lint -- --no-fix

      - name: Test
        run: npm run test -- --runInBand

      - name: Build NestJS
        run: npm run build

  image:
    needs: verify
    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    outputs:
      repository: ${{ steps.image-meta.outputs.repository }}
      digest: ${{ steps.image-build.outputs.digest }}
    steps:
      - name: Checkout repository
        uses: actions/checkout@v7
        with:
          persist-credentials: false

      - name: Define image repository
        id: image-meta
        env:
          DOCKER_USERNAME: ${{ secrets.DOCKER_USERNAME }}
        run: echo "repository=docker.io/${DOCKER_USERNAME}/${IMAGE_NAME}" >> "$GITHUB_OUTPUT"

      - name: Log in to Docker Hub
        uses: docker/login-action@v4
        with:
          registry: docker.io
          username: ${{ secrets.DOCKER_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - name: Build and push once
        id: image-build
        uses: docker/build-push-action@v7
        with:
          context: .
          push: true
          tags: ${{ steps.image-meta.outputs.repository }}:${{ github.sha }}
          cache-from: type=gha
          cache-to: type=gha,mode=max

  deploy:
    needs: image
    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    timeout-minutes: 10
    environment:
      name: production
    concurrency:
      group: production
      cancel-in-progress: false
    steps:
      - name: Deploy exact digest and run bounded health gate
        env:
          EC2_HOST: ${{ secrets.EC2_HOST }}
          EC2_USERNAME: ${{ secrets.EC2_USERNAME }}
          EC2_SSH_KEY: ${{ secrets.EC2_SSH_KEY }}
          EC2_SSH_KNOWN_HOSTS: ${{ secrets.EC2_SSH_KNOWN_HOSTS }}
          IMAGE_REF: ${{ needs.image.outputs.repository }}@${{ needs.image.outputs.digest }}
        run: |
          install -d -m 700 "$HOME/.ssh"
          printf '%s\n' "$EC2_SSH_KEY" > "$HOME/.ssh/id_ed25519"
          chmod 600 "$HOME/.ssh/id_ed25519"
          printf '%s\n' "$EC2_SSH_KNOWN_HOSTS" > "$HOME/.ssh/known_hosts"
          chmod 600 "$HOME/.ssh/known_hosts"

          ssh \
            -i "$HOME/.ssh/id_ed25519" \
            -o BatchMode=yes \
            -o StrictHostKeyChecking=yes \
            -o ConnectTimeout=10 \
            -o ServerAliveInterval=15 \
            -o ServerAliveCountMax=2 \
            "${EC2_USERNAME}@${EC2_HOST}" \
            bash -s -- "$IMAGE_REF" <<'REMOTE'
          set -euo pipefail

          IMAGE_REF="$1"
          cd /opt/nestjs-app

          sudo env IMAGE="$IMAGE_REF" docker compose pull app
          sudo env IMAGE="$IMAGE_REF" docker compose up -d --no-deps app

          healthy=false
          for attempt in $(seq 1 12); do
            if curl --fail --silent --show-error --max-time 2 \
              http://127.0.0.1:3000/health > /dev/null; then
              healthy=true
              break
            fi
            sleep 5
          done

          if [ "$healthy" != "true" ]; then
            echo "Health gate failed; release is not accepted."
            echo "Rollback is explicit: redeploy a previously approved digest."
            exit 1
          fi
          REMOTE

워크플로우를 읽는 법

verify는 PR과 main에서 모두 실행됩니다. 반면 image는 main push 조건을 다시 확인하므로 PR에서는 Docker Hub 비밀이 열리지 않고 이미지도 게시되지 않습니다.

docker/build-push-action의 digest 출력은 Registry에 게시된 manifest를 가리킵니다. 배포 job은 repository@digest를 IMAGE_REF로 만들고, 서버의 docker compose pull과 up에 같은 값을 전달합니다. 두 명령 모두 sudo env IMAGE="$IMAGE_REF" ... 형태이므로 sudo가 기본 환경을 정리하더라도 필요한 이미지 값이 명시적으로 전달됩니다.

type=gha 캐시는 빌드 성공 조건과 별도로 Builder의 지원 조건을 확인합니다. Docker의 캐시 문서에 따르면 기본 docker 드라이버에서는 containerd image store가 켜져 있어야 합니다. 이 조건을 충족하지 않는 환경은 공식 Buildx 설정 예시처럼 캐시를 지원하는 Builder를 먼저 구성합니다. 원 워크플로우의 빌드 단계는 유지하되, image.steps에서 Build and push once 전에 다음 추가 단계를 둘 수 있습니다.

- name: Set up Docker Buildx
  uses: docker/setup-buildx-action@v4
  with:
    driver: docker-container

배포는 서드파티 SSH action 대신 GitHub 호스팅 러너의 OpenSSH 클라이언트를 직접 사용합니다. 서드파티 action을 사용해야 한다면 변경 가능한 태그가 아니라 검토한 전체 commit SHA에 고정해야 합니다.

헬스 확인은 요청당 2초 타임아웃, 최대 12회, 재시도 사이 5초 대기로 제한됩니다. 모두 실패하면 job과 GitHub deployment 기록이 실패하지만, 위 스크립트는 이전 컨테이너로 자동 복귀하지 않습니다. 자동 롤백이라고 설명하려면 이전 digest 저장, 전환, 재검증까지 별도로 구현해야 합니다.

실행 결과를 단계별로 판단하기 PR에서 테스트가 실패하면 verify가 실패하고 이미지 게시·배포는 실행되지 않습니다. main 검증과 이미지 게시가 성공하여 digest A를 얻었더라도 운영 승인 대기 중에는 아직 A를 서버에 배포하지 않습니다. 승인 뒤 A를 실행하고 처음 두 헬스 요청이 실패하다 세 번째가 성공하면 세 번째 요청에서 반복을 끝내고 A를 유지합니다. 두 번의 실패 뒤에만 각각 5초 대기가 발생합니다.

독립 점검 승인된 새 digest B를 실행한 뒤 12번의 헬스 요청이 모두 실패했습니다. 이전 정상 digest는 A로 기록되어 있습니다. job 결과, 서버가 자동으로 A로 돌아가는지, 운영자가 다음에 확인하고 선택할 입력을 설명하세요. 요청·대기만의 최대 시간을 계산할 때는 원 코드가 마지막 실패 뒤에도 sleep 5를 실행한다는 점을 포함합니다. Compose·SSH·명령 실행 부대 시간은 이 계산에서 제외합니다.

비밀과 승인 경계 설정

Docker Hub 자격 증명은 저장소 Actions secret으로 설정하되 main 전용 image job에서만 참조합니다.

• DOCKER_USERNAME: Docker Hub 사용자 이름
• DOCKERHUB_TOKEN: 이미지 push 범위만 가진 액세스 토큰

EC2 접속 값은 저장소 공용 secret이 아니라 production environment secret으로 설정합니다.

• EC2_HOST: 운영 호스트 주소
• EC2_USERNAME: 제한된 운영 사용자
• EC2_SSH_KEY: 해당 사용자용 SSH 개인 키
• EC2_SSH_KNOWN_HOSTS: 사전에 확인한 호스트 공개 키의 known_hosts 항목

production environment에는 필요한 경우 required reviewers, self-review 방지, main만 허용하는 deployment branch 규칙을 설정하고 관리자 우회도 허용하지 않습니다. 승인 대기 중인 job은 environment secret에 접근할 수 없으므로 승인 전에 운영 비밀이 열리지 않는 경계가 만들어집니다. 사용할 수 있는 보호 규칙은 GitHub 요금제와 저장소 공개 범위에 따라 다를 수 있습니다.

운영 DB 비밀번호와 JWT 비밀값은 이미지나 GitHub workflow에 넣지 않습니다. 서버의 제한된 env 파일, AWS Secrets Manager, SSM Parameter Store, Vault 같은 운영 비밀 저장소에서 런타임에 주입합니다.

감사, 관측, 복구

GitHub Actions 로그와 environment deployment 기록은 누가 어떤 커밋에서 어떤 digest를 게시하고 승인했는지 추적하는 출발점입니다. 애플리케이션 로그, 지표, 경보와 지속적인 가용성 관측은 별도의 운영 시스템이 담당해야 합니다. 배포 직후의 제한된 헬스 게이트만으로 이후 가용성을 보장할 수는 없습니다.

복구 절차는 다음처럼 명시적으로 운영합니다.

1. 실패한 deployment와 헬스 로그를 확인합니다.
2. 이전에 승인되어 정상 동작한 repository@sha256:... 값을 배포 기록에서 선택합니다.
3. 동일한 production 승인 경로로 그 digest를 다시 배포합니다.
4. 제한된 헬스 게이트와 외부 모니터링을 다시 확인합니다.

PR에서 운영 job을 직접 호출하는 경로, 승인되지 않은 job이 environment secret을 읽는 경로, latest 태그로 digest를 바꾸는 경로는 허용하지 않습니다. 편의를 위한 우회 하나가 소스·산출물·승인·배포 기록의 연결을 끊기 때문입니다.

CI/CD 파이프라인의 목적은 단계 수를 늘리는 것이 아니라, 실패해야 할 지점에서 빠르게 멈추고 승인한 동일 산출물만 다음 경계로 이동시키는 것입니다.

NestJS 프로젝트에서는 npm ci → lint → test → build를 먼저 고정하고, 그 위에 불변 이미지 digest, 보호된 운영 승인, 제한된 헬스 확인, 명시적 복구와 관측을 한 층씩 더하면 됩니다.