Logo

GitHub Actions로 빌드 후 GitHub Pages에 배포하기

지난 포스팅에서는 저장소의 특정 브랜치를 배포 디렉토리로 지정하여 아주 쉽고 빠르게 GitHub Pages로 웹사이트를 호스팅할 수 있다고 배웠는데요. 하지만 요즘 웹 개발에서 HTML, CSS, JavaScript를 직접 작성하는 일은 드물죠? 대부분 React와 같은 프론트엔드 라이브러리와 Vite와 같은 빌드 도구를 사용하여 HTML, CSS, JavaScript를 생성해낼 것입니다.

이번 포스팅에서는 웹 프로젝트를 GitHub Actions를 사용하여 빌드하고, 빌드 결과물을 바로 GitHub Pages에 배포하는 방법에 대해서 알아보겠습니다.

GitHub Pages 설정

우선 GitHub Actions을 통해서 웹사이트가 빌드 후에 배포될 수 있도록 GitHub Pages를 설정을 해줘야 합니다.

저장소 화면의 Settings 탭에 들어가서 좌측 사이드 메뉴에서 Pages를 클릭합니다. 그 다음 Source 항목을 GitHub Actions로 설정합니다.

GitHub Pages 설정

Vite로 React 프로젝트 생성

차세대 빌드 도구인 Vite로 간단한 React 프로젝트를 생성해보겠습니다.

터미널에서 npm 명령어를 사용하여 저장소 최상위 디렉토리에서 Vite 프로젝트를 시작합니다. 프레임워크로는 React를 선택하고, 변형(variant)로는 JavaScript를 선택하겠습니다.

> npm create vite@latest ./
Need to install the following packages:
create-vite@6.1.1
Ok to proceed? (y) y


> npx
> create-vite ./

✔ Current directory is not empty. Please choose how to proceed: › Ignore files and continue
✔ Select a framework: › React
✔ Select a variant: › JavaScript

Scaffolding project in /workspaces/github-pages...

Done. Now run:

  npm install
  npm run dev

다양한 자바스크립트 프로젝트 생성법에 대해서는 별도 포스팅에서 자세히 다루고 있으니 참고 바랍니다.

터미널에서 시키는데로 의존 패키지를 설치하고 개발 서버를 구동해보겠습니다. http://localhost:5173으로 접속하면 웹사이트가 열릴 것입니다. 프로젝트의 코드를 수정하시면 변경 사항이 웹사이트에 즉시 반영이 될 거에요.

$ npm install
$ npm run dev

이번에는 프로젝트를 빌드도 해보고 상용 모드로 구동도 해보겠습니다. dist 폴더 안에 빌드 결과물이 생성된 것을 확인할 수 있을 거에요. http://localhost:4173으로 접속하면 웹사이트가 열릴 것입니다.

$ npm run build
$ npm run preview

모든 잘 작동하면 프로젝트 코드를 커밋 후 저장소에 올립니다.

$ git add .
$ git commit -m "Init Vite React"
$ git push

GitHub Actions 워크플로우 작성

저장소에 새로운 코드가 올라올 때 마다 프로젝트를 빌드하고 웹사이트를 배포하기 위해서는 GitHub Actions 워크플로우가 필요합니다.

우선 on 항목을 통해서 main 브랜치에 코드가 올라올 때만 워크프로우가 실행되도록 합니다. 그 다음 빌드와 배포를 위한 두 개의 작업을 정의합니다.

.github/workflows/ci.yml
name: CI

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm run build
      - uses: actions/configure-pages@v5
      - uses: actions/upload-pages-artifact@v3
        with:
          path: "./dist"

  deploy:
    needs: build
    permissions:
      pages: write
      id-token: write
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - uses: actions/deploy-pages@v4
        id: deployment

build 작업에는 아래 작업으로 이루어집니다.

  • 저장소의 코드를 CI 서버로 내려받습니다.
  • 의존 패키지를 설치합니다.
  • Vite로 프로젝트를 빌드합니다.
  • GitHub Pages를 설정합니다.
  • dist 폴더에 생성된 빌드 결과물을 Artifact로 업로드합니다.

deploy 작업에는 아래 작업으로 이루어집니다.

  • Artifact로 업로드한 빌드 결과물을 GitHub Pages에 배포합니다.

반드시 빌드가 끝나고 배포가 시작될 수 있도록 deploy 작업에 needs: build 항목을 설정해줍니다. permissions 항목에는 GitHub Pages에 배포하는데 필요한 권한을 명시합니다.

위 워크플로우를 제대로 이해하려면 GitHub Actions에 대한 사전 지식이 필요합니다. 관련 내용은 아래 포스팅에서 자세히 다루고 있으니 참고바랍니다.

Vite 추가 설정

커스텀 도메인을 사용하지 않고 GitHub Pages에서 무료로 제공하는 기본 도메인을 사용할 경우 배포한 웹사이트가 하얀 공백으로 뜨는 문제를 흔히 겪게 되는데요. 이러한 문제가 발생하는 이유는 github.io 무료 도메인을 사용할 경우 URL 맨 뒤에 저장소명이 경로로 붙기 때문입니다.

Vite 추가 설정

이 문제는 Vite의 base 항목을 /저장소명/으로 설정해주면 해결될 것입니다.

vite.config.js
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";

// https://vite.dev/config/
export default defineConfig({
  plugins: [react()],
  base: "/github-pages/",});

마치면서

이상으로 간단한 실습을 통해 GitHub Actions로 빌드한 웹사이트를 어떻게 GitHub Pages에 배포하는지 알아보았습니다. GitHub의 CI 서비스인 GitHub Actions와 GitHub의 호스팅 서비스인 GitHub Pages를 함께 사용하면 강력한 시너지가 발휘됩니다. GitHub에서 제공하는 이 2가지 무료 서비스만 잘 활용하시면 개인 사이드 프로젝트를 효과적으로 빌드 및 배포하실 수 있으실 거라 생각합니다.

GitHub Pages 관련 포스팅은 GitHub Pages 태그를 통해서 쉽게 만나보세요!

This work is licensed under CC BY 4.0

messageCircle