바이브 코딩 결과물을 GitHub Pages와 Actions로 자동 배포하는 법

🚀 왜 자동 배포를 해야 할까요?

개발한 웹 프로젝트를 사용자에게 공개하는 과정은 반복적이고 번거로울 수 있습니다. 특히 바이브(Vibe) 코딩과 같이 정적 웹사이트를 생성하는 경우, 수동 배포는 시간 낭비와 오류 발생 가능성을 높입니다.

GitHub Pages는 이러한 정적 웹사이트를 무료로 호스팅할 수 있는 훌륭한 서비스입니다. 여기에 GitHub Actions를 결합하면 코드를 푸시할 때마다 자동으로 빌드하고 배포하는 CI/CD 파이프라인을 구축할 수 있습니다. 이는 개발 생산성을 극대화하고, 언제나 최신 버전을 유지하게 해줍니다.

자동 배포

🛠️ 시작하기 전에 필요한 것들

본 가이드를 따라하기 전에 다음 준비물이 필요합니다.

바이브 코딩 프로젝트: 배포할 HTML, CSS, JavaScript 등으로 구성된 정적 웹 결과물.
GitHub 계정 및 리포지토리: 프로젝트 코드를 저장하고 관리할 GitHub 리포지토리.
기본적인 Git 명령어 지식: git add, git commit, git push 등.

📁 Step 1: GitHub 리포지토리 준비

가장 먼저 바이브 코딩 결과물이 저장될 GitHub 리포지토리를 준비해야 합니다. 새 리포지토리를 만들거나 기존 리포지토리를 사용해도 좋습니다.

프로젝트의 모든 정적 파일(HTML, CSS, JS, 이미지 등)을 리포지토리에 푸시합니다. 일반적으로 main 브랜치에 푸시하는 것이 좋습니다.

git init
git add .
git commit -m "Initial Vibe project commit"
git branch -M main
git remote add origin https://github.com/your-username/your-repo.git
git push -u origin main

GitHub 리포지토리

⚙️ Step 2: GitHub Pages 설정

이제 GitHub Pages를 활성화하여 웹사이트를 호스팅할 준비를 합니다. 이 단계는 GitHub Actions가 배포할 위치를 지정하는 역할을 합니다.

GitHub 리포지토리로 이동합니다.
상단의 Settings (설정) 탭을 클릭합니다.
왼쪽 사이드바에서 Pages를 클릭합니다.
Build and deployment 섹션에서 Source를 GitHub Actions로 설정합니다. (만약 이 옵션이 보이지 않는다면, 걱정하지 마세요. 첫 GitHub Actions 워크플로우가 성공적으로 실행된 후 이 옵션이 자동으로 설정됩니다. 초기에는 Deploy from a branch를 선택하고 main 브랜치를 지정해도 무방합니다.)
Save (저장) 버튼을 클릭합니다.

