20. GitHub Pages — 무료로 웹사이트 배포하기

🎯 이 장의 목표

GitHub Pages가 무엇인지 이해한다
저장소를 정적 웹사이트로 배포한다
React 같은 앱을 빌드해 배포하는 흐름을 안다
커스텀 도메인과 SSH 인증을 설정한다

20.1 GitHub Pages란?

GitHub Pages는 GitHub 저장소의 파일을 무료로 웹에 호스팅해주는 서비스입니다. HTML/CSS/JS 같은 정적 파일을 올리면, 누구나 접속 가능한 웹사이트가 됩니다.

무료, 별도 서버 불필요
저장소에 push만 하면 자동 배포
개인 포트폴리오, 프로젝트 문서, 블로그, 데모 사이트에 적합

CODE

[저장소의 index.html]  ──배포──►  https://사용자명.github.io/저장소명/

💡 팁

정적(static)이란? 서버에서 매번 새로 만들어내는 게 아니라(동적), 미리 만들어진 파일을 그대로 보여주는 사이트입니다. 데이터베이스가 필요 없는 소개 페이지·문서·프론트엔드 앱에 적합합니다.

20.2 가장 간단한 사이트 만들기

1단계: 저장소에 HTML 파일 두기

BASH

mkdir my-site && cd my-site
git init

index.html 작성:

HTML

<!DOCTYPE html>
<html>
<head><title>My First Page</title></head>
<body>
  <h1>안녕하세요! 👋</h1>
  <p>GitHub Pages로 배포한 첫 사이트입니다.</p>
</body>
</html>

BASH

git add index.html
git commit -m "Add index page"

2단계: GitHub에 push

BASH

# (GitHub에서 저장소 생성 후)
git remote add origin https://github.com/사용자명/my-site.git
git push -u origin main

3단계: Pages 활성화

저장소 → Settings → Pages
Source: "Deploy from a branch" 선택
Branch: main, 폴더는 / (root) 선택 후 Save
잠시 기다리면 URL이 표시됩니다: https://사용자명.github.io/my-site/

그 주소로 접속하면 방금 만든 페이지가 보입니다! 🎉

20.3 사이트 종류 두 가지

GitHub Pages에는 두 종류가 있습니다.

종류	저장소 이름	URL
사용자/조직 사이트	`사용자명.github.io`	`https://사용자명.github.io/`
프로젝트 사이트	아무 이름	`https://사용자명.github.io/저장소명/`

💡 팁

포트폴리오 메인은 사용자 사이트(사용자명.github.io)로, 개별 프로젝트 데모는 프로젝트 사이트로 운영하는 경우가 많습니다.

20.4 React 앱 배포하기

React 같은 프레임워크는 소스 코드를 그대로 올리지 않고, 빌드(build)해서 나온 정적 파일을 배포합니다.

📌 핵심

용어 정리

React: 웹 화면(UI)을 효율적으로 만드는 인기 JavaScript 라이브러리.
프레임워크: 앱의 뼈대와 규칙을 미리 갖춰 둔 개발 도구 모음. 정해진 틀 위에서 내용만 채우면 됩니다.
Vite(비트): React 등으로 만든 앱을 빠르게 개발·빌드해주는 도구.

이들은 GitHub Pages와 무관하게 쓰이는 별도 도구로, 여기서는 "빌드 결과물을 Pages에 올린다"는 흐름만 이해하면 됩니다.

1단계: 앱 준비와 빌드

BASH

# 예: Vite로 React 앱 생성
npm create vite@latest my-react-app -- --template react
cd my-react-app
npm install

2단계: 배포 설정

배포 도구로 gh-pages 패키지가 널리 쓰입니다.

BASH

npm install --save-dev gh-pages

package.json에 추가:

JSON

{
  "homepage": "https://사용자명.github.io/my-react-app",
  "scripts": {
    "predeploy": "npm run build",
    "deploy": "gh-pages -d dist"
  }
}

📌 핵심

homepage 설정이 중요합니다. 프로젝트 사이트는 하위 경로(/my-react-app/)에서 동작하므로, 이를 알려줘야 이미지·링크 경로가 깨지지 않습니다. (Vite는 vite.config.js의 base 옵션으로도 설정합니다: base: '/my-react-app/')

3단계: 배포 실행

BASH

npm run deploy

이 명령은 앱을 빌드(predeploy)한 뒤, 결과물(dist 폴더)을 gh-pages라는 별도 브랜치에 push합니다. GitHub Pages 설정에서 Source 브랜치를 gh-pages로 지정하면 배포됩니다.

CODE

소스 코드(main 브랜치) ──빌드──► dist/ ──gh-pages 브랜치로 push──► 배포

💡 팁

요즘은 gh-pages 패키지 대신 GitHub Actions(13장)로 자동 배포하는 방식도 인기입니다. main에 push하면 Actions가 자동으로 빌드·배포하는 워크플로우를 구성할 수 있습니다.

20.5 인증 오류 해결: HTTPS 대신 SSH

배포·push 중 캐시된 자격 증명 때문에 인증 오류가 날 때가 있습니다. 이럴 때 HTTPS 대신 SSH 방식으로 바꾸면 깔끔하게 해결됩니다. (5장에서 소개한 그 SSH입니다.)

SSH 키 생성과 등록

