GitHub Pages 사용법, 무료 배포부터 접속까지 직접 해 보니

새 폴더에 index.html 한 장을 만들어 커밋하고 공개 저장소로 올린 뒤 github pages를 켜 봤습니다. 주소가 실제로 200으로 답하기까지 40.8초가 걸렸어요. 저장소를 만들고 올리는 데는 6.7초, Pages를 켜는 명령은 1.5초였습니다. 모두 터미널 명령 다섯 단계라서 AI 코딩 에이전트에게 통째로 맡기기도 좋습니다.

따라 할 순서와 열릴 때까지 걸린 시간

순서는 이렇습니다. 모두 터미널에서 실행하고, GitHub CLI(gh)는 미리 로그인해 둬야 해요.

1. git과 gh의 버전을 확인합니다.
2. 새 폴더에서 main 브랜치로 저장소를 시작하고 index.html을 커밋합니다.
3. gh repo create로 공개 저장소를 만들고 곧바로 올립니다.
4. gh api로 Pages를 켜면서 main 브랜치의 루트(/)를 배포 원본으로 지정합니다.
5. 배포 상태가 built로 나오는지 확인합니다.

단계마다 걸린 시간은 아래 표와 같습니다. 4단계의 '열릴 때까지'는 명령이 끝난 뒤 페이지 주소를 5초마다 다시 요청해서 200이 나올 때까지 기다린 시간이에요.

명령을 실행하는 시간보다 Pages를 켠 뒤 페이지가 열리기를 기다린 시간이 가장 길었습니다. 그런데 늘 40초 안팎이면 열릴까요? 공식 문서는 변경 사항이 게시되기까지 최대 10분이 걸릴 수 있다고 안내합니다. 이 값은 한 번 잰 기록이니 기준점 정도로만 봐 주세요.

도식출처: 명령 실행 실측

함께 읽을 글

• 클라우드플레어(Cloudflare) Pages 사용법, 배포부터 접속까지 직접 해 보니
• 파이썬(Python) 설치 방법, 맥에서 첫 코드 실행까지 직접 해 보니
• 깃허브(GitHub) 사용법, 저장소 만들고 첫 커밋·푸시까지 직접 해 보니

단계별 명령과 출력은?

1. 도구 버전 확인

$ git --version && gh --version | head -1
git version 2.54.0
gh version 2.103.0 (2026-10-21)

2. 페이지 파일 커밋

git init -b main으로 처음부터 main 브랜치를 만들고, printf로 index.html 한 장을 써서 커밋합니다.

$ git init -b main && printf '<!doctype html>\n<html lang="ko"><head><meta charset="utf-8"><title>GitHub Pages 테스트</title></head>\n<body><h1>GitHub Pages 테스트 페이지</h1></body></html>\n' > index.html && git add index.html && git commit -m "페이지 추가"
./.git/ 안의 빈 깃 저장소를 다시 초기화했습니다
[main (최상위-커밋) fb337ad] 페이지 추가
 1 file changed, 3 insertions(+)
 create mode 100644 index.html

첫 줄은 폴더 안에 이미 있던 빈 저장소를 다시 초기화했다는 안내입니다. 커밋 자체는 종료 코드 0으로 정상 처리됐어요.

3. 공개 저장소 만들고 올리기

--public은 공개 저장소로 만들라는 뜻입니다. --source=.은 현재 폴더를, --remote=origin은 원격 이름을 지정하죠. 여기에 --push까지 붙이면 만들고 올리는 일이 명령 하나로 끝납니다.

$ gh repo create <저장소> --public --source=. --remote=origin --push
https://github.com/<계정>/<저장소>
branch 'main' set up to track 'origin/main'.
To https://github.com/<계정>/<저장소>.git
 * [new branch]      HEAD -> main

4. Pages 켜기

웹 화면 대신 API로 Pages를 켜고, 배포 원본을 main 브랜치의 /로 지정합니다. 끝에 붙은 --jq '.html_url'은 응답에서 사이트 주소만 뽑아 줘요.

$ gh api -X POST repos/<계정>/<저장소>/pages -f 'source[branch]=main' -f 'source[path]=/' --jq '.html_url'
https://<계정>.github.io/<저장소>/

명령은 1.5초 만에 끝났습니다. 하지만 출력된 주소가 200으로 답하기까지는 40.8초를 더 기다려야 했죠.

5. 배포 상태 확인

$ gh api repos/<계정>/<저장소>/pages --jq '.status + " " + .html_url'
built https://<계정>.github.io/<저장소>/

이번 측정에서는 주소가 열린 뒤 상태가 built로 나왔습니다. 확실히 하려면 페이지 주소가 200으로 답하는지도 함께 확인하세요. 이 과정에는 브라우저를 클릭하는 단계가 없어요. 그래서 AI 에이전트에게 "이 다섯 단계를 실행하고 5단계 출력이 built인지 확인해 줘"처럼 확인할 기준까지 함께 맡기면 좋습니다.

그런데 터미널보다 웹 화면이 편하다면 어떻게 할까요?

웹 화면에서 GitHub Pages 켜는 방법

Creating a GitHub Pages site 문서를 보면 저장소 웹 화면에서도 같은 설정을 할 수 있습니다.

