GitHub Pages 빌드 실패의 늪에서 빠져나온 이야기

은퇴 후 취미로 시작한 블로깅의 악몽

저는 대학교수를 정년퇴직한 후 블로그를 시작하기로 마음먹었습니다. Jekyll과 GitHub Pages를 사용하면 무료로 깔끔한 블로그를 운영할 수 있다는 이야기를 들었거든요. Chirpy 테마까지 적용하니 정말 멋진 블로그가 되었습니다. 그런데 며칠 뒤 갑자기 블로그가 보이지 않기 시작했습니다.

GitHub 저장소의 Actions 탭을 열어보니 빨간색 X 표시가 떠있었고, 로그는 온통 에러 메시지로 가득 찼습니다. 처음엔 매우 당황했지만, 이제 와서 생각해보니 그 경험이 매우 귀했습니다. 아마도 같은 문제로 고민하는 분들이 많을 것 같아서 오늘은 제가 겪었던 GitHub Pages 빌드 실패 문제와 해결 방법을 공유하려고 합니다.

가장 흔한 원인: 플러그인 호환성 문제

GitHub Pages는 보안상의 이유로 특정 Jekyll 플러그인만 허용합니다. 저는 로컬 환경에서는 완벽하게 작동하는 플러그인을 여러 개 설치했는데, GitHub에 푸시하자마자 빌드가 실패했습니다. 에러 메시지를 읽어보니 “The following gem(s) were not found”라는 내용이었습니다.

저는 _config.yml 파일에 다양한 플러그인을 등록했고, 로컬에서는 bundle install로 모든 의존성을 설치할 수 있었습니다. 하지만 GitHub Pages는 안전한 모드에서만 작동하기 때문에 공식적으로 승인된 플러그인만 사용할 수 있습니다.

해결책은 의외로 간단했습니다. 먼저 _config.yml의 plugins 섹션을 확인하고, GitHub Pages가 지원하는 플러그인 목록(jekyll-seo-tag, jekyll-feed, jekyll-sitemap 등)과 비교했습니다. 허용되지 않는 플러그인은 제거했고, 필요한 기능은 GitHub Actions의 custom workflow를 사용해 구현했습니다. 이후 빌드가 정상적으로 진행되었습니다.

숨겨진 함정: 파일 인코딩과 한글 문제

두 번째 문제는 더욱 까다로웠습니다. 포스트를 작성할 때 파일 이름에 한글을 사용했다가는 안 되지만, 본문에 한글을 포함할 때는 인코딩이 중요합니다. 저는 Windows 환경에서 작성한 마크다운 파일을 GitHub에 올렸더니 빌드 과정에서 파일을 읽을 수 없다는 에러가 발생했습니다.

원인은 파일의 인코딩이 UTF-8이 아니라 EUC-KR이었습니다. Windows의 기본 텍스트 에디터에서 저장하면 이런 일이 발생할 수 있습니다. 저는 처음에 이 문제를 파악하기 위해 꽤 오래 걸렸습니다. GitHub의 빌드 로그가 명확한 에러 메시지를 주지 않았거든요.

해결책은 모든 마크다운 파일을 UTF-8 인코딩으로 변환하는 것이었습니다. VS Code를 사용하면 우측 하단의 인코딩 표시를 클릭해 UTF-8로 변경할 수 있습니다. 또한 .gitattributes 파일을 저장소 루트에 생성하고 * text=auto encoding=UTF-8 같은 설정을 추가하면 향후 같은 문제를 미연에 방지할 수 있습니다.

내가 배운 최고의 팁: 로컬 빌드 검증

저는 모든 포스트를 GitHub에 푸시하기 전에 로컬 환경에서 먼저 빌드를 시도하는 습관을 들였습니다. 터미널에서 bundle exec jekyll serve 명령을 실행하면, 자신의 컴퓨터에서 먼저 사이트를 확인할 수 있습니다. 이렇게 하면 GitHub의 오류로 고생할 일이 대부분 줄어듭니다.

특히 _config.yml 파일을 수정했거나 새로운 플러그인을 추가했을 때, 혹은 레이아웃을 변경했을 때는 반드시 로컬에서 검증하는 것이 좋습니다. 제 경험상 빌드 시간이 몇 초 늘어나는 것이 GitHub에서 한 시간씩 기다리는 것보다 훨씬 효율적입니다.

마지막 조언

지난 몇 년간 블로깅을 하면서 정말 많은 교수님들과 은퇴자분들이 개인 블로그를 만들고 싶어 하시는 것을 봤습니다. GitHub Pages는 정말 좋은 선택입니다. 하지만 처음 사용할 때는 몇 가지 함정이 있다는 점을 알고 시작하면 훨씬 수월합니다. 여러분도 비슷한 문제를 경험한다면, 먼저 로컬 빌드 로그를 확인하고, GitHub Actions의 빌드 로그를 자세히 읽어보세요. 대부분의 문제는 명확한 진단으로 해결됩니다.

지금 이 글을 읽고 계신 분 중에 GitHub Pages 빌드로 고민하시는 분이 있다면, 댓글로 구체적인 에러 메시지를 공유해주세요. 저도 응원하고 싶습니다.