Vercel + GitHub Actions CI/CD 자동 배포 세팅 완전 가이드

안녕하세요, 코드픽(CodePick) 기술 블로그 독자 여러분!

빠르게 변화하는 웹 개발 환경에서, 효율적이고 안정적인 배포 프로세스는 개발팀의 생산성과 서비스의 품질을 좌우하는 핵심 요소입니다. 특히 프론트엔드 프로젝트의 경우, 잦은 업데이트와 빠른 피드백이 중요하기 때문에 CI/CD(Continuous Integration/Continuous Deployment) 파이프라인 구축은 이제 선택이 아닌 필수가 되었습니다.

오늘은 많은 개발자들에게 사랑받는 배포 플랫폼 Vercel과 강력한 자동화 도구 GitHub Actions를 결합하여 CI/CD 자동 배포 시스템을 구축하는 완전 가이드를 소개해드리려 합니다. 이 가이드를 통해 여러분의 프로젝트 배포 과정을 혁신하고, 개발에만 집중할 수 있는 환경을 만들어 보세요.

1. CI/CD란 무엇인가요? 왜 중요할까요?

CI/CD는 현대 소프트웨어 개발에서 필수적인 방법론으로 자리 잡았습니다. 이 개념을 이해하는 것이 자동화된 배포 시스템을 구축하는 첫걸음입니다.

1.1. CI (Continuous Integration): 지속적인 통합

CI는 개발자들이 작성한 코드를 주기적으로 메인 브랜치(예: main 또는 master)에 병합(Integrate)하고, 자동으로 빌드 및 테스트하는 과정을 의미합니다.

핵심 목표:

충돌 최소화: 작은 단위로 자주 통합하여 코드 충돌 발생 시 빠르게 감지하고 해결합니다.
버그 조기 발견: 통합 과정에서 발생하는 문제를 자동화된 테스트를 통해 조기에 발견합니다.
코드 품질 향상: 일관된 빌드 및 테스트 환경을 제공하여 코드 품질을 유지합니다.

1.2. CD (Continuous Delivery/Deployment): 지속적인 제공/배포

CD는 CI 단계를 성공적으로 통과한 코드를 실제 운영 환경에 배포할 준비가 된 상태로 만들거나, 아예 자동으로 배포하는 과정을 의미합니다.

Continuous Delivery (지속적인 제공): 빌드 및 테스트가 완료된 코드를 수동 승인 후 배포할 수 있는 상태로 유지합니다. (배포 시점은 수동 결정)
Continuous Deployment (지속적인 배포): 빌드 및 테스트가 완료된 코드를 아무런 수동 개입 없이 자동으로 운영 환경에 배포합니다. (완전 자동화)

이 가이드에서는 Continuous Deployment, 즉 완전 자동 배포에 초점을 맞춥니다.

1.3. CI/CD의 핵심 이점

개발 생산성 향상: 수동 배포에 드는 시간과 노력을 절약하고, 개발자들은 코드 작성에 더 집중할 수 있습니다.
배포 오류 감소: 수동 작업 시 발생할 수 있는 휴먼 에러를 줄이고, 자동화된 검증을 통해 안정성을 높입니다.
빠른 피드백 루프: 변경 사항이 빠르게 배포되어 사용자 피드백을 신속하게 받을 수 있습니다.
시장 출시 시간 단축 (Time-to-Market): 새로운 기능이나 버그 수정이 더 빠르게 사용자에게 도달합니다.
코드 품질 향상: 자동화된 테스트와 통합으로 코드 베이스의 안정성과 신뢰성이 증대됩니다.

2. Vercel과 GitHub Actions, 왜 함께 사용해야 할까요?

Vercel과 GitHub Actions는 각각 강력한 기능을 제공하며, 이 둘을 함께 사용하면 시너지를 극대화하여 최고의 CI/CD 경험을 선사합니다.

2.1. Vercel의 강점

Vercel은 Next.js 개발팀이 만든 프론트엔드 배포 플랫폼으로, 뛰어난 성능과 개발자 친화적인 기능으로 각광받고 있습니다.

