GitHub Pages로 정적 웹사이트 무료 배포하기

글: beautifulwind · 2026년 10월 29일 · 배포·호스팅

서버를 따로 빌리지 않아도 HTML 파일 몇 개만 있으면 누구나 볼 수 있는 웹사이트를 만들 수 있습니다. 이 글에서는 GitHub Pages로 정적 사이트를 배포하는 과정을 처음부터 끝까지, 실제로 자주 막히는 지점과 함께 정리합니다.

GitHub Pages가 적합한 경우

GitHub Pages는 저장소에 있는 파일을 그대로 웹에 공개해 주는 무료 호스팅입니다. 서버에서 코드를 실행하지 않기 때문에 PHP, Node.js 서버, 데이터베이스는 쓸 수 없습니다. 대신 HTML, CSS, JavaScript, 이미지처럼 요청하면 그대로 내려주는 파일만으로 이루어진 사이트라면 별다른 비용 없이 HTTPS까지 적용된 상태로 운영할 수 있습니다.

개인 블로그, 포트폴리오, 문서 사이트, 간단한 랜딩 페이지가 대표적인 사례입니다. 문의 폼이나 댓글처럼 서버가 필요해 보이는 기능도 외부 서비스를 붙이면 해결할 수 있는데, 이 부분은 서버 없이 문의 폼 만들기에서 따로 다룹니다.

저장소 준비하기

먼저 GitHub에 새 저장소를 만들고, 사이트의 첫 화면이 될 index.html을 저장소 최상위에 둡니다. 브라우저는 주소 끝에 파일 이름이 없으면 해당 폴더의 index.html을 찾기 때문에, 이 파일 이름은 반드시 지켜야 합니다.

my-site/
        ├── index.html
        ├── about.html
        ├── assets/
        │   ├── style.css
        │   └── main.js
        └── articles/
            └── first-post.html

파일 이름에는 영문 소문자, 숫자, 하이픈만 쓰는 편이 안전합니다. GitHub Pages는 대소문자를 구분하므로 About.html로 저장해 놓고 링크를 about.html로 걸면 404가 납니다. 로컬 Windows나 macOS에서는 대소문자를 구분하지 않아 잘 보이다가, 배포 후에만 깨지는 대표적인 원인입니다.

Pages 활성화하기

저장소의 Settings → Pages로 이동합니다.
Build and deployment의 Source를 Deploy from a branch로 둡니다.
Branch에서 main, 폴더는 / (root)를 선택하고 저장합니다.
1~2분 뒤 같은 화면 위쪽에 https://사용자이름.github.io/저장소이름/ 형태의 주소가 표시됩니다.

이후에는 main 브랜치에 커밋을 푸시할 때마다 자동으로 다시 배포됩니다. 진행 상황은 저장소의 Actions 탭에서 pages build and deployment 항목으로 확인할 수 있습니다. 배포가 끝났는데도 예전 화면이 보인다면 대부분 브라우저 캐시 때문이니 강력 새로고침(Windows는 Ctrl+Shift+R, macOS는 Cmd+Shift+R)을 해 보세요.

프로젝트 사이트의 경로 문제

저장소 이름이 사용자이름.github.io가 아니라면 사이트는 도메인 최상위가 아니라 /저장소이름/ 아래에 열립니다. 이때 가장 많이 하는 실수가 링크를 슬래시로 시작하는 절대 경로로 쓰는 것입니다.

작성한 경로	실제로 요청되는 주소	결과
`/assets/style.css`	`사용자이름.github.io/assets/style.css`	404 (저장소 이름이 빠짐)
`assets/style.css`	`사용자이름.github.io/저장소이름/assets/style.css`	정상
`../assets/style.css` (하위 폴더의 페이지에서)	`사용자이름.github.io/저장소이름/assets/style.css`	정상

따라서 프로젝트 사이트에서는 현재 파일 위치를 기준으로 한 상대 경로를 쓰는 것이 가장 단순합니다. 나중에 사용자 지정 도메인을 연결해 사이트가 최상위로 옮겨 가더라도 상대 경로는 그대로 동작합니다.

사용자 지정 도메인 연결

도메인을 가지고 있다면 Settings → Pages의 Custom domain에 도메인을 입력하고, 도메인 업체의 DNS 설정에서 레코드를 추가하면 됩니다.

www 같은 하위 도메인: CNAME 레코드를 사용자이름.github.io로 지정합니다.
루트 도메인(example.com): GitHub 문서에 안내된 GitHub Pages의 IP 주소들을 A 레코드로 등록합니다. IP 목록은 바뀔 수 있으므로 반드시 GitHub 공식 문서에서 최신 값을 확인하세요.

DNS 변경이 전파되기까지는 몇 분에서 길게는 하루 정도 걸립니다. 인증서가 발급되면 Enforce HTTPS를 켜 두는 것이 좋습니다. 또한 도메인을 연결하기 전에 GitHub 계정 설정에서 도메인 소유권 인증(Verified domains)을 해 두면, 다른 사람이 같은 도메인을 자기 저장소에 연결하는 문제를 막을 수 있습니다.

광고 플랫폼이나 검색 도구 중에는 사이트를 도메인 단위로 다루는 경우가 많습니다. 예를 들어 ads.txt는 도메인 최상위에 있어야 인식되므로, 장기적으로 운영할 사이트라면 처음부터 자신의 도메인을 연결하는 편이 유리합니다.

자주 겪는 문제

404 페이지만 보일 때

Pages 설정에서 선택한 브랜치와 폴더에 index.html이 실제로 있는지 확인하세요. docs 폴더를 선택해 놓고 파일은 최상위에 두는 경우가 흔합니다.

CSS가 적용되지 않을 때

개발자 도구(F12)의 Network 탭에서 CSS 요청이 404인지 확인합니다. 대부분 위에서 설명한 절대 경로 문제나 파일 이름의 대소문자 차이입니다.

밑줄(_)로 시작하는 폴더가 사라질 때

GitHub Pages는 기본적으로 Jekyll로 사이트를 처리하는데, Jekyll은 _로 시작하는 파일과 폴더를 무시합니다. 저장소 최상위에 빈 파일 .nojekyll을 추가하면 이 처리를 끌 수 있습니다.

정리

GitHub Pages 배포의 핵심은 세 가지입니다. 최상위에 index.html을 둘 것, 프로젝트 사이트라면 상대 경로를 쓸 것, 오래 운영할 사이트라면 사용자 지정 도메인을 연결할 것. 이 세 가지만 지키면 배포 과정에서 만나는 문제의 대부분을 피할 수 있습니다.