[KB_최종 프로젝트 CI/CD] GitHub Actions를 통한 Vue.js 프로젝트 자동 배포

JUN·2024년 10월 6일

GithubAction KBIT’sYourLife KB국민은행 TIL 멀티캠퍼스 채용우대교육

KB IT's your life

목록 보기

12/16

서론

Vue.js 애플리케이션을 자동으로 배포하는 방법을 소개하고자 한다.

수동으로 진행하던 배포 작업을 GitHub Actions를 통해 자동화하고 pages를 통해 배포하여, 코드를 푸시하기만 하면 빌드와 배포가 자동으로 진행되도록 설정할 수 있다.

이번 글에서는 Vite를 사용한 Vue.js 애플리케이션을 GitHub Pages로 자동 배포하는 방법을 설명하겠다.

1. 기본 세팅

GitHub 저장소 생성

먼저, Vue 프로젝트를 위한 GitHub 저장소를 생성해야 한다. 이 저장소는 코드와 자동화 스크립트를 저장하는 공간으로 사용된다.

필수 도구 설치

배포 자동화를 위해 다음과 같은 도구들이 필요하다. npm을 사용하여 설치할 수 있다. 물론 yarn을 사용해도 상관없다.

Node.js (20 버전 이상)
Vite

Vue 프로젝트 생성 (기존 프로젝트가 없을 경우)

터미널을 열고 다음 명령어를 실행하여 Vite로 Vue 프로젝트를 생성한다:

npm create vite@latest

생성 과정에서 지시에 따라 프로젝트를 설정한 후, 프로젝트 디렉터리로 이동한다.

필요한 패키지를 설치한다:

npm install

개발 서버를 시작하여 제대로 작동하는지 확인한다:

npm run dev

2. Vite 설정

이제 프로젝트가 생성되었으니, 배포를 위해 vite.config.js 파일을 수정해야 한다. 이 파일에서는 배포 경로와 별칭(alias)을 설정할 수 있다.

import { fileURLToPath, URL } from "node:url";

import { defineConfig } from "vite";
import vue from "@vitejs/plugin-vue";

// https://vitejs.dev/config/
export default defineConfig({
	base: "/{자신의 레포지토리 이름}/",
	plugins: [vue()],
	resolve: {
		alias: {
			"@": fileURLToPath(new URL("./src", import.meta.url)),
		},
	},
});

Base 경로: base 옵션은 GitHub Pages에서 배포될 경로를 설정하는 것으로, 저장소 이름과 일치해야 한다.

나같은 경우 /metal-wallet-frontend/ 로 base 를 설정해두었다.

base를 /metal-wallet-frontend/로 설정해야 하는 이유는 GitHub Pages에서 프로젝트가 호스팅될 때 해당 저장소 이름이 URL의 일부가 되기 때문이다.

GitHub Pages는 기본적으로 https://사용자이름.github.io/**저장소이름**/ 형식의 URL을 사용한다.

따라서 Vite 설정에서 base 옵션을 저장소 이름과 일치시켜야, 빌드된 애플리케이션의 자산(CSS, JavaScript 등)이 올바른 경로에서 로드될 수 있다.

3. GitHub Actions로 자동 배포 설정

GitHub Actions를 이용하여 배포 작업을 자동화할 수 있다. 이제 deploy.yml 파일을 생성하여, 코드를 main 브랜치에 푸시할 때마다 자동으로 빌드와 배포가 이루어지도록 설정하겠다.

Workflow 파일 생성

프로젝트 디렉터리에서 .github/workflows/ 폴더를 생성한 뒤, deploy.yml 파일을 생성한다.

name: Deploy # Workflow 이름

on: # main 브랜치에 푸시할 때 트리거됨
  push:
    branches:
      - main