자동 배포 및 미리보기 (Preview Deployments): GitHub, GitLab, Bitbucket과 연동하여 코드 푸시 시 자동으로 배포를 시작하고, Pull Request(PR) 생성 시에는 미리보기 URL을 제공합니다. 이는 개발팀의 협업을 크게 개선합니다.
글로벌 CDN 및 엣지 캐싱: 전 세계에 분산된 CDN을 통해 사용자에게 가장 가까운 서버에서 콘텐츠를 제공하여 빠른 로딩 속도를 보장합니다.
서버리스 함수 (Serverless Functions): 백엔드 로직을 별도의 서버 없이 Vercel 플랫폼 내에서 실행할 수 있어 풀스택 개발에 용이합니다.
쉬운 설정과 관리: 대부분의 설정을 대시보드에서 직관적으로 관리할 수 있으며, Next.js, React, Vue 등 인기 프레임워크에 대한 최적화된 빌드 환경을 제공합니다.
환경 변수 관리: 개발, 스테이징, 프로덕션 환경에 따라 쉽게 환경 변수를 설정할 수 있습니다.

2.2. GitHub Actions의 강점

GitHub Actions는 GitHub 리포지토리 내에서 소프트웨어 개발 워크플로우를 자동화할 수 있는 강력한 CI/CD 도구입니다.

유연한 워크플로우 정의: YAML 파일을 통해 빌드, 테스트, 배포 등 모든 단계를 세밀하게 정의할 수 있습니다.
풍부한 액션 마켓플레이스: 다양한 개발자들이 만든 수많은 Actions를 활용하여 복잡한 작업을 손쉽게 자동화할 수 있습니다.
GitHub 생태계와의 완벽한 통합: 코드 저장소와 CI/CD 도구가 동일한 플랫폼 내에 있어 관리 및 연동이 매우 편리합니다.
무료 사용 범위: 개인 및 오픈소스 프로젝트에 대해 충분한 무료 사용 시간을 제공합니다.

2.3. Vercel과 GitHub Actions의 시너지 효과

정교한 제어: Vercel의 기본적인 자동 배포 기능만으로도 충분하지만, GitHub Actions를 통해 빌드 전 추가적인 테스트 실행, 코드 품질 검사, 특정 조건에서의 배포 제어 등 더욱 정교하고 복잡한 워크플로우를 구축할 수 있습니다.
단일 플랫폼 관리: 모든 CI/CD 로직이 GitHub 리포지토리 내 .github/workflows 디렉토리에 YAML 파일로 관리되므로, 코드와 배포 로직을 한곳에서 버전 관리하고 추적할 수 있습니다.
보안 강화: Vercel API 토큰과 같은 민감 정보를 GitHub Secrets에 안전하게 저장하고 워크플로우에서 활용할 수 있습니다.

이제 Vercel과 GitHub Actions를 활용하여 실제 프로젝트의 자동 배포 파이프라인을 구축하는 방법을 단계별로 알아보겠습니다.

3. 프로젝트 준비하기

먼저 Vercel과 GitHub에 프로젝트를 준비해야 합니다. 이 가이드에서는 Next.js 프로젝트를 예시로 들지만, React, Vue 등 다른 프론트엔드 프레임워크에도 동일하게 적용 가능합니다.

3.1. Vercel 프로젝트 생성 및 GitHub 연동

