GitHub Pages 빌드 실패의 90%는 이것 때문이었다

대학을 정년퇴직하고 개인 블로그를 운영하려던 2024년, 나는 GitHub Pages와 Jekyll의 세계에 입문했습니다. 처음에는 간단할 거라 생각했지만, 실제로는 크고 작은 난관들이 연달아 나타났습니다. 특히 빌드 실패는 정말 답답한 경험이었는데, 지난 2년간 수십 번의 시행착오를 거치면서 패턴을 발견했습니다. 오늘은 그 경험을 바탕으로 GitHub Pages 빌드 문제 해결법을 공유하고자 합니다.

가장 흔한 범인: _config.yml의 인코딩 문제

처음 GitHub Pages에 Jekyll 블로그를 올렸을 때, 수십 번의 빌드 실패 메시지를 받았습니다. 당시 나는 어디서부터 문제를 찾아야 할지 몰라 정말 답답했습니다. 결국 발견한 것은 _config.yml 파일의 문자 인코딩 문제였습니다.

특히 한글 설정값을 포함할 때 더욱 그랬습니다. Windows 메모장으로 파일을 저장하면 기본으로 ANSI 인코딩이 되는데, Jekyll은 UTF-8을 요구합니다. 저는 처음에 이 차이를 모르고 며칠을 헤맸습니다. 이제는 항상 VS Code나 Sublime Text 같은 에디터에서 파일을 생성하고, 명시적으로 UTF-8 인코딩을 지정합니다. 파일 하단에 다음과 같은 주석을 추가하는 것도 좋은 습관입니다:

# -*- coding: utf-8 -*-

또한 _config.yml에서 한글이 포함된 값을 사용할 때는 반드시 따옴표로 감싸야 합니다. 예를 들어 tagline: "은퇴 후의 기술 여정"처럼 말이죠. 이 간단한 규칙을 알고 나니 빌드 성공률이 급격히 올라갔습니다.

로컬 테스트 없이 GitHub에 바로 올리지 말 것

제 나이 대의 사람들은 대체로 서툰 부분이 있는데, 저도 처음엔 로컬 테스트 과정을 건너뛰었습니다. 파일을 수정하면 바로 GitHub에 push 했거든요. 당연히 빌드는 자주 실패했습니다.

지난 2년간 배운 가장 귀중한 교훈은 jekyll serve 명령으로 로컬에서 먼저 확인하는 것입니다. 이렇게 하면 빌드 오류 메시지를 즉시 볼 수 있고, 문제를 빠르게 수정할 수 있습니다. 터미널에서 다음 명령을 실행하세요:

bundle exec jekyll serve

로컬 서버가 실행되면 http://localhost:4000으로 접속하여 블로그를 확인할 수 있습니다. 나는 이 과정을 통해 YAML 문법 오류, 이미지 경로 문제, Liquid 템플릿 오류 등을 미리 발견할 수 있었습니다. 이제 저는 절대 로컬 테스트를 건너뛰지 않습니다. 이것이 시간을 절약하는 가장 확실한 방법입니다.

Ruby 버전 불일치와 Gemfile 관리

제가 마주친 또 다른 큰 문제는 Ruby 버전 불일치였습니다. 로컬에서는 잘 되는데 GitHub Actions에서는 빌드가 실패하는 현상이 반복되었습니다. 원인은 제 컴퓨터의 Ruby 버전과 GitHub에서 사용하는 버전이 달랐기 때문입니다.

이 문제를 해결하기 위해 저는 Gemfile과 Gemfile.lock 파일을 항상 관리하기로 했습니다. GitHub Pages에서 권장하는 jekyll 버전은 보통 3.9.x 대인데, Gemfile에 다음과 같이 명시하면 됩니다:

gem "jekyll", "~> 3.9"
gem "github-pages", group: :jekyll_plugins

Gemfile.lock 파일도 함께 커밋하면 로컬과 GitHub 환경에서의 의존성이 일치하게 됩니다. 처음엔 이런 파일들이 복잡해 보였지만, 지금은 이것들이 얼마나 유용한지 압니다. 특히 팀 작업을 할 때나 여러 기기에서 작업할 때 정말 소중한 것입니다.

혹시 여전히 빌드가 실패한다면, GitHub 저장소의 Actions 탭에서 상세한 빌드 로그를 확인하세요. 나는 그 로그 메시지들을 읽으며 많은 것을 배웠습니다.

지금까지의 경험을 토대로 보면, GitHub Pages 빌드 문제는 대부분 이 세 가지 중 하나입니다. 혹시 당신의 블로그도 빌드 실패로 고민 중이라면, 이 글의 해결책들을 하나씩 적용해 보세요. 저처럼 답답함을 겪을 필요는 없을 거라 확신합니다.

댓글로 당신이 경험한 GitHub Pages 빌드 오류 사례를 공유해 주세요. 함께 해결책을 찾아봅시다!