1. 저장소 이름 아래에서 Settings를 누릅니다. 탭이 보이지 않으면 더보기(…) 메뉴에서 찾으면 됩니다.
2. 사이드바의 "Code, planning, and automation" 영역에서 Pages를 누릅니다.
3. "Build and deployment" 아래 "Source"에서 Deploy from a branch를 고릅니다.
4. 바로 아래 "Branch" 드롭다운에서 배포할 브랜치를 고릅니다.
5. 게시가 끝나면 "GitHub Pages" 아래의 Visit site를 눌러 사이트를 엽니다.

주소 형태는 저장소 이름에 따라 달라집니다. Quickstart for GitHub Pages는 저장소 이름을 username.github.io로 지어 사용자 사이트를 만드는 방법을 안내해요. 이번 측정처럼 일반 저장소에서 켜면 https://<계정>.github.io/<저장소>/ 주소가 나왔습니다.

도식출처: 근거를 바탕으로 코드가 그린 도식

어느 방법으로 켜든 무료로 쓰려면 먼저 확인해야 할 조건이 있습니다.

무료로 쓸 때 확인할 조건

• 저장소를 가진 계정이 GitHub Free나 GitHub Free for organizations를 쓴다면 저장소가 공개여야 합니다.
• Pages 사이트는 인터넷에 공개됩니다. 요금제가 허용해서 저장소를 비공개로 두더라도 사이트는 공개되니, 민감한 데이터는 게시 전에 지워 두세요.
• 사이트는 GitHub Actions 워크플로로 빌드·배포됩니다. Actions는 공개 저장소에서 무료이고, 비공개·내부 저장소는 월 무료 사용량을 넘으면 요금이 붙어요.
• PHP, Ruby, Python 같은 서버 측 언어는 지원하지 않습니다. 저장소에 올린 정적 파일만 게시돼요.

AI 에이전트와 함께 서버(백엔드)가 필요한 앱을 만들고 있다면, 그 앱을 통째로 Pages에 올릴 수는 없습니다. 이럴 때는 랜딩 페이지나 문서처럼 정적 파일로 된 부분만 Pages에 두는 쪽이 맞습니다.

진입 파일의 위치도 중요합니다. GitHub Pages는 index.html, index.md, README.md 가운데 하나를 진입 파일로 찾아요. 브랜치와 폴더로 배포한다면 이 파일이 배포 원본 폴더의 맨 위에 있어야 합니다. 예를 들어 원본이 main 브랜치의 /docs 폴더라면 진입 파일도 /docs 안에 둬야 하죠.

자주 하는 실수

• 사용자 사이트 이름: 사용자·조직 사이트는 저장소 이름이 <user>.github.io나 <organization>.github.io여야 합니다. 계정 이름에 대문자가 있으면 소문자로 바꿔 써야 해요.

• 진입 파일 위치: 배포 원본이 /docs인데 index.html을 루트에만 두면 진입 파일을 찾지 못합니다.

• Jekyll 기본 빌드: 브랜치에서 배포하면 기본으로 Jekyll이 사이트를 빌드합니다. 다른 정적 사이트 생성기를 쓴다면 문서는 GitHub Actions로 빌드·게시하길 권합니다. 그렇게 하지 않는다면 배포 원본 루트에 빈 .nojekyll 파일을 만들어 Jekyll 빌드를 끄고, 사이트는 쓰는 정적 사이트 생성기의 안내대로 로컬에서 빌드해 그 정적 결과물을 배포 원본에 올리세요.

• 자동 커밋의 함정: GITHUB_TOKEN을 쓰는 GitHub Actions 워크플로가 올린 커밋으로는 Pages 빌드가 시작되지 않습니다. 에이전트가 만든 워크플로로 배포를 자동화하고 있다면 먼저 이 부분을 확인해 보세요.

• 게시가 안 될 때: 브랜치 배포인데 사이트가 자동으로 게시되지 않는다면, 관리자 권한과 인증된 이메일을 가진 사람이 배포 원본에 push했는지 확인합니다. 1시간이 지나도 반영되지 않으면 Jekyll 빌드 오류 문서를 보면 됩니다.

• 저장소가 공개인가요? GitHub Free 계정에서는 필수입니다.

• 진입 파일이 배포 원본 폴더의 맨 위에 있나요?

• 배포 원본(브랜치와 폴더)을 제대로 지정했나요? 이번 측정에서는 main과 /였습니다.

• 상태 확인 명령의 출력이 built로 나오나요?

• 저장소에 공개되면 안 되는 데이터가 남아 있지는 않나요?

측정 조건과 한계

이번 기록은 2026-10-26 03:32 KST에 맥 한 대(darwin arm64, Node.js v22.23.1)에서 git 2.54.0과 gh 2.103.0으로 측정한 결과입니다. 공개 저장소의 main 브랜치 루트에 index.html 한 장만 올렸고, 명령은 한 번씩만 실행했어요.

그러니 40.8초라는 값은 시간대나 저장소 크기에 따라 달라질 수 있습니다. 게다가 주소를 5초 간격으로 확인했기 때문에, 실제로 열린 순간은 기록보다 조금 빨랐을 수도 있어요. 자기 환경의 값이 궁금하다면 같은 다섯 단계를 몇 번 돌려 보고, 4단계 뒤 기다린 시간을 비교해 보세요.