GitHub Pages로 웹사이트 배포하기
저장소 준비부터 정적 파일 배포, 경로 설정, 배포 후 점검까지 청소년 개발 프로젝트에서 사용하는 과정을 정리했습니다.
1. GitHub Pages가 무엇인가요?
GitHub Pages는 GitHub 저장소에 있는 HTML, CSS, JavaScript 파일을 정적 웹사이트로 공개하는 호스팅 기능입니다. 별도 서버 프로세스를 계속 실행하지 않아도 되므로 포트폴리오, 문서, 소개 페이지, 브라우저에서 동작하는 도구를 배포하기에 적합합니다. 반면 서버에서 실행되는 Node.js 프로그램이나 비밀 환경변수를 그대로 올려 실행하는 용도는 아닙니다.
2. 저장소 구조를 먼저 정리합니다
웹사이트의 시작 파일은 보통 index.html입니다. 공통 스타일은 CSS 파일로, 반복되는 동작은 JavaScript 파일로 분리하면 수정 범위를 줄일 수 있습니다. 이미지와 문서는 assets 또는 images 폴더에 모으고, 페이지가 많아지면 기능별 디렉터리를 만들어 구조를 명확히 합니다. 파일명은 영문 소문자와 하이픈을 사용하는 편이 운영체제별 대소문자 차이로 생기는 오류를 줄이는 데 도움이 됩니다.
3. 배포 설정과 경로를 확인합니다
저장소 설정에서 Pages 배포 원본 브랜치와 폴더를 지정합니다. 루트 도메인을 쓰는 저장소와 프로젝트 하위 경로를 쓰는 저장소는 상대 경로 동작이 다릅니다. 예를 들어 /assets/site.css 같은 절대 경로는 도메인 루트 기준으로 해석됩니다. 프로젝트 하위 경로에서 배포한다면 경로가 올바른지 실제 주소로 확인해야 합니다.
4. 배포 후 확인할 항목
메인 페이지가 열리는지만 확인해서는 부족합니다. 하위 페이지 직접 접속, 새로고침, 모바일 화면, 이미지 로딩, 브라우저 개발자 도구의 콘솔 오류, 네트워크 요청 실패를 각각 점검합니다. 특히 파일명을 바꾸거나 폴더를 이동한 뒤에는 내부 링크와 스크립트 경로가 이전 주소를 가리키지 않는지 검색해야 합니다.
5. 정적 사이트에 비밀 키를 두지 마세요
GitHub Pages에 공개된 HTML과 JavaScript는 방문자가 모두 내려받아 확인할 수 있습니다. API 비밀 키, 관리자 토큰, 데이터베이스 비밀번호를 프런트엔드 코드에 넣으면 안 됩니다. 비밀 정보가 필요한 작업은 Cloudflare Workers 같은 서버 측 환경에서 처리하고, 브라우저에는 공개해도 되는 값만 전달해야 합니다.
6. 업데이트를 안전하게 운영하기
작은 변경이라도 변경 목적이 드러나는 커밋 메시지를 남기고, 여러 파일을 한 번에 바꿀 때는 링크와 기능을 함께 검사합니다. 장애가 발생하면 마지막 정상 커밋과 비교해 원인을 좁힙니다. 배포가 완료되기까지 잠시 시간이 걸릴 수 있으므로 저장소의 Pages 배포 상태와 실제 사이트를 모두 확인하는 습관이 중요합니다.
7. 절대 경로와 상대 경로를 구분합니다
도메인 루트에 배포하는 사이트에서 /services/calc.html은 도메인 최상위 경로를 가리킵니다. 반면 ./services/calc.html은 현재 문서 위치를 기준으로 해석됩니다. 하위 폴더 안의 페이지에서 ../를 몇 번 사용해야 하는지 헷갈리면 브라우저 주소창의 최종 URL과 개발자 도구 Network 탭의 요청 주소를 확인합니다. 파일 이름의 대소문자도 실제 저장소와 정확히 일치해야 합니다.
CSS, JavaScript, 이미지 파일의 경로가 잘못되면 HTML은 열리지만 스타일이나 동작이 빠질 수 있습니다. 페이지 직접 접속, 새로고침, 내부 링크 이동을 각각 시험해야 하는 이유입니다.
8. 404와 캐시 문제를 구분합니다
새 파일을 추가했는데 404가 나타나면 먼저 기본 브랜치에 커밋됐는지, 파일 경로와 대소문자가 맞는지, Pages 배포가 완료됐는지 확인합니다. 배포 완료 후에도 이전 화면이 보이면 강력 새로고침이나 캐시 비활성화 상태에서 다시 확인합니다. 브라우저 캐시 문제인지 실제 배포 실패인지 구분하려면 다른 브라우저나 비공개 창에서도 같은 주소를 열어 봅니다.
사이트의 404 페이지는 사용자가 홈이나 서비스 목록으로 돌아갈 수 있도록 안내해야 합니다. 존재하지 않는 페이지로 연결되는 메뉴가 없는지도 주기적으로 확인합니다.
9. 변경 단위를 작게 유지하기
한 커밋에서 여러 기능을 동시에 바꾸면 문제가 생겼을 때 원인을 찾기 어렵습니다. 가능한 한 한 가지 목적에 맞춰 파일을 수정하고, 커밋 메시지에는 변경 이유를 적습니다. 변경 전후에 대표 화면을 비교하고, 링크·콘솔 오류·모바일 레이아웃·키보드 조작을 다시 확인합니다.
정적 사이트에는 서버 비밀 정보가 들어갈 수 없다는 점을 다시 확인하세요. 공개 저장소에 실수로 비밀 키를 커밋했다면 파일에서 지우는 것만으로 충분하지 않습니다. 해당 키를 즉시 폐기하거나 교체하고, 저장소 기록과 접근 권한도 점검해야 합니다.
참고 자료: GitHub Pages 공식 문서 · GitHub Pages 사이트 만들기