GitHub Pages 배포 실패? Jekyll 빌드 에러 디버깅의 정석

대학 강의실에서 블로그 강의실로

30년간 전자공학을 가르쳤던 나는 퇴직 후 블로그를 시작하기로 결심했습니다. 공학 강의 노트를 정리하고 후학들을 위한 기술 자료를 공유하려는 목표였죠. 그런데 막상 GitHub Pages에 Jekyll 블로그를 구축하면서 생각지 못한 빌드 에러 지옥에 빠졌습니다. 당시 나는 C와 어셈블리 전문가였지, 루비나 마크다운 문법은 생소했거든요.

“왜 로컬에서는 완벽하게 작동하는데 GitHub에서는 자꾸 빌드가 실패할까?”

이 질문이 나를 2주간 밤새우게 만들었습니다. 하지만 그 고통의 과정 덕분에 Jekyll과 GitHub Pages의 미묘한 설정 차이들을 깊이 있게 이해하게 되었습니다. 오늘은 그 경험담을 나누고자 합니다.

Ruby 버전 불일치, 가장 흔한 함정

첫 번째 교훈은 로컬 환경과 GitHub의 루비 버전이 다를 수 있다는 것이었습니다. 나는 Mac에 Ruby 3.1을 설치했는데, GitHub Pages의 빌드 서버는 당시 Ruby 2.7을 사용하고 있었습니다. Gemfile에 ruby "3.1.0"을 명시했기 때문에 GitHub에서 자동으로 호환성 체크를 시작한 것이죠.

해결책은 간단했습니다. .ruby-version 파일을 생성하고 2.7.8 같은 GitHub 서버의 지원 버전을 명시하는 것이었습니다. 또한 Gemfile.lock 파일을 항상 최신 상태로 유지하는 것이 중요합니다. 이 파일은 마치 의약품의 유효기한처럼 작용합니다. 너무 오래된 lock 파일은 새로운 의존성과 충돌을 일으키곤 합니다.

실제로 내가 했던 실수는 로컬에서만 번들을 업데이트하고 Gemfile.lock을 커밋하지 않은 것입니다. 결과적으로 GitHub는 매번 다른 의존성 버전을 설치하려 했고, 그때마다 예측 불가능한 에러가 발생했습니다.

테마와 플러그인의 호환성 문제

Jekyll Chirpy 테마를 사용하면서 또 다른 문제를 마주쳤습니다. 로컬 환경에서 작동하는 커스텀 플러그인들이 GitHub Pages의 제한된 플러그인 환경에서는 먹혀들지 않았던 것입니다. GitHub는 보안상의 이유로 모든 루비 플러그인을 허용하지 않습니다. 단지 특정 공식 플러그인들만 화이트리스트에 포함되어 있죠.

내가 jekyll-paginate-v2를 사용하려고 했을 때 GitHub 빌드는 자동으로 실패했습니다. 하지만 이걸 처음에는 알 수 없었습니다. 빌드 로그를 제대로 읽지 않았거든요. 깃허브 저장소의 Settings > Pages 섹션에서 “Build and deployment” 아래의 빌드 로그를 정독해야 합니다. 이곳에 모든 답이 담겨 있습니다.

해결책은 두 가지였습니다. 첫째, GitHub에서 공식 지원하는 플러그인만 사용하기. 둘째, GitHub Actions를 활용하여 로컬 환경과 동일한 빌드 프로세스를 GitHub 서버에서도 구동하기입니다. 후자는 좀 더 고급 기법이지만, 복잡한 플러그인이 필요한 경우 매우 유용합니다.

프론트매터와 파일명의 숨겨진 함정

마지막으로 배운 교훈은 YAML 프론트매터의 엄격함이었습니다. 마크다운 파일 최상단의 메타데이터 영역을 프론트매터라고 부르는데, 여기서 한글 문자 인코딩 문제가 자주 발생했습니다. 특히 title이나 description에 특수문자를 포함할 때 그랬습니다.

한 번은 제목에 쌍따옴표를 넣었는데, 이것 때문에 YAML 파싱이 깨졌습니다. Jekyll은 로컬에서는 관대하게 처리했지만, GitHub의 빌드 시스템은 엄격했습니다. 해결책은 프론트매터의 문자열을 항상 큰따옴표로 감싸고, 내부의 큰따옴표는 백슬래시로 이스케이프하는 것입니다.

또한 파일명도 중요합니다. 2026-05-18-제목.md 형식을 지켜야 하는데, 파일명에 한글을 사용하면 일부 서버에서 인코딩 문제가 발생할 수 있습니다. 나는 이제 파일명은 영문 소문자와 하이픈만 사용하고 있습니다.

디버깅의 핵심, 로그 읽기

퇴직 전 마지막 학기, 나는 학생들에게 “에러 메시지는 너의 친구”라고 가르쳤습니다. 컴퓨터는 항상 당신에게 무엇이 잘못되었는지 말해줍니다. GitHub Pages도 마찬가지입니다. GitHub 저장소의 Actions 탭에서 각 배포 시도의 로그를 볼 수 있습니다. 이 로그는 보물 지도와 같습니다. 어디서 빌드가 실패했는지, 왜 실패했는지 정확히 알려줍니다.

내가 가장 자주 실수한 부분은 로그를 읽지 않고 “아, 또 실패했네”라고만 생각하는 것이었습니다. 정확한 에러 메시지를 읽고, 그에 맞는 해결책을 찾는 습관이 생기자 문제 해결 속도는 극적으로 빨라졌습니다.

30년 경력의 교수도 새로운 기술 앞에서는 초심자입니다. 하지만 체계적인 접근과 끈기 있는 디버깅으로 모든 문제는 해결될 수 있습니다. 당신의 Jekyll 블로그가 GitHub Pages에서 완벽하게 작동하길 바랍니다. 혹시 비슷한 문제로 고민 중이라면, 댓글로 구체적인 에러 메시지를 남겨주세요. 함께 풀어보겠습니다.