GitHub Pages가 갑자기 배포 안 된다? 10년 경력 개발자도 헷갈리는 Jekyll 빌드 문제 해결기

은퇴 후 시작한 블로깅, 예상 밖의 첫 번째 난관

학교에서 30년을 가르치다가 은퇴한 지 이제 2년. 시간이 많아지니 평소에 관심 있던 프로그래밍을 제대로 배워보고 싶었습니다. 그렇게 시작한 것이 개인 기술 블로그였습니다. 젊은 시절 C와 Java 정도만 해본 제가 현대적인 웹 기술을 배우기 위해서는 뭔가 프로젝트가 필요했거든요.

“GitHub Pages에 Jekyll로 블로그를 만들면 된다”는 유튜브 튜토리얼을 따라 시작했습니다. 로컬 환경에서는 완벽하게 작동했습니다. 화면도 예쁘고, 포스트도 잘 올라가고. 하지만 GitHub에 push한 후 몇 시간이 지나도 웹사이트가 업데이트되지 않았습니다.

“뭐, 이런 일이?” 하고 생각했지만, 젊은 시절 경험으로 문제 해결 방법을 알고 있었습니다. 로그를 확인하는 것이었습니다.

GitHub Actions 로그에서 발견한 “권한 문제”

GitHub 저장소의 Settings 탭을 들어갔을 때, 저는 깜짝 놀랐습니다. 잘알려진 “Build and deployment” 섹션에는 에러 메시지가 있었고, 메일함에는 GitHub로부터의 배포 실패 알림이 몇 개 쌓여있었던 것입니다.

로그를 자세히 읽어보니 문제가 명확했습니다:

1. Ruby 버전 호환성 문제 - 로컬에서는 Ruby 3.2를 썼지만, GitHub Actions의 기본값은 Ruby 2.7
2. Gemfile.lock의 없음 - 정확한 의존성 버전을 명시하지 않았음
3. 테마의 불완전한 설정 - Chirpy 테마의 일부 설정이 빠져있었음

특히 인상적이었던 건, 로컬에서는 “작동한다”고 해서 GitHub에서도 작동하는 게 아니라는 것이었습니다. GitHub Actions는 완전히 새로운 환경에서 처음부터 빌드하기 때문입니다.

저는 .github/workflows/pages.yml 파일을 직접 확인했고, 다음과 같이 수정했습니다:

name: Build and Deploy

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Ruby
        uses: ruby/setup-ruby@v1
        with:
          ruby-version: 3.2
          bundler-cache: true
          
      - name: Build site
        run: bundle exec jekyll build

더 중요한 건 로컬 환경과 동일하게 유지하기 위해 Gemfile.lock을 반드시 git에 커밋하는 것이었습니다.

Gemfile 관리와 테마 호환성 - 숨겨진 함정들

은퇴 후 배운 또 다른 교훈은 “의존성 관리의 중요성”이었습니다.

제가 사용한 Chirpy 테마는 정말 훌륭했지만, 기본 Gemfile이 복잡했습니다. 특히 Windows와 Linux, macOS 간의 호환성 문제가 있었습니다. Jekyll은 기본적으로 Linux 기반으로 설계되어 있기 때문에, Windows 로컬 환경에서는 잘 작동하지만 GitHub Actions (Linux 기반)에서는 문제가 생기는 경우가 많았습니다.

# Gemfile의 중요한 부분
source "https://rubygems.org"

gem "jekyll", "~> 4.3.0"
gem "jekyll-theme-chirpy", "~> 6.0"

group :jekyll_plugins do
  gem "jekyll-paginate"
  gem "jekyll-redirect-from"
  gem "jekyll-seo-tag"
  gem "jekyll-archives"
  gem "jekyll-sitemap"
end

# Windows 전용 gem
gem "tzinfo-data", platforms: [:mingw, :mswin, :x64_mingw, :jruby]
gem "http_parser.rb", "~> 0.6.0", platforms: [:jruby]

그리고 _config.yml에서도 정확한 플러그인 설정이 필요했습니다:

plugins:
  - jekyll-paginate
  - jekyll-redirect-from
  - jekyll-seo-tag
  - jekyll-archives
  - jekyll-sitemap

제 경험상, 로컬에서는 작동하는데 GitHub에서 안 되는 문제의 80%는 이 의존성 관리와 플러그인 설정 문제였습니다.

_config.yml의 기본 설정에서 자주 놓치는 부분들

블로그 운영을 시작하면서 또 다른 깨달음이 있었습니다. Jekyll의 핵심 설정 파일인 _config.yml에는 많은 함정이 있다는 것입니다.

예를 들어, Chirpy 테마를 사용할 때 다음 설정들이 반드시 필요합니다:

```yaml

Site settings

lang: ko-KR timezone: Asia/Seoul title: My Awesome Blog tagline: 은퇴 교수의 기술 블로그 url: “https://yourusername.github.io”

GitHub Pages 배포 설정

github: username: yourusername

댓글 설정

comments: active: disqus disqus: short