GitHub Pages 배포 실패의 악순환에서 벗어나는 법

대학 정보과학과에서 30년을 가르친 나는 은퇴 후 블로그를 시작하려 했습니다. 젊은 시절부터 늘 바빴던 나는 마침내 관심 있던 기술 글쓰기에 손을 댈 수 있게 된 것입니다. 그런데 GitHub Pages에 Jekyll 블로그를 올리려는 순간, 예상치 못한 벽에 부딪혔습니다. 배포는 실패하고, 로컬에서는 잘 되는데 온라인에서는 보이지 않고, 심지어 어떤 오류인지 파악하기도 어려웠습니다. 그 과정에서 얻은 경험을 여러분과 나누고자 합니다.

첫 번째 시행착오: 빌드 로그를 무시했던 실수

처음 GitHub Pages 배포를 시도했을 때 가장 큰 실수는 빌드 실패 알림을 제대로 확인하지 않는 것이었습니다. GitHub Actions가 자동으로 실행되고 빨간 X 표시가 나타났지만, 무심코 넘어갔던 것입니다. 세월이 많이 지나 컴퓨터에 익숙해진 나도 이러한 실수를 했으니, 독자 여러분들도 같은 경험을 할 수 있을 겁니다.

해결책은 간단했습니다. 저장소의 Actions 탭을 열어 가장 최근 워크플로우를 클릭한 후, 빌드 실패 메시지를 꼼꼼히 읽는 것입니다. 보통 Jekyll 버전 호환성 문제, 플러그인 지원 불가 메시지, 또는 마크다운 문법 오류가 표시됩니다. 나는 이 로그를 정독하는 습관 하나만으로도 배포 성공률이 80% 이상 올라갔습니다.

두 번째 깨달음: _config.yml의 숨은 설정들

_config.yml 파일은 Jekyll 프로젝트의 심장입니다. 그런데 많은 초보자들, 그리고 그 당시의 나도, 이 파일을 제대로 이해하지 못하고 있었습니다. 특히 GitHub Pages 환경에서만 문제가 발생하는 경우들이 있습니다.

가장 중요한 설정은 baseurl입니다. 개인 또는 조직 저장소라면 baseurl을 비워두면 되지만, 프로젝트 저장소라면 반드시 /repository-name으로 설정해야 합니다. 로컬에서 테스트할 때는 bundle exec jekyll serve --baseurl "" 명령어로 baseurl 없이 실행해야 제대로 작동합니다. 나는 이 차이를 몰라서 한 달을 헤맸습니다.

또한 safe: true 설정은 GitHub Pages의 기본값입니다. 따라서 로컬 환경의 _config.yml과 실제 배포 환경이 다를 수 있다는 점을 명심해야 합니다. Chirpy 테마를 사용하신다면, 테마의 공식 _config.yml을 참고하여 커스터마이징하는 것이 현명합니다.

세 번째 해법: 로컬 테스트의 중요성

GitHub Pages 배포 전에 로컬에서 완벽하게 테스트하는 습관이 얼마나 중요한지 깨닫는 데 시간이 걸렸습니다. Ruby 개발 환경을 제대로 설정하고, Gemfile에서 GitHub Pages와 동일한 의존성을 유지하는 것이 필수입니다.

나는 결국 다음과 같은 루틴을 만들었습니다. 먼저 bundle install로 모든 gem을 설치하고, bundle exec jekyll serve로 로컬 서버를 실행합니다. http://127.0.0.1:4000에서 모든 페이지가 정상 표시되는지 확인하는 것입니다. CSS가 제대로 로드되는지, 포스트 목록이 나타나는지, 내비게이션이 작동하는지 등을 세심하게 확인합니다. 이 과정을 충실히 하면 배포 후 문제가 거의 발생하지 않습니다.

Gemfile.lock 파일도 중요합니다. 로컬과 GitHub Pages 환경의 gem 버전이 정확히 일치하도록 Gemfile.lock 파일을 함께 커밋해야 합니다. 이 파일을 무시하면 환경 차이로 인한 예측 불가능한 오류가 발생할 수 있습니다.

은퇴 후 기술 블로깅을 시작하려는 여러분이 나처럼 시행착오를 겪지 않기를 바랍니다. GitHub Pages와 Jekyll의 관계를 이해하고, 빌드 로그를 읽고, 로컬에서 충분히 테스트한다면, 여러분의 블로그는 안정적으로 운영될 것입니다. 지금 바로 여러분의 저장소 Actions 탭을 열어 최근 배포 상태를 확인해보세요.