GitHub Actions로 자동 배포 설정하기, CI/CD 입문 가이드

코드를 push하면 알아서 배포된다면?

프로젝트를 수정하고, 빌드하고, 직접 서버에 올리는 과정을 매번 반복하고 있다면 이제 그 시간을 아낄 수 있습니다. GitHub Actions를 사용하면 코드를 push하는 것만으로 테스트부터 배포까지 자동으로 처리할 수 있습니다.

이 글에서는 CI/CD의 기본 개념부터 GitHub Actions 워크플로 작성법, 그리고 실제로 Vercel에 프론트엔드 프로젝트를 자동 배포하는 과정까지 단계별로 알아보겠습니다. CI/CD를 처음 접하는 분도 따라 할 수 있도록 구성했습니다.

CI/CD란 무엇인가요?

CI/CD는 소프트웨어 개발에서 반복되는 작업을 자동화하는 방법론입니다.

CI(Continuous Integration, 지속적 통합) 는 여러 개발자가 작성한 코드를 자주 합치고, 합칠 때마다 자동으로 빌드와 테스트를 실행하는 것을 말합니다. 코드에 문제가 있으면 합치는 시점에 바로 발견할 수 있으므로, 나중에 큰 충돌이 발생하는 것을 막아줍니다.

CD(Continuous Deployment/Delivery, 지속적 배포) 는 테스트를 통과한 코드를 자동으로 서버에 배포하는 것을 말합니다. 수동으로 FTP에 접속하거나 CLI를 실행할 필요 없이, 코드가 main 브랜치에 합쳐지는 순간 프로덕션까지 자동으로 반영됩니다.

구분	의미	자동화 대상
CI (지속적 통합)	코드 변경 시 자동 빌드 + 테스트	빌드, 린트, 단위 테스트
CD (지속적 배포)	테스트 통과 후 자동 배포	스테이징/프로덕션 서버 반영

정리하면, CI는 “코드가 잘 합쳐지는지 확인하는 과정”이고 CD는 “확인된 코드를 자동으로 사용자에게 전달하는 과정”입니다. 이 두 가지를 합쳐서 CI/CD 파이프라인이라고 부릅니다.

GitHub Actions는 어떤 도구인가요?

GitHub Actions는 GitHub에서 제공하는 CI/CD 자동화 도구입니다. 별도의 서버나 외부 서비스 없이, GitHub 저장소 안에서 워크플로(workflow)를 정의하면 코드 push, PR 생성 등의 이벤트가 발생할 때 자동으로 실행됩니다.

프론트엔드 개발자가 GitHub Actions를 선택하는 주된 이유는 다음과 같습니다.

첫째, 진입 장벽이 낮습니다. 이미 GitHub에 코드를 올리고 있다면 추가 설정 없이 바로 사용할 수 있습니다. Jenkins처럼 별도 서버를 구축할 필요가 없습니다.

둘째, 무료 사용량이 충분합니다. 퍼블릭 저장소에서는 표준 러너 사용이 무제한 무료이고, 프라이빗 저장소도 GitHub Free 플랜 기준 월 2,000분의 무료 실행 시간이 제공됩니다. 개인 프로젝트나 소규모 팀이라면 대부분 무료 범위 안에서 해결됩니다.

셋째, 마켓플레이스 생태계가 풍부합니다. actions/checkout, actions/setup-node 같은 공식 액션부터 Vercel, Netlify 배포 액션까지, 이미 만들어진 수천 개의 액션을 가져다 쓸 수 있습니다.

참고로, 2026년 1월부터 GitHub 호스팅 러너의 가격이 최대 39%까지 인하되었습니다. 또한 2026년 3월에는 예약 워크플로에서 시간대(timezone)를 직접 지정할 수 있는 기능도 추가되어, UTC 기준으로만 스케줄을 잡아야 했던 불편이 해소되었습니다.

워크플로 파일은 어떻게 구성되나요?

GitHub Actions의 워크플로는 저장소의 .github/workflows/ 폴더에 YAML 파일로 정의합니다. 핵심 구성 요소는 세 가지입니다.

Workflow(워크플로): 자동화의 최상위 단위입니다. 하나의 YAML 파일이 하나의 워크플로에 해당합니다.

Job(작업): 워크플로 안에서 실행되는 작업 단위입니다. 기본적으로 각 job은 독립된 가상 머신(러너)에서 병렬로 실행되며, 필요하면 순서를 지정할 수도 있습니다.

Step(단계): job 안에서 순서대로 실행되는 개별 명령입니다. 셸 명령어를 직접 쓰거나, 마켓플레이스의 액션을 가져와 사용합니다.

