GitHub Pages에서 Jekyll 빌드 실패? 로컬 환경 완벽 구성이 답입니다
67세 교수가 직접 경험한 Jekyll 로컬 환경 구성과 GitHub Pages 배포 문제 해결법
프롤로그: 은퇴 후의 새로운 도전
작년 봄, 40년간 대학에서 컴퓨터과학을 가르쳤던 저는 정년퇴직을 맞이했습니다. 그동안 강의 노트와 연구 자료들이 수십 개의 폴더에 흩어져 있었는데, 제자들과 동료들이 “교수님, 이 자료들을 온라인에 정리해서 올려주세요”라고 계속 요청했습니다. 그렇게 해서 시작하게 된 것이 바로 Jekyll과 GitHub Pages를 이용한 개인 블로그였습니다.
처음엔 쉬울 줄 알았습니다. GitHub에서 몇 번 클릭하고 마크다운으로 글을 쓰면 되는 것 아닌가 싶었죠. 하지만 현실은 달랐습니다. 로컬에서는 멀쩡하게 보이던 사이트가 GitHub Pages에 올리면 엉망이 되고, 플러그인 호환성 문제로 빌드가 실패하는 일들이 반복되었습니다. 그 과정에서 배운 경험들을 오늘 여러분과 나누고 싶습니다.
로컬 환경 구성: 나의 첫 번째 시행착오
GitHub Pages에서 제대로 작동하는 블로그를 만들려면, 먼저 자신의 컴퓨터에 정확히 동일한 환경을 구축해야 합니다. 저는 처음엔 이것을 무시했고, 그 결과 git push 할 때마다 예상 밖의 오류들을 만났습니다.
제가 사용하는 맥북 프로에 먼저 Homebrew를 설치했습니다. 그 다음 Ruby를 설치했는데, 여기서 주의할 점이 있습니다. macOS에 기본으로 설치된 Ruby로는 부족합니다. rbenv를 통해 최신 버전(저는 3.2.0 버전)을 설치해야 합니다. 제 동료 교수는 이를 무시했다가 gem 설치 시 권한 오류로 몇 시간을 낭비했습니다.
1
2
3
brew install rbenv ruby-build
rbenv install 3.2.0
rbenv global 3.2.0
이 명령어들을 실행한 후, Jekyll과 필요한 번들들을 설치합니다. 그런데 여기서 또 다른 함정이 있었습니다. 바로 Gemfile입니다. GitHub Pages는 특정 버전의 Ruby, Jekyll, 그리고 테마만 지원합니다. 저는 최신 버전의 모든 것을 설치했다가, 로컬과 GitHub Pages 사이의 버전 불일치로 수일간 고생했습니다.
해결책은 GitHub의 공식 설정 가이드에 따라 정확한 Gemfile을 구성하는 것입니다. 특히 github-pages gem을 사용하면 자동으로 호환되는 버전들이 설치됩니다. 이것이 제가 발견한 가장 중요한 팁 중 하나입니다.
GitHub Pages의 숨겨진 제약 조건
학문의 세계에서 40년을 보낸 저에게 GitHub Pages는 매우 민감한 시스템이라는 것을 배우는 데 3개월이 걸렸습니다. 모든 플러그인을 사용할 수 있는 것이 아니라는 점을 말입니다.
GitHub Pages는 보안상의 이유로 특정 Jekyll 플러그인만 허용합니다. 예를 들어, 저는 jekyll-youtube 플러그인을 사용하고 싶었는데, 이는 화이트리스트에 없어서 작동하지 않았습니다. 로컬에서는 완벽하게 동작했지만, GitHub에 올리는 순간 무시되었습니다.
이 문제를 해결하기 위해 저는 GitHub Actions를 사용하기로 결정했습니다. 로컬에서 빌드한 정적 파일들을 _site 폴더에 생성하고, 이를 직접 GitHub에 푸시하는 방식입니다. 처음엔 이것이 번거로워 보였지만, 이제는 이것이 가장 강력하고 유연한 방식이라는 것을 알았습니다.
YAML 파일로 간단한 GitHub Actions 워크플로우를 만들었습니다:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
name: Jekyll Build and Deploy
on: [push]
jobs:
build-and-deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- uses: ruby/setup-ruby@v1
with:
ruby-version: 3.2
bundler-cache: true
- run: bundle exec jekyll build
- uses: peaceiris/actions-gh-pages@v3
with:
github_token: $
publish_dir: ./_site
이 설정 이후로는 단순히 마크다운으로 글을 쓰고 git push만 하면, 자동으로 모든 빌드와 배포가 이루어집니다. 정말 마법 같은 경험이었습니다.
테마 커스터마이징과 실수들
제가 선택한 테마는 Chirpy였습니다. 깔끔하고 기능이 풍부해서 마음에 들었거든요. 하지만 이 테마도 깊게 파고들면 복잡했습니다.
처음엔 단순히 _config.yml 파일을 수정했는데, 변경사항이 적용되지 않는 경험을 했습니다. 로컬 서버를 재시작해야 한다는 것을 뒤늦게 알았습니다. Jekyll은 파일 변경을 감시