GitHub Pages란: 무료 정적 사이트 배포를 단계별로 설명합니다

GitHub Pages란

GitHub Pages는 GitHub에 내장된 무료 정적 사이트 호스팅입니다. 사이트 파일을 일반 Git 저장소에 보관하면, GitHub가 이를 HTTPS로 제공합니다. 해당 브랜치에 git push를 할 때마다 사이트가 갱신되므로, 별도의 FTP나 호스팅 관리 화면, 수동 파일 업로드가 필요 없습니다.

GitHub Pages는 "깃허브 페이지스", "GitHub Pages", "git pages" 등 여러 방식으로 검색됩니다. 정확한 이름은 GitHub Pages이며, 이는 Git 자체가 아니라 GitHub 플랫폼의 기능입니다. Git은 변경 기록만 저장할 뿐, 무엇인가를 게시하지는 않습니다.

GitHub Pages는 주로 프로젝트 문서, 개인 홈페이지와 포트폴리오, 블로그, 랜딩 페이지, 그리고 React, Vue, Svelte로 빌드한 프론트엔드 데모를 올리는 데 쓰입니다.

Git Pages는 정적 파일 호스팅입니다

핵심 단어는 "정적(static)"입니다. GitHub Pages는 HTML, CSS, JavaScript, 이미지, 폰트, JSON처럼 완성된 파일을 브라우저에 그대로 전달합니다. 서버에서 코드를 실행하지는 못합니다. PHP, Python, 서버 측 Node.js, 데이터베이스는 동작하지 않습니다. 회원 가입, 장바구니, 데이터베이스 기반 관리자 페이지가 필요하다면 일반 호스팅이나 클라우드 플랫폼이 필요합니다.

다만 브라우저에서 실행되는 JavaScript는 평소처럼 동작합니다. 싱글 페이지 애플리케이션은 외부 API를 호출할 수 있고, 폼은 외부 서비스를 통해 전송할 수 있으며, 사이트 내 검색도 클라이언트에서 구현할 수 있습니다.

GitHub Pages 사이트의 세 가지 유형

GitHub Pages에는 세 가지 유형의 사이트가 있으며, 유형에 따라 주소가 달라집니다.

사용자 사이트와 조직 사이트는 계정마다 하나만 만들 수 있습니다. 프로젝트 사이트는 저장소마다 하나씩 원하는 만큼 만들 수 있습니다. 개인 사이트의 저장소 이름은 GitHub 아이디와 정확히 같아야 합니다. 아이디가 ivan-petrov라면 저장소 이름은 ivan-petrov.github.io입니다.

공개 저장소에서는 무료 요금제로 Pages를 쓸 수 있습니다. 비공개 저장소에서 사이트를 게시하려면 유료 요금제가 필요합니다. 다만 게시된 사이트 자체는 인터넷의 누구나 볼 수 있습니다.

GitHub Pages로 사이트 배포하는 단계

가장 간단한 방법을 살펴보겠습니다. 완성된 HTML 파일을 브랜치에서 바로 배포하는 방식입니다. GitHub 계정과 설치된 Git이 필요합니다.

1단계. 저장소 만들기

GitHub에서 새 공개 저장소를 만듭니다. 개인 사이트라면 이름을 username.github.io로 정하세요. 프로젝트 사이트라면 이름은 자유입니다. 그다음 저장소를 clone하고 첫 페이지를 추가합니다.

git clone https://github.com/username/username.github.io.git
cd username.github.io
echo "<h1>Hello, GitHub Pages</h1>" > index.html

메인 페이지는 반드시 index.html이라는 이름이어야 합니다(index.md나 README.md도 GitHub가 메인 페이지로 인식합니다). 대소문자는 구분됩니다. Index.html로는 동작하지 않습니다.

2단계. 파일을 GitHub에 보내기

git add index.html
git commit -m "첫 페이지 추가"
git push origin main

처음 push하면서 Git이 아이디와 비밀번호를 묻는다면, 개인 액세스 토큰이나 브라우저 로그인을 사용하세요. GitHub 계정의 비밀번호로는 HTTPS 방식의 git push가 되지 않습니다.

3단계. 설정에서 Pages 켜기

GitHub에서 저장소를 열고 Settings로 들어간 뒤, 왼쪽 메뉴에서 Pages를 선택합니다. Build and deployment 항목의 Source에서 Deploy from a branch를 고릅니다. 그 아래에서 브랜치(보통 main)와 폴더를 지정합니다. 폴더는 루트인 / (root) 또는 /docs를 고를 수 있습니다. 마지막으로 Save를 누르세요.

/docs 폴더는 저장소에 프로젝트 코드가 있고, 문서 사이트를 별도의 디렉터리에 두고 싶을 때 편리합니다.

4단계. 배포될 때까지 기다리기

배포에는 몇 초에서 몇 분이 걸립니다. GitHub는 처음 배포할 때 최대 10분까지 걸릴 수 있다고 안내합니다. 빌드 진행 상황은 Actions 탭에서 볼 수 있으며, pages build and deployment라는 프로세스가 나타납니다. 초록색 체크 표시가 뜨면 Settings → Pages에 사이트 주소가 표시됩니다.