Vercel 계정 생성 및 로그인:
Vercel 웹사이트에 접속하여 GitHub 계정으로 간편하게 로그인하거나 회원가입을 진행합니다.
새 프로젝트 임포트:
로그인 후 Vercel 대시보드에서 Add New... > Project를 클릭합니다.
GitHub 계정이 연동되어 있다면, 연동된 GitHub 리포지토리 목록이 보일 것입니다. 자동 배포를 설정할 프로젝트 리포지토리를 선택하고 Import 버튼을 클릭합니다.
- 팁: 만약 리포지토리가 보이지 않는다면, Configure GitHub App을 클릭하여 Vercel이 접근할 수 있는 리포지토리를 설정해주세요. All repositories 또는 특정 리포지토리를 선택할 수 있습니다.
프로젝트 설정:
Vercel은 대부분의 인기 프레임워크(Next.js, React, Vue 등)를 자동으로 감지하여 최적의 빌드 설정을 제안합니다.
- Root Directory: 프로젝트의 package.json 파일이 있는 루트 디렉토리를 지정합니다. (대부분 .으로 기본 설정됩니다.)
- Build & Output Settings: 기본 설정을 사용해도 무방하지만, 필요에 따라 Build Command (예: npm run build), Output Directory (예: build, dist, .next) 등을 변경할 수 있습니다.
- Environment Variables: 필요한 환경 변수가 있다면 여기서 미리 설정할 수 있습니다.
  Deploy 버튼을 클릭하여 Vercel의 첫 자동 배포를 시작합니다.
첫 배포 확인:
배포가 완료되면 Vercel 대시보드에서 프로젝트의 배포 상태를 확인할 수 있습니다. 이제 GitHub에 코드를 푸시할 때마다 Vercel이 자동으로 빌드 및 배포를 수행할 것입니다.
- 주의: Vercel의 기본 GitHub 연동은 main 브랜치에 푸시할 때마다 자동으로 배포를 수행합니다. 하지만 우리는 GitHub Actions를 통해 이 과정을 더 세밀하게 제어할 것입니다.

3.2. GitHub 리포지토리 준비

Vercel에 연동한 프로젝트의 GitHub 리포지토리를 준비합니다.

만약 기존 프로젝트라면, 현재 상태를 확인합니다.
새 프로젝트라면, git init 후 초기 커밋을 하고 GitHub에 푸시합니다.

GitHub Actions 워크플로우 파일을 저장할 디렉토리를 생성합니다. 프로젝트 루트에 .github/workflows 디렉토리를 생성해주세요.

bash

mkdir -p .github/workflows

이제 이 디렉토리 안에 GitHub Actions 워크플로우 파일을 작성할 것입니다.

4. GitHub Actions 워크플로우 설정

이제 Vercel 배포를 위한 GitHub Actions 워크플로우를 생성하고 설정하는 핵심 단계입니다.

4.1. Vercel API 토큰 발급 및 GitHub Secrets 설정

GitHub Actions가 Vercel에 배포하려면 Vercel 계정에 접근할 수 있는 권한이 필요합니다. 이를 위해 Vercel API 토큰을 발급받고, GitHub 리포지토리의 Secrets에 안전하게 저장해야 합니다.

Vercel API 토큰 발급:
- Vercel 대시보드에 로그인합니다.
- 우측 상단 프로필 아이콘을 클릭하여 Settings로 이동합니다.
- 좌측 메뉴에서 Tokens를 선택합니다.
- Create New Token 버튼을 클릭합니다.
- Name에 토큰 이름을 입력합니다 (예: github-actions-deploy-token).
- Expires는 Never로 설정하는 것이 CI/CD에는 편리하지만, 보안을 위해 특정 기간으로 설정 후 주기적으로 갱신하는 것을 권장합니다.
- Create 버튼을 클릭하면 토큰이 생성되고 화면에 표시됩니다. 이 토큰은 한 번만 표시되므로 반드시 안전한 곳에 복사해두세요.
Vercel Project ID 및 Org ID 확인:
GitHub Actions에서 특정 Vercel 프로젝트에 배포하려면 VERCEL_ORG_ID와 VERCEL_PROJECT_ID가 필요합니다.
- Vercel 대시보드에서 해당 프로젝트를 클릭합니다.
- Settings 탭으로 이동합니다.
- General 섹션에서 Project ID와 Organization ID를 확인할 수 있습니다. 이 값들도 복사해둡니다.
GitHub Secrets 등록:
발급받은 Vercel API 토큰과 Project/Org ID를 GitHub 리포지토리의 Secrets에 등록합니다.
- GitHub에서 해당 프로젝트 리포지토리로 이동합니다.
- Settings 탭을 클릭합니다.
- 좌측 메뉴에서 Secrets and variables > Actions를 선택합니다.
- New repository secret 버튼을 클릭합니다.
- 다음 이름과 값으로 3개의 Secret을 추가합니다:
  - Name: VERCEL_TOKEN, Secret: (발급받은 Vercel API 토큰 값)
  - Name: VERCEL_ORG_ID, Secret: (Vercel에서 확인한 Organization ID 값)
  - Name: VERCEL_PROJECT_ID, Secret: (Vercel에서 확인한 Project ID 값)
