가비아 도메인과 GitHub Pages 연결 가이드

1. GitHub Pages의 동작 원리

GitHub Pages는 저장소(Repository)에 있는 HTML, CSS, JavaScript 파일들을 읽어들여 무료로 웹사이트를 호스팅해주는 서비스입니다.

기본 주소(github.io)로 배포하는 순서

커스텀 도메인 전에, 저장소를 GitHub Pages에 한 번 올려 두는 흐름입니다.

1. GitHub에 저장소를 만들고 index.html 등 정적 파일을 푸시합니다. (프로젝트 사이트면 보통 main 브랜치 루트 또는 설정한 /docs 폴더)
2. 저장소 Settings → Pages에서 Build and deployment의 소스로 브랜치(예: main)와 폴더를 지정하고 저장합니다.
3. 빌드·배포가 끝나면 안내에 나온 https://<사용자명>.github.io/<저장소명>/ 형태의 URL로 접속해 동작을 확인합니다.
4. 이후 이 문서의 3절처럼 Custom domain과 가비아 DNS를 추가하면 방문자에게는 구매한 도메인으로 보이게 할 수 있습니다.

왜 정적 파일만 가능할까?

웹 서버는 크게 두 가지 방식으로 동작합니다.

• 동적 서버 (Dynamic): 클라이언트의 요청이 오면 Python, Node.js, Java 등의 서버 코드가 실행되어 DB를 조회하고 실시간으로 HTML을 만들어 응답합니다.
• 정적 서버 (Static): 서버에서 코드를 실행하지 않습니다. 이미 완성되어 있는 파일(HTML, 이미지 등)을 요청받은 그대로 브라우저에 전달만 합니다.

GitHub Pages는 정적 서버(Static Server)의 역할만 수행합니다. 연산 자원이 드는 서버 사이드 코드 실행을 지원하지 않는 대신, 완성된 프론트엔드 파일들을 전 세계 사용자에게 빠르고 안정적으로 전달(CDN 역할)하는 데 최적화되어 있습니다.

2. 필수 인프라 지식: DNS와 레코드

브라우저는 영어로 된 도메인을 이해하지 못합니다. 실제 통신을 위해서는 도메인을 서버의 실제 IP 주소로 변환하는 과정이 필요하며, 이 역할을 DNS(Domain Name System)가 담당합니다.

DNS 레코드란?

DNS 서버에는 도메인 이름과 그에 해당하는 목적지 정보가 기록된 일종의 '연락처 목록'이 있습니다. 이를 DNS 레코드라고 부릅니다. 목적지의 형태(IP 주소인지, 다른 도메인 이름인지)에 따라 레코드의 종류가 달라집니다. 가장 대표적인 것이 A 레코드와 CNAME 레코드입니다.

3. 설정 프로세스 (양방향 연결)

도메인 연결은 한쪽만 하면 되지 않습니다. GitHub에서는 “이 호스트 이름으로 들어오면 이 저장소를 보여준다”고 등록하고, 가비아(DNS)에서는 “그 호스트 이름이 GitHub 쪽 IP/이름을 가리킨다”고 등록합니다. 순서는 보통 GitHub에 이름을 먼저 넣고, 같은 이름이 DNS에서도 맞게 가리키게 맞춥니다.

• 1
  GitHub: 수락할 주소 한 줄 등록

  배포할 저장소 → Settings → Pages → Custom domain에 실제로 쓸 주소를 그대로 넣고 저장합니다. 아래 패턴 A를 쓸 거면 example.com, 패턴 B를 쓸 거면 www.example.com·app.example.com·dns-test.example.com처럼 전체 FQDN을 넣습니다. (패턴 B에서는 루트 example.com만 넣지 않습니다.)

