GitHub Pages 배포 실패의 악몽에서 벗어나다: Jekyll 빌드 에러 완벽 해결법

나의 GitHub Pages 악몽기를 돌아보며

대학을 은퇴한 후 블로그를 시작하려던 나는 Jekyll과 GitHub Pages의 매력에 빠졌습니다. 무료 호스팅, 간단한 마크다운 문법, 버전 관리까지 가능하다니요. 하지만 현실은 녹록지 않았습니다. 처음 배포했을 때 “Failed to build site”라는 빨간 에러 메시지만 받아들였고, 원인을 찾는 데 무려 사흘이 걸렸습니다.

당시에는 왜 이렇게 어려웠을까요? 정보가 산발적이었고, 에러 메시지는 불친절했으며, GitHub Pages와 로컬 환경의 차이도 몰랐기 때문입니다. 하지만 지난 3년간 수십 번의 배포 실패를 거치면서 패턴을 발견했습니다. 그리고 이제는 어떤 에러가 나더라도 1시간 안에 해결할 수 있게 되었습니다.

가장 흔한 3가지 빌드 에러와 해결책

Ruby 버전 불일치 문제

제일 처음 마주친 에러가 바로 이것이었습니다. 로컬에서는 완벽히 작동하는데 GitHub에 푸시하면 빌드가 실패하는 현상 말입니다.

원인은 간단합니다. 내 로컬 머신에 설치된 Ruby 버전과 GitHub Pages가 지원하는 Ruby 버전이 달랐던 것입니다. GitHub Pages는 특정 버전의 Ruby만 공식 지원하기 때문에, 이를 맞춰줘야 합니다.

해결방법은 이렇습니다. 먼저 .ruby-version 파일을 프로젝트 루트에 생성하고 3.3.0 또는 그 이하의 안정적인 버전을 명시합니다. 그리고 Gemfile과 Gemfile.lock을 반드시 GitHub 저장소에 커밋하세요. 이 파일들이 있으면 GitHub Actions가 정확한 의존성 버전을 설치합니다.

나는 rbenv를 사용하여 로컬 환경을 GitHub Pages와 동일하게 설정했습니다. rbenv install 3.1.2 후 rbenv local 3.1.2를 실행하면, 현재 폴더에서만 해당 Ruby 버전이 사용됩니다.

플러그인 호환성 문제

두 번째 난관은 플러그인이었습니다. 멋진 기능의 플러그인을 발견해서 Gemfile에 추가하고 번들을 설치한 후 배포하면, GitHub Pages가 “이 플러그인은 허용되지 않습니다”라는 메시지를 남깁니다.

GitHub Pages는 보안상의 이유로 승인된 플러그인만 사용 가능합니다. jekyll-paginate, jekyll-feed, jekyll-sitemap 정도면 충분하지만, 더 많은 기능을 원할 수도 있죠.

이 경우 GitHub Actions를 활용하는 것이 해결책입니다. 저장소의 .github/workflows/ 디렉토리에 jekyll.yml 파일을 작성하면, GitHub가 빌드 과정을 완전히 제어할 수 있습니다. 이렇게 하면 승인되지 않은 플러그인도 사용할 수 있으며, 더 빠른 배포도 가능합니다.

YAML 프론트매터 오류

세 번째는 가장 찾기 어려운 에러였습니다. 특정 포스트만 빌드를 실패시키는데, GitHub의 에러 메시지는 파일 이름조차 알려주지 않았습니다.

결국 이진 탐색 방식으로 포스트를 하나씩 비활성화하면서 원인을 찾았습니다. 문제는 마크다운 파일의 YAML 프론트매터에 있었습니다. 콜론(:)이 포함된 문자열은 반드시 따옴표로 감싸야 하는데, 나는 무시했던 것입니다.

예를 들어 title: "GitHub: 초보자 가이드" 처럼 작성해야 하고, description 필드에 특수 문자가 있다면 더욱 주의해야 합니다. YAML 린터를 사용하면 이런 실수를 사전에 방지할 수 있습니다.

배포 전 로컬에서 검증하기

내가 배운 가장 중요한 교훈은 로컬 환경이 GitHub Pages와 동일해야 한다는 점입니다.

프로젝트 디렉토리에서 bundle exec jekyll serve를 실행하면 로컬 서버가 시작됩니다. 이 환경은 GitHub Pages 빌드 환경과 거의 동일하기 때문에, 여기서 문제가 없다면 대부분 배포도 성공합니다.

또한 bundle exec jekyll build를 실행하여 _site 폴더가 정상적으로 생성되는지 확인하세요. 만약 경고나 에러가 나타나면, 배포 전에 반드시 해결해야 합니다.

나는 매 배포 전마다 이 과정을 습관처럼 진행합니다. 몇 분의 확인 작업이 며칠의 디버깅을 절약해줍니다.

앞으로의 블로깅을 위해

은퇴 후 취미로 시작한 GitHub Pages 블로깅이 이제 나의 주요 활동이 되었습니다. 처음에는 기술적인 장벽이 높았지만, 이를 극복하면서 더 깊은 만족감을 얻었습니다.

혹시 당신도 Jekyll 빌드 에러로 고민하고 있다면, 먼저 로컬에서 같은 환경을 구성하고 단계적으로 검증해보세요. 대부분의 문제는 예상보다 간단하게 해결됩니다.

오늘부터라도 GitHub Pages로 당신의 블로그를 시작해보지 않으시겠어요?