이렇게 등록된 Secrets는 GitHub Actions 워크플로우에서 안전하게 참조할 수 있습니다.

4.2. 워크플로우 YAML 파일 작성 상세 가이드

이제 프로젝트 루트의 .github/workflows 디렉토리에 deploy-to-vercel.yml 파일을 생성하고 다음 내용을 작성합니다.

yaml

# .github/workflows/deploy-to-vercel.yml

name: Deploy to Vercel

on:
  push:
    branches:
      - main # main 브랜치에 푸시될 때마다 워크플로우 실행
  pull_request:
    branches:
      - main # main 브랜치로 PR이 생성될 때마다 워크플로우 실행 (미리보기 배포)

jobs:
  deploy:
    runs-on: ubuntu-latest # 워크플로우를 실행할 가상 환경 지정

    steps:
      - name: Checkout Repository
        uses: actions/checkout@v4 # GitHub 리포지토리 코드를 워크플로우 환경으로 가져옴

      - name: Setup Node.js
        uses: actions/setup-node@v4 # Node.js 환경 설정
        with:
          node-version: 20 # 사용할 Node.js 버전 지정 (프로젝트에 맞게 변경)

      - name: Install Dependencies
        run: npm ci # 프로젝트 의존성 설치 (npm install 대신 ci를 사용하여 더 안정적)

      - name: Build Project
        run: npm run build # 프로젝트 빌드 명령 실행 (package.json의 "build" 스크립트)

      - name: Deploy to Vercel
        run: |
          echo "VERCEL_ORG_ID=${{ secrets.VERCEL_ORG_ID }}" >> .env
          echo "VERCEL_PROJECT_ID=${{ secrets.VERCEL_PROJECT_ID }}" >> .env
          npx vercel deploy --prod --token=${{ secrets.VERCEL_TOKEN }}
        env:
          VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
          VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}
          VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}
        # Vercel CLI가 VERCEL_ORG_ID와 VERCEL_PROJECT_ID를 환경 변수로 인식하도록 설정
        # --prod 플래그는 프로덕션 환경으로 배포하도록 지시
        # --token은 Vercel API 토큰을 사용하여 인증

YAML 파일 설명:

name: Deploy to Vercel: 워크플로우의 이름을 정의합니다. GitHub Actions 탭에서 이 이름으로 워크플로우를 식별할 수 있습니다.
on: 워크플로우가 언제 실행될지 정의합니다.
- push: main 브랜치에 코드가 푸시될 때 실행됩니다. 이는 최종 프로덕션 배포를 담당합니다.
- pull_request: main 브랜치로 Pull Request가 생성될 때 실행됩니다. Vercel은 PR에 대한 Preview Deployment를 자동으로 생성하므로, 이 단계에서는 주로 빌드 및 테스트를 수행하고 Vercel의 기본 PR 배포 기능을 활용합니다. (위 YAML에서는 deploy 잡이 실행되므로, 실제로는 Vercel의 PR 배포와 별개로 Actions를 통해 한 번 더 배포 시도를 할 수 있습니다. Vercel의 기본 PR 배포를 사용하려면 pull_request 트리거에서 deploy 잡을 제외하거나 다른 잡을 실행하도록 구성할 수 있습니다.) 이 가이드에서는 push를 통한 최종 배포에 집중합니다.
jobs: 워크플로우 내에서 실행될 작업(job)들을 정의합니다.
- deploy: 배포 작업을 정의합니다.
  - runs-on: ubuntu-latest: 이 작업이 실행될 가상 환경을 지정합니다. ubuntu-latest는 최신 Ubuntu 환경을 의미합니다.
  - steps: deploy 작업 내에서 순차적으로 실행될 단계들을 정의합니다.
    - Checkout Repository: actions/checkout@v4 액션을 사용하여 GitHub 리포지토리의 코드를 워크플로우 환경으로 가져옵니다.
    - Setup Node.js: actions/setup-node@v4 액션을 사용하여 Node.js 환경을 설정합니다. node-version을 프로젝트에 맞는 버전으로 지정합니다 (예: 20).
    - Install Dependencies: npm ci 명령어를 실행하여 프로젝트의 의존성을 설치합니다. npm install 대신 npm ci를 사용하는 것이 CI 환경에서는 더 안정적이고 빠릅니다. (package-lock.json을 기반으로 설치)
    - Build Project: npm run build 명령어를 실행하여 프로젝트를 빌드합니다. package.json 파일에 scripts: { "build": "next build" }와 같은 빌드 스크립트가 정의되어 있어야 합니다.
    - Deploy to Vercel: Vercel CLI를 사용하여 Vercel에 프로젝트를 배포하는 핵심 단계입니다.
      - echo "VERCEL_ORG_ID=${{ secrets.VERCEL_ORG_ID }}" >> .env
      - echo "VERCEL_PROJECT_ID=${{ secrets.VERCEL_PROJECT_ID }}" >> .env
      - 이 두 줄은 Vercel CLI가 프로젝트와 조직을 식별하는 데 필요한 ID를 .env 파일에 작성하여 환경 변수로 제공합니다. .env 파일이 없는 경우 생성되고, 있다면 추가됩니다.
      - npx vercel deploy --prod --token=${{ secrets.VERCEL_TOKEN }}:
        
        npx vercel deploy: Vercel CLI를 사용하여 배포를 시작합니다. npx는 로컬에 설치되지 않은 패키지의 CLI를 실행할 때 유용합니다.
        
        --prod: 이 배포가 프로덕션 환경으로 간주되도록 합니다. 즉, 프로젝트의 메인 도메인에 연결됩니다.
        
        --token=${{ secrets.VERCEL_TOKEN }}: 이전에 GitHub Secrets에 저장한 Vercel API 토큰을 사용하여 Vercel에 인증합니다. GitHub Actions는 secrets 컨텍스트를 통해 Secret 값에 접근할 수 있습니다.
      - env: VERCEL_ORG_ID, VERCEL_PROJECT_ID, VERCEL_TOKEN을 환경 변수로 명시적으로 설정하여 Vercel CLI가 인식하도록 합니다.

5. 환경 변수 관리

프론트엔드 프로젝트에서는 API 키, 데이터베이스 URL 등 다양한 환경 변수를 사용합니다. Vercel과 GitHub Actions 환경에서 이러한 변수들을 안전하고 효율적으로 관리하는 방법을 이해하는 것이 중요합니다.

5.1. Vercel 대시보드 환경 변수 설정

Vercel은 프로젝트별로 환경 변수를 설정할 수 있는 기능을 제공합니다. 이는 주로 프론트엔드 코드(클라이언트 사이드 또는 서버 사이드 렌더링 시)에서 직접 사용되는 변수들을 관리하는 데 적합합니다.

Vercel 대시보드에서 해당 프로젝트를 클릭합니다.
Settings 탭으로 이동합니다.
좌측 메뉴에서 Environment Variables를 선택합니다.
Add New 버튼을 클릭하여 Name과 Value를 입력합니다.
Environments 섹션에서 이 변수가 적용될 환경(Development, Preview, Production)을 선택합니다.
- Development: vercel dev 명령으로 로컬 개발 시 사용됩니다.
- Preview: Pull Request 등 미리보기 배포 시 사용됩니다.
- Production: main 브랜치 푸시 등으로 최종 배포 시 사용됩니다.

이러한 변수들은 Vercel이 빌드 및 런타임 시 자동으로 주입해줍니다. 예를 들어 Next.js 프로젝트에서는 NEXT_PUBLIC_ 접두사를 붙여 클라이언트 사이드 코드에서도 접근할 수 있도록 할 수 있습니다.