• 2
  가비아: 1번에 넣은 주소에 맞춰 DNS만 맞추기

  1번에 적은 이름이 루트(Apex)인지 서브도메인인지에 따라 가비아에서 할 일이 갈립니다. A 레코드와 CNAME은 바꿔 쓰는 게 아니라, 호스트 종류에 맞게 쓰는 것입니다. 루트와 www를 둘 다 쓰면 아래 두 칸을 함께 설정합니다.

  패턴 A — Apex (루트)

  언제: 명함·링크에 example.com처럼 앞에 아무 레이블도 없이 쓸 때. (서브도메인만 쓸 계획이면 이 칸은 생략 가능.)

  GitHub(1번): example.com

  가비아: A 레코드 네 개 — 호스트 @(또는 공란), 값은 아래 IP 각각 한 줄씩.

  선택: www.example.com도 열고 싶으면 CNAME 추가 — 호스트 www, 값 username.github.io. (끝 마침표는 업체 안내에 따름). www만 등록하고 루트는 비워 두면, 사용자가 example.com만 칠 때는 안 열릴 수 있어서, 루트를 쓰려면 이 A 레코드가 필요합니다.

  IP 복사

  185.199.108.153

  185.199.109.153

  185.199.110.153

  185.199.111.153

  패턴 B — 서브도메인

  언제: 항상 www.example.com, app.example.com, dns-test.example.com처럼 앞에 레이블이 붙은 주소만 쓸 때. www가 아니어도 됩니다. 이 경우 루트를 쓰지 않아도 되며, 1번에 넣은 FQDN과 방문자가 칠 주소가 같으면 됩니다.

  GitHub(1번): 예) dns-test.example.com — 적을 이름과 동일하게.

  가비아: CNAME — 호스트는 맨 앞 레이블만 (www, app, dns-test 등). dns-test.example.com 전체를 호스트 칸에 넣지 않습니다.

  값(Value):

  username.github.io.

  호스트 이름은 점(.)으로 이어진 레이블입니다. 명함·주소에는 보통 dns-test.example.com 또는 https://dns-test.example.com처럼 적고, DNS 패널의 호스트 칸에는 dns-test만 넣는 식으로 맞춥니다.

  CNAME 값에 넣으면 안 되는 것

  값에는 호스트 이름만 옵니다.

  https://username.github.io/repo-name/

  username.github.io/repo-name/

  username.github.io. — 저장소 경로(/repo-name/)는 DNS가 아니라 GitHub Pages가 Host 헤더와 저장소 설정으로 처리합니다.
• 3
  전파 확인 후 HTTPS

  DNS가 전 세계에 반영될 때까지 수 분~길면 하루 정도 걸릴 수 있습니다. Pages에 DNS가 정상으로 보이면 Enforce HTTPS를 켭니다. 아래 노란 박스도 같이 참고하세요.

4. 트래픽 흐름과 가상 호스팅 원리

전 세계 수많은 웹사이트가 동일한 GitHub IP(185.199.108.153)를 사용합니다. 그렇다면 GitHub 서버는 수많은 요청 중에서 어떻게 내 도메인(dy.com)을 찾아 정확히 내 저장소의 파일을 반환할까요?

핵심은 브라우저가 IP 주소로 통신을 시작할 때, HTTP 요청 정보 안에 Host: dy.com 이라는 헤더를 몰래 포함해서 보낸다는 것입니다.

GitHub의 웹 서버(Nginx, HAProxy 등)는 이 Host 헤더를 읽어들입니다. 수만 개의 사이트가 같은 IP로 들어오더라도, 헤더에 적힌 dy.com을 확인한 뒤 내부 스토리지에서 dy.com이 등록된 특정 저장소(Repository)의 폴더로 라우팅하여 해당 HTML 파일을 사용자에게 응답합니다. 이를 인프라 용어로 가상 호스팅(Virtual Hosting)이라고 합니다.

여러 저장소 중 어떤 사이트로 갈지는 어떻게 정해지나요?

GitHub Pages는 저장소마다 Settings → Pages → Custom domain에 등록된 호스트 이름을 전역으로 매핑합니다. 사용자가 example.com으로 접속하면 브라우저는 Host: example.com을 보내고, GitHub는 “이 호스트는 어느 저장소에 연결돼 있는가”를 조회해 해당 저장소의 게시 파일을 돌려줍니다.

같은 호스트 이름은 한 저장소에만 연결할 수 있습니다. 다른 저장소에 동일 도메인을 등록하면 충돌합니다. 프로젝트를 나누려면 game.example.com, docs.example.com처럼 서브도메인을 나누고, 각각 다른 저장소의 Custom domain에 대응하는 FQDN을 등록하면 됩니다.

username.github.io/repo-name/ 형태의 프로젝트 URL에서 보이는 repo-name은 DNS가 아니라 GitHub의 경로 라우팅입니다. 커스텀 도메인을 붙인 뒤에는 브라우저가 그 도메인으로 요청하고, GitHub이 해당 저장소 콘텐츠를 루트 경로로 제공합니다.

5. 자주 발생하는 문제 해결 (Troubleshooting)