깃허브 페이지(GitHub Pages)가 404로 뜨면 GitHub Docs가 정한 순서대로 일곱 곳을 봅니다. GitHub 상태 페이지, DNS 설정, 브라우저 캐시, index.html 파일, 폴더 내용, 사용자 지정 도메인, 저장소 설정 순서입니다.
직접 고칠 수 있는 곳은 주로 index.html 파일 이름·위치와 게시 원본으로 고른 브랜치·폴더입니다. 2026년 10월 23일 GitHub Docs 「404 오류 문제 해결」 문서를 직접 읽고 점검 순서를 그대로 옮겼습니다.
깃허브 페이지에 처음 올리는 법은 깃허브로 웹사이트 무료 배포하기에 정리했습니다. 이 글은 올렸는데 안 열릴 때만 다룹니다.
1. 깃허브 페이지 404, 무엇부터 확인하나요?
GitHub 상태 페이지부터 봅니다. 문서는 404가 보이면 먼저 GitHub의 상태 페이지(Status page)에 진행 중인 장애가 있는지 보라고 적었습니다. 내 잘못이 아닐 수도 있기 때문입니다.
- GitHub 상태 페이지 — 깃허브 쪽 장애가 있는가
- DNS 설정 — 내 도메인을 쓴다면 레코드가 맞는가
- 브라우저 캐시 — 비공개 사이트라면 캐시를 지웠는가
- index.html 파일 — 이름과 위치가 맞는가
- 폴더 내용 — 파일이 맨 위 폴더에 있는가
- 사용자 지정 도메인 — 도메인 설정이 맞는가
- 저장소 — 브랜치·권한·공개 설정이 맞는가
2. index.html 파일 이름과 위치 확인하기
깃허브 페이지는 사이트의 첫 화면 파일로 index.html을 찾습니다. 이 파일이 저장소에 없으면 404가 납니다. 이름은 대소문자까지 정확해야 합니다.
index.html 파일 이름은 대/소문자를 구분합니다. 예를 들어 Index.html은 작동하지 않습니다.
AI 도구나 노코드 도구에서 내려받은 파일 이름이 Index.html이나 index.HTML이면 소문자 index.html로 바꿔야 합니다. 영어판 문서는 다른 변형이 아니라 index.html이어야 한다고 적었습니다.
위치도 중요합니다. 이 파일은 게시 원본으로 고른 곳의 맨 위에 있어야 합니다. 게시 원본이 main 브랜치의 /docs 폴더라면 index.html도 main 브랜치의 /docs 폴더 바로 안에 있어야 합니다.
폴더째 올리면 index.html이 한 단계 안쪽 폴더에 들어갈 수 있습니다. 문서의 다섯째 점검 항목도 폴더 내용이 루트(맨 위) 폴더에 있는지 보라는 것입니다.
3. 게시 원본 브랜치와 폴더 다시 보기
게시 원본은 깃허브가 사이트를 만들 때 읽는 곳입니다. 브랜치(저장소 안의 작업 갈래)와 폴더를 고르는데, 폴더는 맨 위(/)나 /docs 둘 중 하나입니다.
확인하는 곳은 저장소 이름 아래 Settings → 왼쪽 Pages → 「Build and deployment」입니다. 「Source」에서 Deploy from a branch를 고르고, 브랜치와 폴더를 고른 뒤 Save를 누릅니다.
404 문서는 사이트를 게시하는 브랜치가 main 또는 기본 브랜치여야 한다고 적었습니다. 파일을 다른 브랜치에 올려 두고 게시 원본은 main으로 두면 사이트에 반영되지 않습니다.
/docs 폴더를 게시 원본으로 골라 놓고 나중에 그 폴더를 지우면 사이트가 빌드(사이트 파일을 만드는 과정)되지 않고, /docs 폴더가 없다는 오류 메시지가 뜹니다.
4. 올렸는데 반영이 안 될 때
먼저 기다려 봅니다. GitHub Docs는 변경 내용을 올린 뒤 사이트에 게시되기까지 최대 10분이 걸릴 수 있다고 적었습니다.
10분이 지나도 그대로라면 누가 올렸는지 봅니다. 브랜치에서 게시할 때 자동 게시가 안 되면, 관리자 권한과 확인된 메일 주소가 있는 사람이 올렸는지 보라고 문서는 안내합니다.
- 올린 사람이 깃허브 계정의 메일 주소를 인증하지 않았다
- 배포 키(deploy key)로 올리고 있다
GITHUB_TOKEN을 쓰는 GitHub Actions 워크플로가 올린 커밋이다(이 경우 Pages 빌드가 시작되지 않습니다)
저장소에 심볼릭 링크(다른 파일을 가리키는 바로가기 파일)가 들어 있다면 브랜치 게시가 아니라 GitHub Actions 워크플로로 게시해야 한다고 문서는 적었습니다.
5. 빌드 오류 메시지는 어디서 보나요
깃허브 페이지는 기본적으로 GitHub Actions 워크플로 실행으로 빌드되고 배포됩니다. 그래서 오류를 찾으려면 저장소의 워크플로 실행 기록에서 GitHub Pages 실행을 열어 봅니다.
브랜치에서 게시하는 경우 빌드에 실패하면 깃허브 계정의 기본 메일 주소로 메일이 옵니다. 메일함에서 빌드 실패 메일이 왔는지도 함께 봅니다.
오류가 났던 워크플로는 다시 실행할 수도 있다고 문서는 안내합니다. Jekyll(깃허브 페이지가 쓰는 사이트 생성 도구)로 만든 사이트라면, 올리기 전에 내 컴퓨터에서 먼저 시험해 오류를 고치라고도 권합니다.
6. 내 도메인과 저장소 설정 때문에 생기는 404
내 도메인을 붙인 사이트라면 CNAME 레코드가 저장소 이름 없이 사용자이름.github.io를 가리키는지 확인합니다. 도메인 쪽 값과 순서는 깃허브 페이지 도메인 연결, 내 주소 붙이기에 정리했습니다.
첫 화면은 열리는데 안쪽 링크가 다 깨진다면, 사용자 지정 도메인을 새로 붙였거나 떼어 냈기 때문일 수 있다고 문서는 적었습니다. 도메인을 바꿀 때 사이트가 다시 빌드되게 하는 것이 권장 해결책입니다.
- 저장소를 공개에서 비공개로(또는 반대로) 바꾸면 사이트 주소가 바뀌어, 다시 빌드될 때까지 링크가 끊깁니다
- 비공개 저장소로 사이트를 운영한다면 GitHub Pro·Team·Enterprise Cloud 구독이 살아 있는지 봅니다
- 저장소에는 관리자 권한이 있는 사람(예: 저장소 주인)이 올린 커밋이 있어야 합니다
여기까지 다 봤는데도 404가 계속되면, 문서는 GitHub Community의 Pages 분류에 질문을 올리라고 안내합니다.
7. 깃허브 페이지 404 점검 정리
- GitHub 상태 페이지에 장애가 있는지 봅니다
- 파일 이름이 소문자
index.html인지, 게시 원본 맨 위에 있는지 봅니다 Settings→Pages에서 브랜치·폴더를 다시 고르고Save를 누릅니다- 최대 10분 기다리고, 워크플로 실행 기록과 메일에서 빌드 오류를 봅니다
- 내 도메인을 붙였다면 CNAME 값과 저장소 공개 설정을 봅니다
어디에 올릴지부터 다시 고민된다면 웹사이트 배포 무료, 어디에 올릴까 총정리를 보세요. Vercel에서 빌드가 실패했다면 vercel 배포 오류, 빌드 실패 읽는 법이 이어집니다.
참고자료 (모두 2026년 10월 23일 확인)
- GitHub Docs 「GitHub Pages 사이트에 대한 404 오류 문제 해결」 — docs.github.com
- GitHub Docs 「GitHub Pages 사이트의 게시 소스 구성」 — docs.github.com
- GitHub Docs 「GitHub Pages 사이트에 대한 Jekyll 빌드 오류 정보」 — docs.github.com
#깃허브페이지 #GitHubPages #404오류 #깃허브페이지배포 #웹사이트배포
