GitHub Pages 실전 가이드 — 커스텀 도메인부터 CI/CD까지

게시일: 2025년 8월 8일 · 14분 읽기

이 블로그 자체가 GitHub Pages다. 무료인데 이 정도면 충분하다

GitHub Pages는 거의 10년을 써왔다. 처음엔 설정이 복잡할 거라고 생각했지만, 요즘엔 정말 간단하다. 이 글에서는 처음부터 끝까지, GitHub Pages로 프로덕션 블로그를 운영하는 전 과정을 다룬다.

1단계: 리포지토리 설정

GitHub Pages를 활성화하려면 먼저 정확한 리포지토리 이름이 필요하다. username.github.io 형식이어야 한다. 이 경우 자동으로 main 브랜치가 배포된다.

# 리포지토리 생성 후 로컬에서
git clone https://github.com/yourusername/yourusername.github.io
cd yourusername.github.io

# 간단한 인덱스 파일 생성
echo "Hello World" > index.html

git add index.html
git commit -m "Initial commit"
git push origin main

이제 https://yourusername.github.io 에 접속하면 "Hello World"가 보인다. 정말 간단하다.

2단계: 커스텀 도메인 설정

GitHub Pages의 기본 주소(yourusername.github.io)가 마음에 들지 않으면 자신의 도메인을 사용할 수 있다.

GitHub 측 설정:

1. 리포지토리 Settings -> Pages로 이동
2. Custom domain 입력 필드에 yourdomain.com 입력
3. CNAME 파일이 자동으로 생성됨

DNS 설정:

도메인 구매처(가비아, Route53 등)의 DNS 관리에서 A 레코드를 추가한다:

A레코드:
185.199.108.153
185.199.109.153
185.199.110.153
185.199.111.153

또는 CNAME레코드:
yourusername.github.io

DNS 변경은 보통 15분에서 1시간이 걸린다. 변경이 완료되면 GitHub의 Pages 설정에서 도메인 확인이 완료된다고 표시된다.

3단계: HTTPS 자동 설정

커스텀 도메인을 설정한 후 GitHub Pages 설정을 다시 보면 "Enforce HTTPS" 옵션이 나타난다. 이를 활성화하면 Let's Encrypt 인증서가 자동으로 적용된다.

HTTPS 활성화 후에는 모든 HTTP 요청이 자동으로 HTTPS로 리다이렉트된다. 브라우저 주소창에 초록색 자물쇠 아이콘이 보인다.

4단계: GitHub Actions로 자동 배포

정적 파일만 커밋하기 싫으면 GitHub Actions로 빌드 자동화를 할 수 있다. 예를 들어 마크다운 파일을 커밋하면 자동으로 HTML로 변환되고 배포된다.

# .github/workflows/deploy.yml
name: Build and Deploy

on:
  push:
    branches: [main]

permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - uses: actions/setup-node@v3
        with:
          node-version: '18'

      - name: Install dependencies
        run: npm install

      - name: Build
        run: npm run build

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v1
        with:
          path: './dist'

  deploy:
    runs-on: ubuntu-latest
    needs: build
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - name: Deploy
        id: deployment
        uses: actions/deploy-pages@v1

이 워크플로우는:

1. main 브랜치에 푸시될 때마다 실행
2. Node.js 18 환경에서 npm install 실행
3. npm run build로 정적 파일 생성
4. dist 폴더를 GitHub Pages에 배포

Jekyll을 이용한 블로그

마크다운으로 블로그를 운영하려면 Jekyll을 쓰면 된다. GitHub Pages는 Jekyll을 기본 지원한다.

# jekyll 설치 (로컬)
gem install jekyll bundler

# 새 프로젝트 생성
jekyll new myblog
cd myblog

# 로컬 서버 실행 (포트 4000)
bundle exec jekyll serve

이제 _posts 폴더에 마크다운 파일을 추가하면 된다. 파일 이름 형식: YYYY-MM-DD-title.md

# _posts/2025-09-05-my-first-post.md
---
layout: post
title: "My First Post"
date: 2025-09-05
categories: blog
---

# Hello

This is my first post.

Jekyll은 이 마크다운을 HTML로 변환하고, 테마를 적용하고, RSS 피드까지 생성해준다.

정적 사이트 생성기 (Hugo, 11ty 등)

Jekyll 대신 다른 생성기를 쓰고 싶으면, GitHub Actions에서 빌드만 처리하면 된다.

# Hugo의 경우
- name: Setup Hugo
  uses: peaceiris/actions-hugo@v2
  with:
    hugo-version: latest

- name: Build
  run: hugo --minify

- name: Upload artifact
  uses: actions/upload-pages-artifact@v1
  with:
    path: './public'

GitHub Pages의 제한사항

알아야 할 제한들:

• 정적 파일만: 서버 로직이 필요하면 불가능
• 10GB 리포지토리 크기: 이미지를 많이 쓰면 금세 도달
• 빌드 시간 10분: 초과하면 실패
• 분당 요청 한도: 하지만 실제로 도달하기 어려움

이미지 최적화

저장소 크기를 줄이려면 이미지를 최적화해야 한다. 내 경험상 1MB 이상의 이미지는 눈에 띄는 차이가 없다.

# ImageMagick으로 이미지 최적화
convert large.jpg -quality 85 -resize 1200x optimized.jpg

# 또는 Node.js 패키지 사용
npm install -g imagemin-cli imagemin-mozjpeg
imagemin image.jpg --plugin=mozjpeg > optimized.jpg

SEO 최적화

GitHub Pages 사이트도 검색 엔진에 최적화할 수 있다. robots.txt를 루트에 추가한다:

# robots.txt
User-agent: *
Allow: /
Sitemap: https://yourdomain.com/sitemap.xml

그리고 Jekyll이나 빌드 스크립트에서 sitemap.xml을 생성하도록 설정한다.

GitHub Pages vs 다른 선택지

언제 GitHub Pages를 쓸까?

• 코드와 블로그가 함께 있으면 좋을 때
• 서버 비용이 부담스러울 때
• 정적 사이트로 충분할 때

언제 다른 플랫폼을 쓸까?

• API가 필요할 때 → Vercel, Netlify, Cloudflare Pages
• 트래픽이 많을 때 → Cloudflare Pages (대역폭 무제한)
• Next.js를 쓸 때 → Vercel

실제 운영 경험

이 블로그는 GitHub Pages에서 3년을 운영했다. 단 한 번도 다운타임이 없었다. 푸시하면 몇 초 안에 배포된다. 트래픽 폭증도 자동으로 처리된다.

유일한 불편은 서버 로직이 필요한 상황인데, 그럴 때는 별도의 API 서버(Cloudflare Workers, AWS Lambda 등)를 연결하면 된다.

결론: GitHub Pages는 오래 개발해 온 내 기준에서도 여전히 개인 블로그로 쓰기에 충분하다.