아래는 Node.js 프로젝트를 빌드하고 테스트하는 기본 워크플로 예시입니다.

yaml

name: CI

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

jobs:
  build-and-test:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Run lint
        run: npm run lint

      - name: Run tests
        run: npm test

      - name: Build
        run: npm run build

이 워크플로의 동작을 정리하면 다음과 같습니다.

• on: main 브랜치에 push하거나 PR을 열면 실행됩니다.
• runs-on: ubuntu-latest: GitHub에서 제공하는 최신 Ubuntu 가상 머신에서 실행됩니다.
• actions/checkout@v4: 저장소 코드를 가상 머신으로 복사합니다.
• actions/setup-node@v4: Node.js 20 버전을 설치하고, npm 캐시를 활용해 설치 속도를 높입니다.
• 이후 npm ci → lint → test → build 순서로 실행됩니다.

하지만 여기서 끝나면 CI만 구축한 것입니다. 빌드 결과물을 실제 서버에 올리는 CD 단계를 추가해야 자동 배포가 완성됩니다.

실전: Vercel 자동 배포 워크플로 만들기

이전 글 Vercel vs Netlify, 프론트엔드 무료 배포 플랫폼 어디가 더 좋을까?에서 두 플랫폼을 비교한 바 있습니다. 여기서는 Vercel을 예시로 GitHub Actions를 통한 자동 배포를 설정하겠습니다.

Vercel은 GitHub 저장소를 연결하면 자동 배포를 해주지만, GitHub Actions를 직접 구성하면 배포 전에 테스트를 실행하거나 빌드 캐시를 세밀하게 제어하는 등 파이프라인을 더 유연하게 관리할 수 있습니다.

1단계: Vercel 토큰과 프로젝트 정보 준비

먼저, Vercel 대시보드에서 배포에 필요한 세 가지 값을 확인합니다.

• VERCEL_TOKEN: Vercel 계정 Settings > Tokens에서 생성
• VERCEL_ORG_ID: 로컬에서 vercel link 실행 후 .vercel/project.json에서 확인
• VERCEL_PROJECT_ID: 같은 파일에서 확인

이 세 값을 GitHub 저장소의 Settings > Secrets and variables > Actions에서 Repository Secret으로 등록합니다. 토큰이나 ID를 워크플로 파일에 직접 쓰면 노출 위험이 있으므로, 반드시 Secrets를 통해 관리해야 합니다.

2단계: 배포 워크플로 작성

.github/workflows/deploy.yml 파일을 생성합니다.

yaml

name: Deploy to Vercel

env:
  VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
  VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}

on:
  push:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Run tests
        run: npm test

  deploy:
    needs: test
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Vercel CLI
        run: npm install --global vercel@latest

      - name: Pull Vercel environment
        run: vercel pull --yes --environment=production --token=${{ secrets.VERCEL_TOKEN }}

      - name: Build project
        run: vercel build --prod --token=${{ secrets.VERCEL_TOKEN }}

      - name: Deploy to Vercel
        run: vercel deploy --prebuilt --prod --token=${{ secrets.VERCEL_TOKEN }}

이 워크플로에는 두 개의 job이 있습니다. test job이 먼저 실행되고, 테스트가 통과해야만 deploy job이 실행됩니다(needs: test). 따라서 테스트에 실패하면 배포가 자동으로 차단됩니다.

이것이 바로 CI/CD의 핵심입니다. 테스트라는 안전장치를 거친 코드만 프로덕션에 반영되므로, 깨진 코드가 사용자에게 노출될 가능성이 크게 줄어듭니다.

3단계: PR 프리뷰 배포 추가 (선택)

PR마다 프리뷰 환경을 자동 생성하면 코드 리뷰 시 실제 동작을 확인할 수 있어 팀 협업에 유리합니다. 아래 워크플로를 별도 파일(예: preview.yml)로 추가하면 됩니다.

yaml

name: Preview Deployment

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  deploy-preview:
    runs-on: ubuntu-latest
    env:
      VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
      VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}
    steps:
      - uses: actions/checkout@v4

      - name: Install Vercel CLI
        run: npm install --global vercel@latest

      - name: Pull Vercel environment
        run: vercel pull --yes --environment=preview --token=${{ secrets.VERCEL_TOKEN }}

      - name: Build project
        run: vercel build --token=${{ secrets.VERCEL_TOKEN }}

      - name: Deploy preview
        run: vercel deploy --prebuilt --token=${{ secrets.VERCEL_TOKEN }}

프로덕션 배포와 달리 --prod 플래그가 없으므로, Vercel은 고유한 프리뷰 URL을 생성합니다. PR 코멘트에 이 URL을 남기면 리뷰어가 바로 확인할 수 있습니다.

