GitHub Pages에서 Jekyll 빌드가 자꾸 실패하는 이유, 60년 개발자가 찾아낸 해법

시작하며: 늦깎이 블로거의 좌절기

올해 67세가 된 나는 지난 50년간 소프트웨어 개발자로 살아왔습니다. 그런데 정년을 앞두고 갑자기 개발 경험을 정리하고 싶은 마음이 들었습니다. 우리 대학의 젊은 교수들이 모두 GitHub Pages와 Jekyll로 블로그를 운영하고 있다는 것을 알게 되었고, “내 나이에도 할 수 있겠지” 하는 생각으로 시작했습니다.

그것이 얼마나 큰 실수였는지는 처음 git push를 했을 때 알게 되었습니다. 화면에 떴던 것은 친절한 초록색 체크마크가 아니라, 무서운 빨간색 X와 함께 “Build failed” 메시지였습니다. 같은 오류로 4번을 반복했습니다. 5번째 시도에서 깨달은 것들을 오늘은 여러분과 나누고 싶습니다.

Jekyll 빌드 실패의 가장 흔한 원인: Ruby 버전 호환성 문제

처음 내가 마주친 오류 메시지는 이렇게 시작했습니다: “Bundler::GemNotFound: Could not find gem ‘jekyll’ in any of the gem sources”. 나는 로컬에서는 잘 작동하는데 왜 GitHub에서만 안 되는지 이해할 수 없었습니다.

문제는 내 로컬 환경의 Ruby 버전(3.2)과 GitHub Actions에서 사용하는 기본 Ruby 버전이 달랐다는 것입니다. GitHub Pages는 특정 Ruby 버전만 지원하며, 그 버전들도 정기적으로 업데이트됩니다. 나는 .ruby-version 파일도 없었고, Gemfile에는 Ruby 버전 제약이 없었습니다.

해결책은 간단했습니다. 프로젝트 루트에 .ruby-version 파일을 만들고 3.1을 입력했습니다. 그리고 Gemfile의 맨 아래에 다음 한 줄을 추가했습니다:

ruby "~> 3.1.0"

그다음 로컬에서 bundle lock --add-platform x86_64-linux를 실행하여 Gemfile.lock을 업데이트했습니다. 이것이 GitHub의 Linux 환경에서 정확한 gem 버전을 찾도록 도와줍니다. 이 한 가지 변화만으로 5번의 빌드 실패 중 2번이 해결되었습니다.

Chirpy 테마의 숨겨진 설정: _config.yml의 함정

내가 선택한 것은 Chirpy 테마였습니다. 깔끔한 디자인에 매력을 느꼈거든요. 그런데 로컬에서는 완벽하게 보이던 사이트가 GitHub Pages에 배포되니 CSS가 제대로 적용되지 않았습니다. 모든 것이 회색으로 보였습니다.

문제는 _config.yml 파일의 url 설정이었습니다. 나는 이를 비워두었는데, GitHub Pages에서는 이 값이 반드시 정의되어야 합니다. 특히 사용자 페이지가 아닌 프로젝트 페이지(예: github.com/username/reponame)에서 호스팅할 경우, baseurl도 설정해야 합니다.

내가 추가한 설정은 다음과 같습니다:

url: "https://myusername.github.io"
baseurl: "/myblog"

이 작은 두 줄이 모든 CSS 파일, JavaScript 파일, 이미지의 경로를 올바르게 지정하도록 해줍니다. Jekyll은 이 설정을 기반으로 모든 링크를 생성합니다. 이것을 깨닫는 데 3시간이 걸렸습니다.

로컬과 GitHub의 환경 차이: 대소문자 민감성

네 번째 빌드 실패 때는 정말 답답했습니다. 오류 메시지는 매우 불친절했거든요: “Liquid error: non-existent include file”. 로컬에서는 멀쩡한데, GitHub에서만 오류가 발생했습니다.

원인은 파일명의 대소문자였습니다. Windows 환경에서 개발한 내 컴퓨터는 파일명 대소문자를 구분하지 않습니다. 그런데 GitHub의 Linux 서버는 완벽하게 구분합니다. 나는 _includes/header.html이라는 파일을 Header.html이라고 불러왔던 것입니다.

이 문제를 찾기 위해 나는 GitHub Actions의 빌드 로그를 처음으로 자세히 읽어보게 되었습니다. 이 경험이 매우 소중했습니다. 왜냐하면 이후로 모든 오류를 스스로 해결할 수 있는 기초를 얻었기 때문입니다.

해결책은:

1. 모든 파일과 폴더를 소문자로 통일하기
2. 마크다운 파일에서 이미지나 다른 자산을 참조할 때도 정확한 경로 사용하기
3. Git에 이미 대소문자가 다르게 올라가있다면 git mv 명령어 사용하기

빌드 시간 초과: 너무 많은 플러그인의 위험성

다섯 번째 오류는 특이했습니다. 빌드가 30분을 초과했다는 메시지였습니다. GitHub Pages의 빌드는