javascript

// Next.js 예시 (클라이언트/서버 모두 접근 가능)
const apiKey = process.env.NEXT_PUBLIC_API_KEY;

5.2. GitHub Actions Secrets 활용

GitHub Actions Secrets는 Vercel API 토큰처럼 민감하고 외부에 노출되어서는 안 되는 정보를 저장하는 데 최적화되어 있습니다. 이 변수들은 GitHub Actions 워크플로우 내에서만 접근 가능하며, Vercel 배포 환경으로 직접 전달되지는 않습니다 (단, VERCEL_TOKEN처럼 Vercel CLI에 인수로 전달하는 경우는 예외).

주요 사용 사례:

Vercel API 토큰 (VERCEL_TOKEN)
다른 외부 서비스의 API 키 (예: 테스트 단계에서만 필요한 경우)
빌드 또는 테스트 스크립트에서만 필요한 민감 정보

5.3. 환경 변수 관리 전략 비교

특징/용도	Vercel 대시보드 환경 변수	GitHub Actions Secrets
주요 용도	Vercel 배포된 앱에서 직접 사용되는 변수 (API 키, DB URL 등)	GitHub Actions 워크플로우 내에서 사용되는 민감 정보 (API 토큰 등)
접근 주체	Vercel 빌드/런타임 환경, 배포된 애플리케이션	GitHub Actions 워크플로우 스텝
보안 수준	높음 (대시보드에서 관리, UI로 노출)	매우 높음 (암호화되어 저장, UI로 노출되지 않음)
적용 환경	Development, Preview, Production (Vercel 환경)	GitHub Actions 실행 환경
예시	`NEXT_PUBLIC_API_URL`, `DATABASE_URL`	`VERCEL_TOKEN`, `SLACK_WEBHOOK_URL`
코드 노출 여부	`NEXT_PUBLIC_` 접두사 사용 시 클라이언트 코드에서도 접근 가능	워크플로우 로그에 노출되지 않도록 주의 필요

대부분의 프론트엔드 관련 환경 변수는 Vercel 대시보드에서 관리하는 것이 간편하고 효과적입니다. GitHub Actions Secrets는 Vercel 배포 자체에 필요한 인증 정보나 Actions 내부에서만 사용될 민감 정보를 관리하는 데 활용합니다.

6. CI/CD 테스트 및 디버깅

이제 워크플로우 파일을 GitHub 리포지토리에 푸시하여 자동 배포가 제대로 작동하는지 확인하고, 문제가 발생했을 때 디버깅하는 방법을 알아봅니다.

6.1. 워크플로우 실행 확인

**Git

Vercel + GitHub Actions CI/CD 자동 배포 세팅 완전 가이드

Vercel + GitHub Actions CI/CD 자동 배포 세팅 완전 가이드

1. CI/CD란 무엇인가요? 왜 중요할까요?

1.1. CI (Continuous Integration): 지속적인 통합

1.2. CD (Continuous Delivery/Deployment): 지속적인 제공/배포

1.3. CI/CD의 핵심 이점

2. Vercel과 GitHub Actions, 왜 함께 사용해야 할까요?

2.1. Vercel의 강점

2.2. GitHub Actions의 강점

2.3. Vercel과 GitHub Actions의 시너지 효과

3. 프로젝트 준비하기

3.1. Vercel 프로젝트 생성 및 GitHub 연동

3.2. GitHub 리포지토리 준비

4. GitHub Actions 워크플로우 설정

4.1. Vercel API 토큰 발급 및 GitHub Secrets 설정

4.2. 워크플로우 YAML 파일 작성 상세 가이드

5. 환경 변수 관리

5.1. Vercel 대시보드 환경 변수 설정

5.2. GitHub Actions Secrets 활용

5.3. 환경 변수 관리 전략 비교

6. CI/CD 테스트 및 디버깅

6.1. 워크플로우 실행 확인

AI 서비스나 플랫폼 개발을고민 중이신가요?

AI 서비스나 플랫폼 개발을
고민 중이신가요?