GitHub Actions 비용은 얼마나 드나요?

개인 프로젝트나 소규모 팀이라면 대부분 무료로 사용할 수 있습니다.

플랜	월 무료 실행 시간	스토리지
GitHub Free	2,000분	500MB
GitHub Pro	3,000분	1GB
GitHub Team	3,000분	2GB
GitHub Enterprise	50,000분	50GB

퍼블릭 저장소에서 표준 러너를 사용하면 실행 시간 제한 없이 무료입니다. 일반적인 프론트엔드 프로젝트의 빌드와 테스트는 2~5분 정도 걸리므로, 프라이빗 저장소라도 하루 수 차례 배포하는 수준이면 무료 범위를 넘기기 어렵습니다.

다만, 2026년 3월부터 프라이빗 저장소의 셀프 호스팅 러너 사용 시 분당 $0.002의 플랫폼 요금이 추가되었다는 점은 참고할 필요가 있습니다. 개인 프로젝트 수준에서는 영향이 거의 없지만, 대규모 팀에서는 비용 계산이 필요합니다.

워크플로 작성 시 자주 하는 실수는?

GitHub Actions를 처음 설정할 때 자주 겪는 문제와 해결법을 정리합니다.

들여쓰기 오류: YAML은 들여쓰기에 민감합니다. 탭(Tab) 대신 반드시 스페이스 2칸을 사용하세요. VS Code에서 YAML 확장을 설치하면 문법 오류를 실시간으로 잡아줍니다.

Secrets 미등록: 워크플로에서 ${{ secrets.VERCEL_TOKEN }}을 참조했는데 실제로 등록하지 않으면 빈 문자열이 전달됩니다. Actions 탭에서 실행 로그를 확인하면 어느 단계에서 실패했는지 파악할 수 있습니다.

브랜치명 불일치: on.push.branches에 main으로 지정했는데 실제 기본 브랜치가 master이면 워크플로가 실행되지 않습니다. git branch -M main으로 브랜치명을 통일하거나, 워크플로 파일의 브랜치명을 수정하세요. 개발자가 꼭 알아야 할 Git 명령어 10가지에서 브랜치 관련 명령어를 더 자세히 다루고 있습니다.

npm ci vs npm install: CI 환경에서는 npm install 대신 npm ci를 사용하는 것이 좋습니다. npm ci는 package-lock.json을 기준으로 정확한 버전을 설치하므로 재현 가능한 빌드를 보장합니다.

다음 단계: 어디까지 확장할 수 있을까?

기본 CI/CD 파이프라인을 구축했다면, 다음 단계로 이런 것들을 고려해 볼 수 있습니다.

캐싱 최적화: actions/cache 또는 setup-node의 cache 옵션을 활용하면 node_modules 설치 시간을 절반 이상 줄일 수 있습니다. 빌드 도구의 캐시도 함께 관리하면 전체 파이프라인 속도가 눈에 띄게 개선됩니다. Vite vs Webpack 2026, 속도 차이가 얼마나 날까?에서 다룬 것처럼, 빌드 도구의 선택도 CI 속도에 직접적인 영향을 줍니다.

Lighthouse CI 연동: 배포할 때마다 자동으로 Lighthouse 점수를 측정하면 성능 저하를 조기에 발견할 수 있습니다.

매트릭스 전략: 여러 Node.js 버전이나 OS에서 동시에 테스트해야 할 때 strategy.matrix를 사용하면 하나의 워크플로 파일로 여러 환경을 커버할 수 있습니다.

환경별 분리 배포: 2026년 3월 업데이트로, GitHub Actions에서 환경(environment)을 배포 없이 사용할 수 있게 되었습니다. deployment: false 옵션을 설정하면 환경의 시크릿과 변수 관리 기능만 활용할 수 있어, 스테이징과 프로덕션의 설정을 더 유연하게 분리할 수 있습니다.

마무리

GitHub Actions는 프론트엔드 개발자가 가장 쉽게 시작할 수 있는 CI/CD 도구입니다. 코드를 push하면 테스트하고, 통과하면 배포하는 이 단순한 흐름만으로도 개발 프로세스의 안정성과 속도가 크게 달라집니다.

이 글에서 소개한 기본 워크플로를 자신의 프로젝트에 적용해 보세요. .github/workflows/ 폴더에 YAML 파일 하나를 추가하는 것만으로 시작할 수 있습니다. 처음에는 빌드와 테스트 자동화부터 시작하고, 익숙해지면 배포와 성능 모니터링까지 확장해 나가면 됩니다.

자주 묻는 질문 (FAQ)