GitHub Pages 배포 오류 문제

Mar 9, 2025 by ADMIN 22 views

GitHub Pages는 GitHub에서 제공하는 정적 웹사이트 호스팅 서비스입니다. GitHub Actions를 사용하여 GitHub Pages에 정적 웹사이트를 배포하려고 할 때 지속적으로 오류가 발생했습니다. 이 글에서는 GitHub Pages 배포 오류 문제를 해결하는 방법을 설명합니다.

문제 상황

GitHub Actions를 사용하여 GitHub Pages에 정적 웹사이트를 배포하려고 할 때 지속적으로 다음 오류가 발생했습니다:

Error: No uploaded artifact was found! Please check if there are any errors at build step, or uploaded artifact name is correct.

빌드 자체는 성공적으로 완료되었고, 아티팩트를 다운로드하여 로컬에서 python -m http.server 8000으로 테스트했을 때 http://localhost:8000/index.html로 정상 접속이 가능했으나, GitHub Pages에 배포 단계에서만 문제가 발생했습니다.

시도한 해결 방법들

시도 1: 기본 워크플로우 사용

초기에는 다음과 같은 구조의 워크플로우를 사용했습니다:

단일 작업(build_and_deploy)에서 모든 단계 수행
actions/upload-artifact@v4를 사용하여 아티팩트 업로드
배포 전에 아티팩트를 다시, 다운로드하여 확인하는 단계 포함

시도 2: 명시적인 아티팩트 이름 지정

name: github-pages와 artifact_name: github-pages를 명시적으로 지정하여 아티팩트 이름을 맞추려고 시도했습니다.

시도 3: 작업 분리 및 tar 압축 사용

빌드와 배포를 별도 작업으로 분리
dist 디렉토리를 tar로 압축하여 아티팩트로 업로드
배포 전에 압축을 풀어서 사용

시도 4: _site 디렉토리 사용

빌드 결과물을 _site 디렉토리로 복사하여 GitHub Pages의 기본 디렉토리 구조를 맞추려고 시도했습니다.

해결 방법

최종적으로 GitHub Pages의 공식 워크플로우 패턴을 따르는 접근 방식이 문제를 해결했습니다:

name: Deploy to GitHub Pages

on:
  push:
    branches: ["main"]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Set up Node
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      - name: Create env file
        run: |
          echo "VITE_APP_API_URL=${{ secrets.VITE_APP_API_URL }}" > .env.production
          echo "NODE_ENV=production" >> .env.production
      - name: Install dependencies
        run: npm ci
      - name: Build
        run: npm run build
        env:
          VITE_APP_API_URL: ${{ secrets.VITE_APP_API_URL }}
      - name: Add CNAME file
        run: echo 'blu2print.site' > ./dist/CNAME
      - name: Setup Pages
        uses: actions/configure-pages@v4
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: './dist'

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

핵심 해결 포인트

작업 분리: 빌드와 배포를 별도 작업으로 분리
액션 버전 일관성: 모든 GitHub Pages 관련 액션의 최신 호환 버전 사용
- actions/configure-pages@v4
- actions/upload-pages-artifact@v3
- actions/deploy-pages@v4
필수 단계 순서:
- configure-pages → upload-pages-artifact → deploy-pages 순서 준수
환경 설정: environment 블록에서 올바르게 github-pages 환경 참조

교훈

GitHub Pages 배포에는 일반 아티팩트(upload-artifact) 대신 Pages 전용 아티팩트(upload-pages-artifact)를 사용해야 합니다.
빌드와 배포는 별도의 작업으로 분리하는 것이 권장됩니다.
액션 버전 간의 호환성이 중요합니다 - GitHub의 공식 패턴을 따르는 것이 좋습니다.
불필요한 디버깅 단계는 오히려 워크플로우를 복잡하게 만들 수 있습니다.

이 문제를 해결하는 데 도움이 되었던 주요 참고 자료는 [GitHub Pages 공식 배포 가이드](https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#publishing-with-a-custom-github-actions-workflow)입니다.

이 글에서는 GitHub Pages 배포 오류 문제를 해결하는 방법에 대한 FAQ를 제공합니다.

Q: GitHub Pages 배포 오류가 발생하는 이유는 무엇입니까?

A: GitHub Pages 배포 오류는 다양한 이유로 발생할 수 있습니다. 빌드 단계에서 오류가 발생하거나, 아티팩트를 올바르게 업로드하지 못하는 경우, GitHub Pages의 공식 워크플로우 패턴을 따르지 않는 경우 등이 있습니다.

Q: 빌드 단계에서 오류가 발생하는 경우 어떻게 해야 합니까?

A: 빌드 단계에서 오류가 발생하는 경우, 빌드 로그를 확인하여 오류의 원인을 파악해야 합니다. 빌드 로그를 확인하여 오류의 원인을 파악한 후, 오류를 해결하는 방법을 찾아야 합니다.

Q: 아티팩트를 올바르게 업로드하는 방법은 무엇입니까?

A: 아티팩트를 올바르게 업로드하는 방법은 GitHub Pages의 공식 워크플로우 패턴을 따르는 것입니다. actions/upload-pages-artifact@v3를 사용하여 아티팩트를 업로드해야 합니다.

Q: GitHub Pages의 공식 워크플로우 패턴을 따르는 방법은 무엇입니까?

A: GitHub Pages의 공식 워크플로우 패턴을 따르는 방법은 다음과 같습니다.

actions/configure-pages@v4를 사용하여 Pages를 설정합니다.
actions/upload-pages-artifact@v3를 사용하여 아티팩트를 업로드합니다.
actions/deploy-pages@v4를 사용하여 Pages를 배포합니다.

Q: 빌드와 배포를 별도 작업으로 분리하는 방법은 무엇입니까?

A: 빌드와 배포를 별도 작업으로 분리하는 방법은 다음과 같습니다.

빌드 작업을 build로 이름을 지어줍니다.
배포 작업을 deploy로 이름을 지어줍니다.
build 작업이 완료된 후, deploy 작업을 시작합니다.

Q: 액션 버전 간의 호환성이 중요합니까?

A: 액션 버전 간의 호환성이 중요합니다. GitHub Pages의 공식 워크플로우 패턴을 따르는 경우, 최신 호환 버전의 액션을 사용해야 합니다.

Q: 불필요한 디버깅 단계는 오히려 워크플로우를 복잡하게 만들 수 있습니다.

A: 불필요한 디버깅 단계는 오히려 워크플로우를 복잡하게 만들 수 있습니다. 워크플로우를 단순화하기 위해 불필요한 디버깅 단계를 제거해야 합니다.