이후에는 파일을 수정하고 commit한 뒤 git push만 하면 사이트가 자동으로 갱신됩니다.

GitHub Actions로 배포하기

브랜치에서 배포하는 방식은 저장소에 완성된 파일이 있을 때 적합합니다. 사이트를 먼저 빌드해야 한다면, 예를 들어 Vite, React, Hugo 같은 도구를 쓴다면, Source에 GitHub Actions를 선택하는 편이 좋습니다. Settings → Pages의 Source에서 GitHub Actions를 고르면 GitHub가 워크플로 템플릿을 제안합니다.

빌드 후 dist 폴더의 정적 파일을 배포하는 최소한의 워크플로는 다음과 같습니다.

name: Deploy to Pages
on:
  push:
    branches: [main]
permissions:
  contents: read
  pages: write
  id-token: write
jobs:
  deploy:
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npm run build
      - uses: actions/configure-pages@v5
      - uses: actions/upload-pages-artifact@v3
        with:
          path: dist
      - id: deployment
        uses: actions/deploy-pages@v4

이 파일은 .github/workflows/pages.yml에 둡니다. git push를 하면 Actions가 의존성을 설치하고, 프로젝트를 빌드한 뒤 dist의 내용을 배포합니다. 이 방식의 장점은 저장소에 소스 코드만 두고, 빌드 결과물로 커밋 기록이 부풀지 않는다는 점입니다.

프로젝트 사이트에서 흔히 빠지는 함정은 경로입니다. 사이트는 /저장소이름/ 주소에서 열리지만, 빌드 도구는 기본적으로 리소스를 루트 /에서 참조합니다. 그 결과 페이지가 스타일과 스크립트 없이 표시됩니다. 기본 경로(base path)를 설정하면 해결됩니다. Vite에서는 base: '/저장소이름/'을 지정하고, 다른 빌드 도구에도 비슷한 옵션이 있습니다.

Jekyll과 기타 정적 사이트 생성기

브랜치에서 배포할 때 GitHub는 기본적으로 파일을 Jekyll(Ruby로 작성된 정적 사이트 생성기)에 통과시킵니다. 그래서 페이지를 Markdown으로 쓰고 테마와 템플릿을 적용할 수 있으며, GitHub가 이를 HTML로 변환해 줍니다. 블로그나 문서에 편리합니다. .md 파일을 작성하면 디자인은 테마가 담당합니다.

부작용도 있습니다. Jekyll은 밑줄(_)로 시작하는 파일이나 폴더, 예를 들어 _next나 _assets를 무시합니다. 다른 도구로 빌드한 사이트에서 그런 폴더가 필요하다면, 루트에 빈 .nojekyll 파일을 두세요.

touch .nojekyll
git add .nojekyll
git commit -m "Jekyll 비활성화"
git push

Hugo, Astro, Eleventy, MkDocs, Docusaurus 같은 다른 생성기는 GitHub Actions를 통해 동작합니다. 워크플로에서 빌드하고, 완성된 폴더를 배포하는 방식입니다. GitHub Pages 자체는 이런 도구를 알 필요가 없고, 최종 파일만 있으면 됩니다.

GitHub Pages에 독립 도메인 연결하기

username.github.io 주소는 학습용 프로젝트에 충분하지만, 포트폴리오나 프로젝트에는 독립 도메인이 더 좋습니다. 설정은 도메인 등록 업체와 저장소 설정 양쪽에서 해야 합니다.

DNS 설정

www.example.com이나 blog.example.com 같은 서브도메인에는 username.github.io를 가리키는 CNAME 레코드를 만듭니다. 루트 도메인 example.com에는 GitHub Pages의 IP 주소를 가리키는 A 레코드를 만듭니다.

185.199.108.153
185.199.109.153
185.199.110.153
185.199.111.153

AAAA 레코드용 IPv6 주소를 포함한 최신 목록은 GitHub 문서에 있습니다. 설정하기 전에 꼭 확인하세요. 루트 도메인과 www를 모두 설정하는 것이 좋습니다. 그러면 GitHub가 한쪽 주소를 다른 쪽으로 리다이렉트해 줍니다.

저장소 설정

Settings → Pages의 Custom domain 칸에 도메인을 입력하고 저장합니다. 브랜치에서 배포하는 경우 GitHub가 도메인 이름이 적힌 CNAME 파일을 저장소에 만듭니다. Actions로 배포하는 경우에는 CNAME 파일이 필요 없으며, 도메인은 설정에 저장됩니다.

GitHub는 계정 설정(프로필 설정의 Pages 섹션)에서 도메인을 인증하도록 권장합니다. DNS가 GitHub를 가리키는 동안 다른 사람이 자신의 저장소에 내 도메인을 연결하는 상황을 막아 줍니다. DNS 변경은 최대 하루가 걸릴 수 있으므로, 바로 동작하지 않으면 조금 기다리세요.