이 설정이 완료되면 GitHub Pages URL이 생성됩니다 (예: https://your-username.github.io/your-repo/). 초기에는 404 에러가 발생할 수 있지만, Actions가 배포를 완료하면 정상적으로 작동합니다.

GitHub Pages 설정

🚀 Step 3: GitHub Actions 워크플로우 생성

이제 GitHub Actions를 설정하여 코드가 main 브랜치에 푸시될 때마다 자동으로 배포되도록 할 차례입니다.

H3: 워크플로우 파일 생성

리포지토리 루트에 .github/workflows 디렉토리를 생성하고 그 안에 deploy.yml 파일을 만듭니다. 이 파일이 GitHub Actions 워크플로우의 정의를 담고 있습니다.

your-repo/.github/workflows/deploy.yml

.github/
└── workflows/
    └── deploy.yml

워크플로우 파일

H3: 워크플로우 코드 작성

deploy.yml 파일에 다음 내용을 작성합니다. 이 워크플로우는 코드를 체크아웃하고, 빌드(필요한 경우), 그리고 GitHub Pages로 배포하는 과정을 자동화합니다.

name: Deploy Vibe Project to GitHub Pages

on:
  push:
    branches:
      - main # main 브랜치에 푸시될 때 워크플로우 실행

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: read # 리포지토리 내용 읽기 권한
      pages: write # GitHub Pages에 쓰기 권한 (배포)
      id-token: write # OpenID Connect 토큰 발급 권한 (보안)

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4 # 리포지토리 코드 체크아웃

      # 만약 Vibe 코딩 결과물이 `dist`나 `build` 폴더에 생성되는 빌드 과정을 거친다면,
      # 이 부분에 빌드 스텝을 추가해야 합니다. 예: npm install, npm run build
      # 간단한 정적 파일인 경우, 이 단계는 생략해도 무방합니다.
      # - name: Setup Node.js (Optional, if Vibe uses Node for build/packaging)
      #   uses: actions/setup-node@v4
      #   with:
      #     node-version: '18'
      # - name: Install dependencies
      #   run: npm install
      # - name: Build Vibe project
      #   run: npm run build

      - name: Upload Pages artifact
        uses: actions/upload-pages-artifact@v3 # Pages에 배포할 아티팩트 업로드
        with:
          # Vibe 코딩 결과물이 있는 디렉토리를 지정합니다.
          # 일반적으로 프로젝트의 루트 (./) 또는 빌드 결과물 폴더 (예: ./dist, ./public) 입니다.
          path: './' # 프로젝트 루트에 바로 배포 파일이 있다면 './' 로 지정

      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4 # GitHub Pages로 배포 실행

path: './' 부분은 중요합니다. Vibe 코딩 결과물이 리포지토리의 최상위 디렉토리에 바로 있다면 ./로 설정하고, 만약 dist나 public과 같은 특정 빌드 폴더에 결과물이 생성된다면 해당 폴더 경로로 변경해야 합니다 (예: path: './dist').

✅ Step 4: 워크플로우 테스트 및 배포 확인

deploy.yml 파일을 커밋하고 main 브랜치에 푸시합니다.

git add .github/workflows/deploy.yml
git commit -m "Add GitHub Actions for Pages deployment"
git push origin main

이제 GitHub 리포지토리의 Actions 탭으로 이동합니다. Deploy Vibe Project to GitHub Pages라는 이름의 워크플로우가 실행 중인 것을 볼 수 있습니다. 모든 단계가 초록색 체크 표시와 함께 성공하면 배포가 완료된 것입니다.

배포가 성공하면, Step 2에서 확인했던 GitHub Pages URL로 접속하여 바이브 코딩 결과물이 정상적으로 배포되었는지 확인합니다.

워크플로우 실행

🔍 문제 해결 팁 (Troubleshooting)

404 에러: GitHub Pages 설정에서 브랜치와 폴더가 올바르게 지정되었는지, 또는 Source가 GitHub Actions로 설정되었는지 확인하세요. Actions 워크플로우가 성공했는지도 중요합니다.
권한 문제: 워크플로우 YAML 파일의 permissions 섹션이 올바르게 설정되었는지 확인하세요 (pages: write, id-token: write).
아티팩트 경로: upload-pages-artifact 스텝의 path가 바이브 코딩 결과물이 실제로 있는 폴더를 정확히 가리키는지 확인하세요.

🏁 마치며

이제 바이브 코딩 결과물을 GitHub Pages에 GitHub Actions를 이용해 자동으로 배포하는 방법을 알아보았습니다. 이 자동화된 배포 파이프라인은 개발 시간을 절약하고, 배포 오류를 줄이며, 항상 최신 버전의 프로젝트를 쉽게 공유할 수 있도록 돕습니다.

한번 설정하면 개발에만 집중하고 배포는 GitHub Actions에 맡길 수 있습니다. 여러분의 프로젝트에 이 강력한 자동화 기능을 적극 활용해보세요!

인사이트 아카이브 랩