← 목록으로 돌아가기
Tech

GitHub Actions로 외부 프로젝트 통합 배포하기

Repository 바로가기 ↗
2026년 1월 20일

GitHub Actions을 활용해 외부 프로젝트를 가져와 빌드하고 통합하는 방법을 알아봅니다.

개요

  1. 블로그 빌드 과정 중에 외부 GitHub 저장소의 프로젝트를 가져오는 방법
  2. sed 명령어로 빌드 설정을 동적으로 수정하여 서브 경로(basePath) 문제 해결하기
  3. 하나의 GitHub Pages 사이트에 여러 프로젝트를 통합하여 배포하는 파이프라인 구축

배경

개인 블로그를 운영하다 보면, 별도로 개발한 토이 프로젝트나 데모를 블로그의 하위 경로에서 보여주고 싶을 때가 있습니다.
단순한 방법은 프로젝트 코드를 블로그 저장소에 직접 포함시키는 것이지만, 이는 저장소를 무겁게 만들고 프로젝트 관리를 복잡하게 합니다.
대신 GitHub Actions를 사용하면 배포 시점에만 외부 프로젝트를 가져와 빌드하고 합칠 수 있어 훨씬 깔끔하게 관리할 수 있습니다.

GitHub Actions 워크플로우 구성

기존 블로그 배포 워크플로우(deploy.yml)에 외부 프로젝트를 처리하는 단계를 추가합니다.

1. 전체 흐름

  1. 메인 블로그 빌드: 먼저 블로그(Next.js)를 빌드하여 out/ 폴더를 생성합니다.
  2. 외부 프로젝트 체크아웃: actions/checkout을 사용해 외부 저장소를 임시 폴더로 가져옵니다.
  3. 설정 주입 및 빌드: 외부 프로젝트가 서브 경로에서 동작하도록 설정을 수정하고 빌드합니다.
  4. 결과물 통합: 빌드된 외부 프로젝트 결과물을 블로그의 out/projects/... 경로로 복사합니다.

2. 워크플로우 예시

아래는 3d-fireworks-simulation이라는 외부 프로젝트를 /projects/3d-fireworks-simulation 경로에 배포하는 설정입니다.

# .github/workflows/deploy.yml

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      # ... (기존 블로그 빌드 단계) ...

      # (선택) 필요한 도구 설치
      - name: Install wasm-pack
        run: curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh

      # 외부 프로젝트 가져오기
      - name: Checkout external project
        uses: actions/checkout@v4
        with:
          repository: kimseongyu/3d-fireworks-simulation
          path: temp-fireworks

      # 외부 프로젝트 설정 수정 및 빌드
      - name: Build external project
        run: |
          cd temp-fireworks

          # 중요: 정적 내보내기 및 basePath 설정을 동적으로 주입
          sed -i "s/const nextConfig: NextConfig = {/const nextConfig: NextConfig = { output: 'export', basePath: '\/projects\/3d-fireworks-simulation',/" next.config.ts

          npm ci
          npm run build

          # 빌드 결과물을 메인 블로그의 출력 폴더로 이동
          mkdir -p ../out/projects/3d-fireworks-simulation
          cp -r out/* ../out/projects/3d-fireworks-simulation/

3. 핵심 포인트: 동적 설정 주입 (sed)

외부 프로젝트는 보통 루트 경로(/)에서 실행되도록 설정되어 있습니다. 이를 블로그의 하위 경로에서 실행하려면 basePath 설정이 필요합니다.

소스 코드를 직접 수정하지 않고, 배포 시점에 sed 명령어를 사용해 next.config.ts를 수정하는 방식이 유용합니다.

sed -i "s/찾을문자열/바꿀문자열/" 파일명

위 예시에서는 nextConfig 객체 선언부를 찾아 output: 'export'(정적 배포)와 basePath 설정을 강제로 추가했습니다.

장점

  1. 저장소 분리: 블로그와 프로젝트 저장소를 독립적으로 관리할 수 있습니다.
  2. 자동 동기화: 블로그를 배포할 때마다 외부 프로젝트의 최신 main 브랜치 내용을 가져옵니다.
  3. 유연성: sed 등을 활용해 배포 환경에 맞춰 설정을 자유롭게 변경할 수 있습니다.