GitHub Pages에서 Jekyll 빌드가 실패하는 이유, 20년 개발자도 헷갈리는 숨겨진 함정들

프롤로그: 67세 개발 교수의 첫 번째 GitHub Pages 도전기

저는 지난 40년간 대학에서 프로그래밍을 가르쳐온 교수입니다. 작년에 은퇴를 앞두고 제 경험담과 강의 노트를 정리하기 위해 블로그를 시작하려고 했습니다. “Jekyll과 GitHub Pages면 충분하겠지”라고 생각했던 것이 얼마나 순진한 판단이었는지 깨닫는 데는 2주밖에 걸리지 않았습니다.

처음에는 공식 문서를 따라가며 로컬에서 완벽하게 빌드되었습니다. 하지만 GitHub에 푸시하는 순간, 빌드 실패 알림이 날아왔습니다. “Why on earth is this failing?” 라고 외쳤던 기억이 생생합니다. 그 이후 일주일간의 디버깅 과정을 통해 배운 교훈들을 여러분과 나누고자 합니다.

1단계: 로컬 환경과 GitHub 환경의 숨겨진 차이

가장 큰 문제는 로컬 환경에서는 완벽하게 작동하지만, GitHub Pages의 원격 환경에서는 실패하는 현상이었습니다.

루비 버전의 불일치가 첫 번째 범인이었습니다. 제 MacBook Pro에는 Ruby 3.0이 설치되어 있었지만, GitHub Pages는 특정 루비 버전으로만 빌드를 진행합니다. GitHub Pages의 Dependabot이 권장하는 Ruby 버전을 확인하지 않은 것이 실수였습니다.

해결책은 간단했습니다. 프로젝트 루트에 .ruby-version 파일을 생성하고 GitHub가 권장하는 버전을 명시했습니다:

3.1.2

또한 Gemfile을 반드시 포함시켜야 합니다. 저는 처음에 로컬에서만 bundle install을 사용하고 Git에는 올리지 않았는데, GitHub는 이 파일을 통해 의존성을 파악합니다. 특히 주의할 점은 Gemfile과 Gemfile.lock을 모두 커밋해야 한다는 것입니다. Gemfile.lock을 gitignore에 포함시켜서 또 한 번 실패했던 경험이 있습니다.

2단계: 플러그인과 테마의 호환성 문제

Jekyll의 강력함은 플러그인에 있지만, 이것이 또한 가장 큰 함정입니다.

저는 SEO 최적화를 위해 jekyll-seo-tag 플러그인을 추가했고, 자동 사이트맵 생성을 위해 jekyll-sitemap을 설치했습니다. 로컬에서는 모두 정상 작동했습니다. 하지만 GitHub Pages는 안전상의 이유로 특정 플러그인만 허용합니다.

GitHub Pages 공식 문서에는 “지원되는 플러그인” 목록이 있습니다. 저는 이를 간과했고, 지원하지 않는 플러그인을 사용했기 때문에 원격 빌드가 계속 실패했습니다.

해결책은 두 가지입니다:

첫 번째, GitHub이 지원하는 플러그인만 사용하는 것입니다. 공식적으로 지원되는 플러그인은:

• jekyll-coffeescript
• jekyll-default-layouts
• jekyll-gist
• jekyll-github-metadata
• jekyll-optional-front-matter
• jekyll-paginate
• jekyll-redirect-from
• jekyll-relative-links
• jekyll-sass-converter
• jekyll-seo-tag
• jekyll-sitemap
• jekyll-mentions
• jemoji

두 번째, 지원하지 않는 플러그인을 꼭 사용해야 한다면 GitHub Actions를 통해 로컬에서 빌드 후 결과물을 업로드하는 방식으로 전환하는 것입니다. 이 방법을 알게 된 후, 저는 더 다양한 플러그인을 자유롭게 사용할 수 있었습니다.

3단계: _config.yml의 숨겨진 설정 함정

_config.yml은 Jekyll의 심장입니다. 하지만 원격 빌드와 로컬 빌드 간의 설정 불일치가 발생하기 쉬운 부분이기도 합니다.

저는 로컬 환경에서만 적용되는 설정을 _config.yml에 포함시켰습니다. 예를 들어, url과 baseurl 설정이 그것입니다. 로컬에서는 http://localhost:4000으로 테스트하지만, GitHub Pages는 https://yourusername.github.io에서 서빙됩니다.

더 심각한 문제는 theme과 remote_theme의 혼용이었습니다. Chirpy 테마를 사용할 때, 저는 두 옵션을 동시에 지정했는데, 이로 인해 충돌이 발생했습니다.

올바른 설정은:

# GitHub Pages에서는 remote_theme 사용
remote_theme: cotes2020/jekyll-theme-chirpy@latest

# baseurl 설정 (리포지토리 이름이 있는 경우)
baseurl: "/repository-name"

# url 설정
url: "https://yourusername.github.io"

또한 safe: true 옵션은 GitHub Pages에서 자동으로 활성화되므로, 별도로 설정할 필요가 없습니다.

실전 팁: GitHub Actions를 통한 완전한 통제

제 경