GitHub Pages의 HTTPS

*.github.io 주소에서는 HTTPS가 항상 켜져 있습니다. 독립 도메인의 경우, DNS가 올바르게 설정되면 GitHub가 Let's Encrypt 인증서를 자동으로 발급합니다. 그러면 Settings → Pages에 Enforce HTTPS 항목이 나타나는데, 이를 체크하면 모든 HTTP 요청이 HTTPS로 리다이렉트됩니다.

체크 상자가 비활성화되어 있다면 인증서가 아직 발급되지 않은 것입니다. DNS 레코드를 확인하고 기다리세요. Custom domain 칸에서 도메인을 지웠다가 다시 추가하면, 인증서 재발급이 시작되는 경우도 있습니다. 또한 이미지나 스크립트를 http://에서 불러오고 있지 않은지도 확인하세요. 브라우저는 이런 리소스를 혼합 콘텐츠로 보고 차단합니다.

GitHub Pages의 제한 사항

호스팅은 무료지만 몇 가지 한계가 있습니다. GitHub 문서에 명시되어 있으며, 개인이나 학습용 사이트라면 대부분 충분합니다.

기술적 한도 외에 이용 약관도 있습니다. GitHub Pages는 온라인 쇼핑몰이나 SaaS 같은 상업 서비스, 대용량 파일 배포에는 적합하지 않습니다. 포트폴리오, 문서, 블로그, 프로젝트 랜딩 페이지라면 문제없습니다.

또 다른 제한은 서버 설정이 불가능하다는 점입니다. 직접 리다이렉트 규칙, 응답 헤더, .htaccess 같은 규칙은 쓸 수 없습니다. 루트에 404.html이라는 자체 페이지를 두는 것은 가능합니다. 존재하지 않는 주소에 접근하면 GitHub가 그 페이지를 보여 줍니다.

자주 생기는 문제와 해결 방법

GitHub Pages에서 404 오류가 나요

가장 흔한 원인은 배포 소스로 선택한 폴더에 index.html이 없는 것입니다. 올바른 브랜치와 폴더(/ (root) 또는 /docs)를 골랐는지, 파일 이름이 소문자 index.html인지 확인하세요. 두 번째 원인은 사이트가 아직 배포되지 않은 것입니다. Actions 탭을 열고 빌드가 끝날 때까지 기다리세요.

싱글 페이지 애플리케이션의 내부 페이지에서 새로고침할 때 404가 나면, 라우팅 문제입니다. 예를 들어 /about 파일이 없어서 서버가 그 주소를 찾지 못하는 것입니다. 해결 방법은 해시 라우팅(/#/about)을 쓰거나, index.html 사본을 404.html이라는 이름으로 두는 것입니다.

사이트가 갱신되지 않아요

먼저 변경 사항이 실제로 GitHub에 도착했는지 확인하세요. git status와 git log origin/main --oneline -3을 실행합니다. 그다음 Actions 탭을 엽니다. 빌드가 실패했다면 빨간 X 표시와 오류 로그가 있습니다. Jekyll 파일의 문법 오류나 워크플로의 잘못된 설정이 원인인 경우가 많습니다.

빌드는 성공했는데 브라우저에 예전 버전이 보인다면 캐시가 원인입니다. GitHub Pages는 몇 분 동안 파일을 캐시하고, 브라우저도 캐시합니다. 캐시를 지우고 새로고침(Ctrl+F5 또는 Cmd+Shift+R)하거나, 시크릿 창에서 여세요.

스타일이나 이미지가 불러와지지 않아요

거의 항상 경로 문제입니다. 프로젝트 사이트에서 /style.css로 링크하면, 저장소 폴더가 아니라 username.github.io의 루트를 가리킵니다. 상대 경로(style.css, ./img/logo.png)를 쓰거나, 빌드 도구에 기본 경로를 설정하세요. 파일 이름의 대소문자도 확인하세요. Windows에서는 Logo.PNG와 logo.png가 똑같이 동작하지만, GitHub 서버는 둘을 구분합니다.

밑줄로 시작하는 폴더가 배포되지 않아요

Jekyll의 동작입니다. _app 같은 폴더는 게시되지 않습니다. 루트에 .nojekyll 파일을 추가하거나, GitHub Actions 배포로 바꾸세요.

정리

GitHub Pages는 정적 사이트를 무료로 배포하는 가장 빠른 방법입니다. 저장소를 만들고, index.html을 넣고, Settings → Pages에서 소스를 고르면 몇 분 뒤 username.github.io에서 사이트를 열 수 있습니다. 빌드가 필요한 사이트에는 GitHub Actions를, 독립 도메인에는 DNS 레코드와 Enforce HTTPS를 사용하세요. 한계도 기억해 두세요. 정적 콘텐츠만 다룰 수 있고, 서버 측 코드는 실행되지 않으며, 크기와 트래픽에 상한이 있습니다. GitHub 작업, 변경 사항 전송, 자동화는 Git 강의에서 실습으로 다룹니다.