jobs:
  build: # 첫 번째 작업: 빌드
    name: Build
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repo # 저장소 체크아웃
        uses: actions/checkout@v4

      - name: Setup Node # Node.js 설치
        uses: actions/setup-node@v4
        with:
          node-version: "20"

      - name: Install dependencies # 패키지 설치
        run: npm install

      - name: Print working directory # 현재 작업 디렉토리 출력
        run: pwd

      - name: List project files before build # 빌드 전 파일 구조 확인
        run: ls -al

      - name: Build project # 프로젝트 빌드
        run: npm run build

      - name: List build files # 빌드 후 파일 확인
        run: ls -al ./dist

      - name: Upload production-ready build files # 빌드된 파일 업로드
        uses: actions/upload-artifact@v4
        with:
          name: production-files
          path: ./dist

  deploy: # 두 번째 작업: 배포
    name: Deploy
    needs: build # build 작업이 완료되어야 실행됨
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main' # 브랜치 확인

    steps:
      - name: Download artifact # 빌드된 파일 다운로드
        uses: actions/download-artifact@v4
        with:
          name: production-files
          path: ./dist

      - name: Deploy to GitHub Pages # GitHub Pages로 배포
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./dist

설명

Workflow 설정 설명

GitHub Actions를 통해 저장소에 푸시가 되면 자동으로 빌드 및 배포가 진행된다. 이 과정에서 .github/workflows/ 디렉토리에 deploy.yml 파일을 생성하여 설정한다.

1. 이름 및 트리거 설정

name: Deploy # Workflow 이름

on: # main 브랜치에 푸시할 때 트리거됨
  push:
    branches:
      - main

name: Deploy: 워크플로우의 이름을 “Deploy”로 지정한다.
on: 특정 이벤트에 따라 워크플로우가 실행되도록 트리거를 설정한다. 여기서는 push 이벤트로 main 브랜치에 푸시할 때마다 워크플로우가 실행된다.

2. 빌드 작업

jobs:
  build: # 첫 번째 작업: 빌드
    name: Build
    runs-on: ubuntu-latest

jobs: 워크플로우에서 실행할 작업 목록을 정의한다. build는 첫 번째 작업으로 애플리케이션을 빌드한다.
runs-on: Ubuntu 최신 버전의 가상 환경에서 작업이 실행된다.

steps:
  - name: Checkout repo # 저장소 체크아웃
    uses: actions/checkout@v4

Checkout repo: GitHub Actions가 저장소를 체크아웃하여 코드를 가져오는 단계이다. actions/checkout@v4를 사용하여 저장소를 다운로드한다.

  - name: Setup Node # Node.js 설치
    uses: actions/setup-node@v4
    with:
      node-version: "20"

Setup Node: Node.js 20 버전을 설치한다. 프로젝트 빌드와 패키지 설치를 위해 필요하다.

  - name: Install dependencies # 패키지 설치
    run: npm install

Install dependencies: npm install을 통해 프로젝트의 의존성을 설치한다.

  - name: List project files before build # 빌드 전 파일 구조 확인
    run: ls -al

List project files before build: 빌드 전에 파일 구조를 확인한다.

  - name: Build project # 프로젝트 빌드
    run: npm run build
  - name: List build files # 빌드 후 파일 확인
    run: ls -al ./dist

Build project: npm run build 명령어로 프로젝트를 빌드한다. 빌드된 파일은 dist 폴더에 생성된다.

  - name: Upload production-ready build files # 빌드된 파일 업로드
    uses: actions/upload-artifact@v4
    with:
      name: production-files
      path: ./dist

Upload production-ready build files: 빌드된 파일을 artifact로 업로드하여 다음 단계에서 사용할 수 있도록 한다.

3. 배포 작업

  deploy: # 두 번째 작업: 배포
    name: Deploy
    needs: build # build 작업이 완료되어야 실행됨
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main' # 브랜치 확인

deploy: 배포 작업을 정의한다.
needs: build: 이 작업은 빌드 작업이 완료된 후에 실행된다.
if: github.ref == 'refs/heads/main': main 브랜치에서만 배포 작업이 실행되도록 조건을 설정한다.

  - name: Download artifact # 빌드된 파일 다운로드
    uses: actions/download-artifact@v4
    with:
      name: production-files
      path: ./dist

Download artifact: 빌드된 파일을 다운로드하여 dist 폴더에 저장한다.

  - name: Deploy to GitHub Pages # GitHub Pages로 배포
    uses: peaceiris/actions-gh-pages@v4
    with:
      github_token: ${{ secrets.GITHUB_TOKEN }}
      publish_dir: ./dist