GitHub Pages에서 Jekyll 빌드 실패? 로컬 환경 구축이 정답이었다

서론: 반복되는 실패의 악순환

정년을 앞두고 은퇴 후 취미로 시작한 기술 블로깅이었습니다. 40년 개발자 경력 동안 쌓은 지식들을 정리하고 싶었거든요. GitHub Pages에 Jekyll을 올리는 것은 어렵지 않을 거라 생각했습니다. 저는 얼마나 착각했던가요.

처음 두 달간 저는 GitHub 웹 인터페이스에서 직접 파일을 수정하고 커밋했습니다. 그러면 GitHub Actions가 자동으로 Jekyll을 빌드해서 배포할 것이라고 기대했습니다. 하지만 현실은 달랐습니다. 매번 “Build failed” 메일이 날아왔고, 로그를 확인해도 무엇이 잘못됐는지 알 수 없었습니다. YAML 형식이 잘못됐다고 하다가, 다음엔 gem 버전 문제라고 하고, 그 다음엔 마크다운 신택스 오류라고 했습니다.

직업 생활 내내 익숙해진 “원격 서버에 배포 후 테스트”라는 구시대적 방식을 고집한 것이 문제였습니다. 이제 개발 문화는 달라져 있었습니다. 로컬 환경에서 충분히 테스트한 후에야 원격에 올려야 한다는 원칙을 깨달은 것은 이미 5개월차였습니다.

로컬 Jekyll 환경 설치: 더 이상 미룰 수 없었던 결정

마침내 아들이 권한 대로 WSL2를 설치했습니다. Windows Subsystem for Linux 2는 제 노트북의 윈도우 환경에서 리눅스를 직접 실행할 수 있게 해주는 도구였습니다. 명령어 몇 줄로 설치했더니, 마치 제 노트북이 완전한 개발 환경으로 변신했습니다.

그 다음 단계는 Ruby 설치였습니다. 40년 전 저는 어셈블리와 C언어로 개발했는데, 지금은 Ruby라는 우아한 언어가 있다니요. 설치 과정도 간단했습니다. rbenv라는 도구를 사용해서 Ruby 버전을 관리할 수 있었습니다.

curl -fsSL https://github.com/rbenv/rbenv-installer/raw/main/bin/rbenv-installer | bash
rbenv install 3.2.0
rbenv global 3.2.0

그 다음은 Bundler를 설치하고, Jekyll 프로젝트 폴더에서 bundle install을 실행했습니다. 순식간에 필요한 모든 gem 패키지들이 설치되었습니다. 이것이 바로 마법이었습니다. 로컬 환경에서 정확히 같은 버전의 라이브러리들이 설치되는 순간, 제 개발 환경과 GitHub Pages의 빌드 환경이 동일해졌습니다.

실시간 테스트의 기쁨: bundle exec jekyll serve

이제 bundle exec jekyll serve 명령 하나로 로컬 서버가 실행됩니다. 포트 4000번에 브라우저를 띄우면, 제 블로그가 실시간으로 보입니다. 그리고 가장 신기한 부분은 자동 리로드입니다. 마크다운 파일을 저장하면, 몇 초 후 브라우저에 반영됩니다.

이제 저는 더 이상 GitHub에 푸시하기 전에 브라우저에서 확인합니다. 마크다운 신택스가 틀렸다면 로컬에서 즉시 알 수 있습니다. Jekyll 플러그인 문제도 로컬에서 먼저 나타납니다. 이미지 경로가 잘못되었다면, 깃허브에 올리기 전에 수정합니다.

지난 3개월 동안 저는 단 한 번의 빌드 실패도 없었습니다. 평균 20분 걸리던 배포 시간도 이제는 2-3분입니다. 로컬에서 테스트하고 푸시하면 거의 즉시 반영되기 때문입니다.

실전 팁: 개발자 경험의 질을 높이는 방법

저는 Git도 로컬에서 관리하기 시작했습니다. GitHub 웹 인터페이스에서 직접 수정하던 것을 멈추고, VS Code를 열어서 모든 변경사항을 로컬에서 작성합니다. 그 다음 테스트하고, 커밋하고, 푸시합니다.

또 하나 배운 점은 .gitignore 파일의 중요성입니다. Jekyll이 생성하는 _site 폴더나 .jekyll-cache 폴더는 깃에 올릴 필요가 없습니다. 이런 파일들을 제외하면 저장소가 깔끔해지고, 협업할 때도 불필요한 충돌이 줄어듭니다.

Chirpy 테마를 사용하면서 _config.yml의 각 옵션이 무엇을 의미하는지도 로컬에서 확인할 수 있었습니다. 몇 가지 설정을 변경하고 jekyll serve를 실행하면, 바로 화면에 반영되는 모습을 보면서 학습 곡선이 훨씬 가팔라졌습니다.

결론: 경험 많은 개발자의 실수

40년을 개발자로 살면서 배운 가장 큰 교훈은 이것입니다. 옛날 방식에 의존하면 새로운 도구를 제대로 활용할 수 없다는 점입니다. 저는 오직 원격 서버에 배포 후 테스트하는 것만 알았기에, GitHub Pages라는 현대적 플랫폼의 장점을 3개월이나 활용하지 못했습니다.

지금 여러분이 GitHub Pages에서 Jekyll 빌드 오류로 고생하고 있다면, 제 경험을 거울삼으세요. 로컬 환경을 설정하는 데 1시간 정도 투자하면, 그 이후로는 몇 달의 시간과 스트레스를 절약할 수 있습니다. WSL2, Ruby, Bundler, Jekyll. 이 네 가지 도구만 설치하면 여러분도 저처럼 배포 실패 없는 쾌적한 블로깅 경험을 할 수 있을 것입니다.

이제 여러분도 로컬 환경을 구축해서 첫 번째 bundle exec jekyll serve를 실행해보세요. 그 화면이 얼마나 아름답고 신속한지 경험하면, 다시는 원격 배포에만 의존하지 않을 것입니다.