GitHub Pages에서 Jekyll 빌드가 자꾸 실패하는 이유, 드디어 알았습니다
67세 교수가 겪은 Jekyll 빌드 오류 해결 경험담과 실질적인 해결 방법
대학 40년 경력의 새로운 도전, Jekyll 블로그
저는 서울의 한 대학에서 40년간 컴퓨터과학을 가르쳐온 교수입니다. 올해 67세인 저는 정년을 앞두고 연구 자료를 체계적으로 정리하기 위해 GitHub Pages와 Jekyll을 배우기로 결심했습니다. 젊은 시절에는 HTML과 CSS로 웹사이트를 만들었지만, 시대가 변했다고 생각했거든요.
처음 몇 주는 좋았습니다. GitHub에 계정을 만들고, Jekyll 테마를 선택하고, 로컬에서 블로그를 실행했을 때 완벽했으니까요. 그런데 GitHub에 푸시하는 순간, GitHub Actions에서 빌드가 자꾸 실패했습니다. 같은 파일이 로컬에서는 멀쩡한데 말입니다. 이 좌절감은 마치 강의실에서 완벽하게 준비한 시험지를 인쇄소에 제출했는데 글씨가 깨져 나온 것과 같았습니다.
Ruby 버전 불일치, 가장 흔한 함정
첫 번째 문제는 Ruby 버전이었습니다. 제 로컬 맥북에는 Ruby 3.2가 설치되어 있었는데, GitHub Actions는 기본적으로 다른 버전을 사용하고 있었습니다. Jekyll의 플러그인들은 버전에 민감해서, 로컬에서는 작동하지만 GitHub의 서버에서는 호환되지 않는 경우가 생기는 것입니다.
해결 방법은 생각보다 간단했습니다. 저는 프로젝트 루트에 .ruby-version 파일을 생성하고 버전을 명시했습니다:
1
3.2.0
그리고 더 중요한 것은 .github/workflows/ 디렉토리에 jekyll.yml 파일을 직접 만들어서 GitHub Actions에서 사용할 Ruby 버전을 명확히 지정하는 것입니다. 이렇게 하니 로컬과 서버의 환경이 일치하게 되었고, 빌드 오류가 반으로 줄어들었습니다.
Gemfile이 최고의 보험
두 번째 문제는 의존성(dependency) 관리였습니다. 제가 사용하는 Jekyll 테마 “Chirpy”는 여러 개의 Ruby 젬(gem)을 필요로 합니다. 로컬에서 bundle install을 실행하면 Gemfile.lock이 생성되는데, 이 파일을 GitHub에 커밋하지 않으면 서버에서 다른 버전의 젬들을 설치하게 됩니다.
처음에는 Gemfile.lock을 .gitignore에 포함시켰던 실수를 했습니다. 이것이 왜 문제가 되는지 깨닫기까지 3일이 걸렸습니다. 결론은 이렇습니다:
1
2
# Gemfile.lock은 반드시 커밋하세요
# 이것이 로컬과 서버의 정확한 의존성을 일치시키는 유일한 방법입니다
제 Gemfile은 다음과 같이 구성했습니다:
1
2
3
4
5
6
7
8
9
10
11
source "https://rubygems.org"
gem "jekyll", "~> 4.3.0"
gem "jekyll-theme-chirpy", "~> 6.0"
gem "webrick", "~> 1.7"
group :jekyll_plugins do
gem "jekyll-paginate"
gem "jekyll-redirect-from"
gem "jekyll-seo-tag"
end
GitHub Actions 워크플로우 설정, 세 번째 관문
마지막 문제는 GitHub Actions의 워크플로우 설정이었습니다. 저는 처음에 Jekyll의 기본 워크플로우를 사용했는데, 이것이 모든 플러그인을 제대로 지원하지 않았습니다.
특히 _site 디렉토리의 생성 과정에서 권한 문제가 생겼고, 빌드 프로세스가 중간에 멈추는 경험을 했습니다. 이를 해결하기 위해 저는 다음과 같은 워크플로우를 직접 작성했습니다:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
name: Build and Deploy
on:
push:
branches: [ main ]
pull_request:
branches: [ main ]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Set up Ruby
uses: ruby/setup-ruby@v1
with:
ruby-version: 3.2
bundler-cache: true
- name: Build with Jekyll
run: bundle exec jekyll build
- name: Deploy to GitHub Pages
if: github.ref == 'refs/heads/main'
uses: peaceiris/actions-gh-pages@v3
with:
github_token: $
publish_dir: ./_site
이 워크플로우의 핵심은 bundler-cache: true 옵션으로, 이것이 Gemfile.lock을 사용하여 정확한 의존성을 설치하도록 강제합니다.
내가 배운 교훈
40년 동안 학생들을 가르쳐온 경험에서 알 수 있듯이, 기술은 세부 사항에 있습니다. GitHub Pages와 Jekyll도 마찬가지입니다. 로컬 환경과 서버 환경의 불일치가 모든 문제의 근원입니다.
처음에는 이런 오류 메시지들이 답답했습니다. 하지만 깊이 파고들다 보니, 각 오류가 명확한 이유를 가지고 있었고, 해결 방법도 합리적이었습니다. 이제