BASH

# 1. SSH 키 생성
ssh-keygen -t ed25519 -C "your_email@example.com"
# (저장 위치·암호는 엔터로 기본값 진행 가능)

# 2. 공개 키 내용 복사
cat ~/.ssh/id_ed25519.pub

복사한 공개 키를 GitHub → Settings → SSH and GPG keys → New SSH key에 등록

BASH

# 4. 연결 테스트
ssh -T git@github.com

# 5. 원격 주소를 SSH 형식으로 변경
git remote set-url origin git@github.com:사용자명/저장소명.git

이후로는 토큰 입력 없이 push/배포가 됩니다. SSH 키는 한 번 등록하면 매번 인증할 필요가 없어 편리합니다.

20.6 커스텀 도메인 연결

사용자명.github.io 대신 직접 산 도메인(www.mysite.com)을 연결할 수 있습니다.

도메인 등록 업체(예: 가비아, Namecheap)에서 도메인 구매
DNS 설정에서 GitHub Pages를 가리키도록 레코드 추가
- 사용자 사이트: A 레코드를 GitHub Pages IP로
- 서브도메인(www): CNAME 레코드를 사용자명.github.io로
저장소 → Settings → Pages → Custom domain에 도메인 입력 후 Save
Enforce HTTPS 체크 (무료 SSL 인증서 자동 발급)

📌 핵심

잠깐, 도메인 용어

DNS(Domain Name System): 사람이 읽는 도메인 이름(mysite.com)을 컴퓨터가 쓰는 숫자 주소(IP)로 바꿔주는 인터넷의 "전화번호부".
A 레코드: 도메인을 특정 IP 주소로 연결하는 DNS 설정 항목.
CNAME 레코드: 도메인을 다른 도메인 이름으로 연결하는 항목(예: www를 사용자명.github.io로).
SSL 인증서: 사이트와 방문자 사이 통신을 암호화해 https://로 안전하게 접속되게 하는 디지털 증명서.

설정이 반영되면(DNS 전파에 시간이 걸릴 수 있음) 내 도메인으로 사이트에 접속됩니다.

💡 팁

저장소에 CNAME이라는 파일이 자동 생성되어 도메인이 기록됩니다. 이 파일을 지우면 도메인 연결이 풀리니 주의하세요.

20.7 마크다운으로 간단 페이지 만들기

코딩 없이 마크다운(README.md)만으로도 페이지를 만들 수 있습니다. GitHub Pages는 Jekyll이라는 정적 사이트 생성기를 내장하고 있어, 테마를 고르면 마크다운을 예쁜 웹페이지로 변환해줍니다.

💡 팁

마크다운(Markdown)은 #(제목), **굵게**, - 목록 같은 간단한 기호로 서식 있는 문서를 작성하는 경량 표기법입니다. 배우기 쉬워 README·문서·블로그에 널리 쓰입니다. Jekyll(지킬)은 이런 마크다운 글을 완성된 웹사이트로 자동 변환해주는 도구입니다.

저장소에 README.md 또는 index.md 작성
Settings → Pages → Theme chooser에서 테마 선택
자동으로 스타일이 적용된 페이지가 배포됨

문서·프로젝트 소개 페이지를 빠르게 만들 때 유용합니다.

20.8 실습: 포트폴리오 한 장 배포

BASH

# 1. 저장소 준비
mkdir portfolio && cd portfolio
git init

# 2. 페이지 작성
cat > index.html << 'EOF'
<!DOCTYPE html>
<html>
<head><title>홍길동 포트폴리오</title></head>
<body>
  <h1>홍길동</h1>
  <p>주니어 개발자입니다.</p>
  <a href="https://github.com/사용자명">GitHub</a>
</body>
</html>
EOF

# 3. 커밋 & push
git add .
git commit -m "Add portfolio page"
git remote add origin git@github.com:사용자명/portfolio.git
git push -u origin main

# 4. Settings → Pages에서 main 브랜치 배포 활성화
# → https://사용자명.github.io/portfolio/ 에서 확인!

20.9 이 장에서 배운 것 (요약)

GitHub Pages = 정적 파일을 무료로 웹 호스팅 (push만 하면 배포)
사용자 사이트(사용자명.github.io) vs 프로젝트 사이트(/저장소명/)
React 등은 빌드 후 결과물을 배포 (gh-pages 패키지 또는 Actions, homepage/base 설정 주의)
인증 오류 시 SSH 키로 전환하면 매번 인증 불필요
커스텀 도메인: DNS 설정 + Settings에 도메인 입력 + Enforce HTTPS
마크다운 + Jekyll 테마로 코딩 없이 페이지 생성 가능

✍️ 확인 문제

React 앱은 왜 소스 코드를 그대로 올리지 않고 빌드해서 배포하나요?
push 인증 오류가 반복될 때 HTTPS 대신 무엇으로 바꾸면 좋나요?
프로젝트 사이트의 URL 형태는 어떻게 되나요?

축하합니다! 이제 Git 내부 원리부터 협업·자동화·배포까지 모두 익혔습니다. 부록 치트시트로 전체를 정리하세요. → 99_부록-치트시트.md

← 이전19. Git 훅(Hooks) — 자동 검사 걸기다음 →부록 B — 기초 기술 용어 사전