깃허브 페이지 도메인 연결을 하려다 DNS 화면에서 멈췄다면 먼저 확인할 순서가 필요해요. 기본 배포, 레코드, HTTPS까지 한 번에 점검하면 원인을 훨씬 빨리 좁힐 수 있습니다.
GitHub Pages 도메인 연결 전 준비사항
개인 도메인은 별도의 도메인 등록기관에서 먼저 준비해야 해요. GitHub Pages는 정적 사이트를 배포하는 기능이지, 도메인 이름을 직접 발급해 주는 서비스는 아닙니다.
정적 사이트가 기본 주소에서 열리지 않는다면 깃허브 페이지 도메인 연결보다 배포 문제를 먼저 봐야 합니다. 사용자명.github.io 같은 기본 주소가 정상이어야 사용자 지정 주소도 확인할 수 있어요.
- 기본 주소 접속 여부를 확인합니다.
- 저장소 공개 범위와 Pages 사용 가능 상태를 봅니다.
- 배포 브랜치 또는 액션 배포 성공 여부를 확인합니다.
- 게시 소스와 생성 폴더가 맞는지 봅니다.
- 도메인 등록기관에서 DNS 관리 권한이 있는지 확인합니다.
- 실제 권한이 있는 DNS 제공업체와 네임서버를 확인합니다.
사용자 사이트와 조직 사이트는 보통 사용자명.github.io 저장소를 쓰고, 프로젝트 사이트는 사용자명.github.io/저장소 이름 구조를 씁니다. 이 차이는 나중에 기본 URL, 사이트 URL, 이미지 경로, 사이트 빌드 결과까지 영향을 줍니다. 그래서 저장소 설정과 페이지 설정 메뉴에서 게시 소스, 배포 브랜치, 자동화 워크플로 상태를 먼저 확인하는 습관이 필요했어요.
루트 주소와 www 주소의 구조 및 대표 URL 선택
도메인 업체 화면에서 `@`, 빈 호스트 칸, `example.com`은 보통 루트 도메인을 뜻합니다. 이 주소는 에이펙스 도메인 또는 네이키드 도메인이라고도 불러요. 깃허브 페이지 도메인 연결을 할 때 개인 도메인의 최상위 주소 연결을 원한다면 이 부분을 건드리게 됩니다.
반대로 `www`, `blog`, `docs`는 각각 별도의 호스트 이름을 가진 서브도메인입니다. `www.example.com`은 www 호스트를 쓰는 하위 주소 연결이고, `blog.example.com`도 다른 서브도메인입니다. 사용자 지정 주소를 넣기 전에 루트와 www 중 어떤 사이트 URL을 정규 도메인으로 쓸지 정해야 해요.
| 주소 유형 | 예시 | DNS에서 입력할 호스트 | 권장 역할 |
|---|---|---|---|
| 루트 도메인 | example.com | @ 또는 빈칸 | 대표 기본 URL로 사용 가능 |
| www 서브도메인 | www.example.com | www | 정규 도메인 또는 보조 이동 주소 |
| 기타 서브도메인 | blog.example.com | blog | 별도 섹션이나 문서 주소 |
| GitHub Pages 기본 주소 | 사용자명.github.io | 입력하지 않음 | 배포 확인용 기본 주소 |
루트 도메인과 www 호스트를 둘 다 운영하더라도 검색엔진에 보여 줄 정규 도메인은 하나가 좋아요. 주소 전달과 GitHub Pages의 URL 리디렉션을 동시에 걸면 이동이 겹칠 수 있으니, SEO 정규화 관점에서도 한쪽 흐름만 남기는 편이 깔끔했습니다.
A·AAAA·CNAME을 이용한 DNS 레코드 설정
A 레코드는 IPv4 주소를 가리키고, AAAA 레코드는 IPv6 주소를 가리킵니다. CNAME 레코드는 다른 호스트 이름을 가리켜요. DNS 설정 화면 이름은 달라도 DNS 레코드의 핵심은 호스트, 유형, 값, TTL 값입니다.
IP 주소는 바뀔 수 있으니 실제 입력 전에는 GitHub 공식 안내의 현재 값을 확인해야 합니다. 2026년 7월 20일 기준 공식 문서의 GitHub Pages IPv4 주소는 185.199.108.153, 185.199.109.153, 185.199.110.153, 185.199.111.153입니다.
| 연결 대상 | 호스트 입력값 | 레코드 유형 | 대상 값 | 입력 수 | 주의사항 |
|---|---|---|---|---|---|
| 루트용 A | @ 또는 빈칸 | A 레코드 | GitHub Pages IPv4 주소 | 4개 | 기존 A 레코드 충돌 확인 |
| 선택적 AAAA | @ 또는 빈칸 | AAAA 레코드 | GitHub Pages IPv6 주소 | 4개 | IPv6 주소까지 쓸 때 추가 |
| www용 CNAME | www | CNAME 레코드 | 사용자명.github.io | 1개 | 저장소 이름은 넣지 않음 |
| 기타 서브도메인용 CNAME | blog 등 | CNAME 레코드 | 사용자명.github.io | 1개 | 호스트 이름을 정확히 입력 |
| 제공업체 지원 시 ALIAS | @ 또는 빈칸 | ALIAS 레코드 | 사용자명.github.io | 1개 | A 레코드 대신 쓰는 방식 |
| 제공업체 지원 시 ANAME | @ 또는 빈칸 | ANAME 레코드 | 사용자명.github.io | 1개 | 지원 여부를 DNS 제공업체에서 확인 |
- 루트 호스트를 `@` 또는 빈칸으로 표시하는지 확인합니다.
- www 호스트에 CNAME을 한 개만 유지합니다.
- 같은 호스트의 충돌하는 A·CNAME을 제거합니다.
- TTL 값의 단위가 초인지 분인지 확인합니다.
- 클라우드플레어 설정을 쓴다면 초기 확인 단계에서 프록시 비활성화와 오렌지 구름 상태를 봅니다.
- CAA 레코드와 DNSSEC 설정이 인증서 확인 과정에 영향을 주는지 검토합니다.
DNS 설정을 저장해도 바로 결과가 보이지 않을 수 있어요. 기존 TTL 값과 캐시 때문에 DNS 전파 시간이 다릅니다. 도메인 등록기관과 DNS 제공업체가 다른 경우에는 네임서버가 어디를 보고 있는지도 함께 확인해야 깃허브 페이지 도메인 연결이 엉뚱한 곳에서 막히지 않습니다.
깃허브 페이지 도메인 연결과 CNAME 파일 확인
DNS 레코드와 GitHub의 사용자 지정 주소 입력이 둘 다 끝나야 연결 확인이 진행됩니다. DNS 설정만 바꾸고 저장소 설정을 놓치면 사용자 지정 주소가 적용되지 않습니다.
- 대상 저장소의 Settings를 엽니다.
- Pages 설정 메뉴로 이동합니다.
- 배포 브랜치 또는 액션 배포 상태를 확인합니다.
- 사용자 지정 주소 입력란에 대표 도메인을 입력합니다.
- 저장 후 DNS 확인 메시지를 점검합니다.
- 게시된 결과물에서 CNAME 파일 내용을 확인합니다.
CNAME 파일에는 프로토콜이나 경로 없이 도메인 이름 한 줄만 들어가야 합니다. 예를 들어 `https://example.com/about`이 아니라 `example.com`만 적는 식이에요. 깃허브 페이지 도메인 연결 후 사용자 지정 주소 입력란에 저장한 값과 CNAME 파일 내용이 다르면 사이트 빌드 때 혼선이 생길 수 있습니다.
배포 브랜치에서 바로 게시하는 정적 사이트라면 저장소 루트에 CNAME 파일이 남는지 보면 됩니다. 빌드 도구가 `public` 같은 폴더를 결과물로 쓰면 그 폴더에 CNAME 파일을 넣어야 할 수 있어요. Jekyll 설정을 쓰는 경우에는 _config.yml 파일의 주소 값도 함께 봤습니다. 자동화 워크플로와 액션 배포에서는 게시 소스마다 파일 유지 방식이 다르니 페이지 설정 메뉴에서 다시 확인하는 게 좋습니다.
도메인 소유권 확인과 apex·www 주소 통합
GitHub의 소유권 확인은 안내된 호스트 이름과 인증 토큰을 TXT 레코드에 넣는 방식입니다. 확인이 끝난 뒤에도 TXT 레코드를 유지하면 계정이나 조직 차원에서 개인 도메인을 더 안정적으로 관리할 수 있어요.
이 절차는 피싱 방지와 탈취 방지에 의미가 있습니다. 다른 Pages 사이트가 내 도메인을 임의로 사용자 지정 주소에 연결하는 위험을 낮추는 장치라고 이해하면 됩니다. 깃허브 페이지 도메인 연결을 오래 운영할 생각이라면 초기에 같이 해두는 편이 편했습니다.
| 대표 주소 선택 | DNS 구성 | GitHub 입력 주소 | 예상 이동 방향 |
|---|---|---|---|
| 루트 대표 | 루트 A 또는 ALIAS, www CNAME | example.com | www에서 루트로 URL 리디렉션 |
| www 대표 | 루트 A 또는 ALIAS, www CNAME | www.example.com | 루트에서 www 리디렉션 |
| 루트만 연결 | 루트 레코드만 구성 | example.com | 루트 주소만 사용 |
| 서브도메인만 연결 | www 또는 blog CNAME | www.example.com | 하위 주소 연결만 사용 |
도메인 등록기관의 주소 전달과 GitHub의 www 리디렉션을 겹치게 설정하면 반복 이동이 생길 수 있습니다. 최상위 주소 연결과 하위 주소 연결을 한 경로씩 점검하면서 정규 도메인을 정리하는 게 좋아요.
TLS 인증서 발급과 강제 HTTPS 활성화
TLS 인증서와 SSL 인증서는 일상 대화에서 비슷하게 쓰이지만, 실제 보안 연결은 TLS를 사용한다고 보면 됩니다. GitHub 화면에서 HTTPS 적용 상태를 볼 때도 이 흐름으로 이해하면 쉬워요.
렛츠인크립트 같은 인증 기관이 도메인 응답을 확인할 수 있어야 인증서 발급이 진행됩니다. 사용자 지정 주소 저장 직후 강제 HTTPS가 바로 켜지지 않는다면 DNS 확인과 TLS 인증서 준비가 끝날 때까지 기다려야 합니다.
- DNS 확인 완료 상태를 확인합니다.
- 인증서 발급을 기다립니다.
- HTTP와 HTTPS 주소를 각각 접속해 봅니다.
- 강제 HTTPS를 활성화합니다.
- 이미지·CSS·스크립트 주소를 HTTPS 또는 상대 주소로 바꿉니다.
SSL 인증서 갱신은 GitHub Pages에서 자동으로 처리되지만, DNS 구성이 유지되어야 합니다. 인증서 오류가 보이면 클라우드플레어 설정, CAA 제한, 프록시 상태를 확인하세요. HTTPS 적용 뒤에도 HTTP 자산을 불러오면 혼합 콘텐츠가 생깁니다. HSTS 정책이 적용된 브라우저에서는 이전 오류가 더 엄격하게 보일 수 있으니 보안 연결 점검은 여러 브라우저에서 해보는 편이 좋았습니다.
DNS 전파 상태와 실제 응답 확인
깃허브 페이지 도메인 연결에서 제일 답답했던 부분은 기다려야 하는지, 설정이 틀렸는지 구분하는 일이었어요. DNS 전파는 TTL 값과 각 통신 환경의 캐시 갱신 상태에 따라 다르게 보입니다.
- DNS 관리 화면에서 저장된 레코드를 다시 확인합니다.
- `dig example.com A`로 루트 IPv4 응답을 확인합니다.
- `dig www.example.com CNAME`으로 www 대상을 확인합니다.
- `nslookup example.com`으로 다른 방식의 응답을 비교합니다.
- 다른 네트워크와 외부 전파 상태 검사 도구에서 결과를 비교합니다.
| 확인 대상 | 명령 또는 방법 | 정상 결과 | 이상 결과의 의미 |
|---|---|---|---|
| A | dig 명령어로 A 조회 | GitHub Pages IP 주소 반환 | 루트 DNS 레코드 문제 가능 |
| AAAA | dig 명령어로 AAAA 조회 | IPv6 주소 반환 | 선택 레코드 누락 또는 값 오류 |
| CNAME | dig www.example.com CNAME | 사용자명.github.io 반환 | 중복 또는 잘못된 대상 |
| 권한 네임서버 | nslookup 명령어 또는 DNS 조회 | 현재 네임서버 응답 | 다른 DNS 제공업체 화면을 수정했을 수 있음 |
| 브라우저 접속 결과 | 시크릿 창과 다른 네트워크 | 새 사이트 표시 | 브라우저 캐시 또는 로컬 캐시 문제 |
DNS 조회는 정상인데 브라우저만 이전 화면을 보이면 브라우저 캐시나 로컬 DNS 캐시 갱신을 봅니다. 여러 DNS 서버가 이전 값을 반환하면 DNS 전파를 더 기다려야 해요. 터미널 확인과 전파 상태 검사를 같이 하면 연결 확인 실패 원인을 훨씬 좁힐 수 있습니다.
404·NXDOMAIN·인증서·리디렉션 오류 해결
사이트 접속 오류는 화면 메시지부터 나눠 보면 덜 헷갈립니다. 깃허브 페이지 도메인 연결에서 자주 만난 건 404 오류, NXDOMAIN 오류, 인증서 오류, 리디렉션 루프였습니다. 각각 확인 위치가 달라요.
404와 NXDOMAIN 및 자산 경로 문제
404 오류는 도메인은 도착했지만 보여 줄 파일을 못 찾을 때 자주 보입니다. 게시 소스, 루트의 `index.html`, 배포 결과의 CNAME 파일, 프로젝트 사이트의 기본 URL을 확인하세요. 프로젝트 사이트에서 사용자 지정 주소를 쓰면 `/저장소 이름/`을 기준으로 잡던 절대 경로가 달라질 수 있습니다. React, Jekyll, Hexo에서는 상대 경로와 절대 경로 차이 때문에 이미지나 링크 깨짐이 생기기도 했어요. NXDOMAIN 오류는 유효한 DNS 응답 자체를 찾지 못한 상태라 DNS 레코드와 네임서버부터 봐야 합니다.
인증서 오류와 반복 리디렉션 문제
인증서 오류는 DNS 확인 미완료, 중복 CNAME, A 레코드 충돌, CAA 제한, 프록시 설정과 관련될 수 있습니다. Cloudflare를 쓴다면 초기 점검 때 프록시 비활성화를 해보고, 외부 주소 전달과 GitHub Pages 이동 설정이 서로 같은 방향인지 확인합니다. GitHub Pages와 외부 서비스가 서로 HTTPS 또는 대표 주소 이동을 반복하면 리디렉션 루프가 생깁니다.
| 증상 | 가능한 원인 | 확인 위치 | 해결 방향 |
|---|---|---|---|
| 404 오류 | 게시 소스 또는 index 파일 누락 | Pages 설정과 배포 결과 | 게시 폴더와 파일 구조 수정 |
| NXDOMAIN 오류 | DNS 응답 없음 | 네임서버와 DNS 레코드 | 호스트와 대상 값 재입력 |
| 연결 확인 실패 | 잘못된 구성 또는 전파 대기 | GitHub 사용자 지정 주소 | 레코드 저장 후 다시 확인 |
| 인증서 오류 | 인증서 발급 미완료 | Pages HTTPS 영역 | DNS와 CAA 확인 후 대기 |
| HTTPS 선택 비활성 | 검증 미완료 | Pages 설정 메뉴 | 사용자 지정 주소 재저장 검토 |
| 리디렉션 루프 | 주소 전달 중복 | 도메인 업체와 GitHub | 이동 경로 하나만 유지 |
| 이미지·CSS 링크 깨짐 | 자산 경로 불일치 | 빌드 설정과 HTML | 상대 경로 또는 새 절대 경로 적용 |
| 간헐적 사이트 접속 오류 | 캐시 또는 서비스 영향 | 여러 네트워크와 깃허브 서비스 상태 | DNS부터 배포와 인증서 순서로 분리 |
로컬 설정이 정상인데 여러 환경에서 동시에 접속되지 않으면 깃허브 서비스 상태도 확인합니다. 한 번에 여러 값을 바꾸면 원인을 놓치기 쉬워요. DNS, 배포, 인증서 순서로 나누면 잘못된 구성, 레코드 충돌, 중복 CNAME, 링크 깨짐을 차분히 줄일 수 있습니다.
연결 후 도메인과 검색 노출 관리
도메인 만료가 생기면 DNS 설정과 인증서 갱신에도 영향이 갈 수 있습니다. 그래서 자동 갱신 상태, 결제 수단, 연락처는 연결 직후 바로 확인해 두는 게 좋아요.
저장소를 재배포하거나 빌드 구성을 바꿀 때 CNAME 파일이 빠지지 않는지도 봐야 합니다. 사용자 지정 주소가 사라지면 보안 연결과 사이트 URL 관리가 다시 흔들릴 수 있습니다.
- 도메인 만료일과 자동 갱신 상태를 확인합니다.
- 네임서버 및 DNS 설정 변경 이력을 남깁니다.
- CNAME 파일과 사용자 지정 주소 유지 여부를 봅니다.
- HTTP에서 대표 HTTPS 주소로 이동하는지 확인합니다.
- 구글 서치 콘솔의 검색엔진 색인 상태를 점검합니다.
- 새 사이트 URL 기준 사이트맵 제출 상태를 확인합니다.
깃허브 페이지 도메인 연결이 끝났다면 SEO 정규화도 같이 봐야 합니다. 구글 서치 콘솔에 개인 도메인 속성을 등록하고 검색엔진 색인과 사이트맵 제출 상태를 새 주소 기준으로 확인하세요. 연결 해제를 할 때는 GitHub Pages의 사용자 지정 주소를 먼저 제거한 뒤 불필요한 DNS 레코드를 정리하고, 이전 주소의 이동 정책도 함께 검토하는 편이 좋습니다.
깃허브 페이지 도메인 연결 마무리 점검
처음에는 DNS 화면의 용어가 제일 어렵게 느껴졌지만, 순서를 나누니 훨씬 단순해졌습니다. 기본 배포 확인, 대표 주소 선택, DNS 레코드 입력, GitHub 사용자 지정 주소 저장, HTTPS 적용, 오류 점검 순서로 보면 됩니다. 막히는 지점이 생기면 기다릴 문제인지 설정 문제인지 먼저 나눠 보세요. 이 기록이 개인 사이트를 직접 연결하는 과정에서 시행착오를 줄이는 데 도움이 되었으면 합니다.
