GitHub Pages가 빌드 실패하는 이유, 67세 교수가 찾아낸 해결책

교수도 헷갈리는 GitHub Pages 빌드 실패의 악순환

올해로 교직 생활 30년째를 맞이한 나는 작년부터 개인 기술 블로그를 운영하고 있습니다. 정년 이전에 그동안 쌓아온 프로그래밍 경험담과 학생들을 가르치며 얻은 인사이트를 기록하고 싶었거든요. Jekyll과 GitHub Pages를 선택한 것은 마크다운 문법으로 간단히 포스팅할 수 있다는 점 때문이었습니다.

그런데 첫 세 달간 정말 고생했습니다. 글을 작성하고 GitHub에 푸시하면 “Build failed” 이메일만 자꾸 날아왔습니다. 아무리 로컬에서 bundle exec jekyll serve로 확인해도 완벽한데, GitHub에서는 자꾸 실패한다고 하는 거예요. 처음엔 내 실력 부족이라 생각했지만, 며칠에 걸쳐 차근차근 분석해보니 패턴이 보이기 시작했습니다.

루비 버전 불일치가 일으키는 숨겨진 함정

가장 먼저 발견한 문제는 루비 버전 불일치였습니다. 로컬 환경에서 설치한 루비 버전과 GitHub Actions에서 실행되는 루비 버전이 달랐던 것입니다.

나는 처음에 .ruby-version 파일의 중요성을 모르고 있었습니다. Windows 환경에서 Ruby 3.2.0을 설치했고, Jekyll Chirpy 테마를 적용했는데, GitHub의 기본 환경은 Ruby 2.7이었던 거죠. 특정 젬(gem)들이 Ruby 3.2에서는 잘 작동하지만 2.7에서는 호환되지 않는 문제가 발생했습니다.

해결책은 간단했습니다. 프로젝트 루트에 .ruby-version 파일을 생성하고 3.2.0이라고 명시했고, Gemfile에서도 ruby "3.2.0"을 명시했습니다. 더 나아가, .github/workflows/jekyll.yml 파일을 수정하여 GitHub Actions가 동일한 루비 버전을 사용하도록 강제했습니다. 그 순간부터 빌드 성공률이 확 올라갔습니다.

_config.yml에 숨어있는 지뢰들

두 번째 문제는 _config.yml 파일의 설정 오류였습니다. 인터넷에서 여러 설정 예제를 참고하다 보니 서로 충돌하는 옵션들이 섞여있었던 겁니다.

특히 url과 baseurl 설정이 문제였어요. 내 GitHub 사용자명이 “professor-lee”인데, Repository 이름을 “professor-lee.github.io”로 만들었을 때는 baseurl: ""로 설정해야 합니다. 하지만 다른 Repository 이름(예: “tech-blog”)으로 설정하려면 baseurl: "/tech-blog"로 명시해야 합니다. 이 작은 실수가 CSS와 이미지 경로를 모두 깨뜨렸던 것입니다.

또한 Chirpy 테마는 특정 플러그인들을 요구하는데, _config.yml에서 plugins: 섹션이 제대로 설정되지 않으면 테마의 스타일링이 전혀 적용되지 않습니다. 저는 plugins:에 jekyll-paginate, jekyll-redirect-from, jekyll-seo-tag, jekyll-archives 등 모든 필수 플러그인을 명시해야 했습니다.

.gitignore와 빌드 캐시 문제의 미스터리

세 번째로 만난 문제는 제가 _site 디렉토리를 실수로 Git에 커밋해버린 것이었습니다. 로컬에서는 성공적으로 빌드되는데 GitHub에서만 자꾸 실패하길래, 아예 먼저 빌드한 결과물이 리포지토리에 남아있으면 GitHub Actions가 혼동하는 건 아닐까 싶었어요.

문제를 해결하기 위해 저는:

1. 프로젝트 루트의 .gitignore 파일을 확인했습니다.
2. _site/, .jekyll-cache/, .jekyll-metadata 등 빌드 관련 디렉토리가 제대로 무시되도록 설정했습니다.
3. 이미 커밋된 이력이 있다면 git rm -r --cached _site/로 제거했습니다.

이 과정 후에 GitHub Actions는 항상 깨끗한 상태에서 빌드를 시작하게 되었고, 예측 불가능한 오류들이 대부분 사라졌습니다.

실제 해결 과정에서 배운 디버깅 팁

67년을 살면서 배운 것 중 하나는 “급할수록 돌아가라”는 교훈입니다. GitHub Pages 빌드 오류도 마찬가지였습니다.

먼저 GitHub의 Actions 탭에서 실패한 빌드 로그를 꼼꼼히 읽었습니다. 대부분의 오류는 로그에 명확히 드러나 있었어요. “Liquid syntax error”, “cannot find include file”, “undefined method” 같은 메시지들이 구체적으로 어느 줄에서 문제가 발생했는지 알려주고 있었는데, 저는 처음에 그걸 제대로 읽지 않고 있었습니다.

그 다음, 로컬 환경을 GitHub 환경과 최