처음하는 클로드코드 Part2 × GitHub Pages 배포 — 비주얼 가이드

WHY

왜 GitHub Pages인가요?

랜딩페이지 · 포트폴리오 · 이벤트 페이지를
인터넷 주소(URL)로 누구나 접속할 수 있게 만들려면 배포가 필요합니다
GitHub Pages는 그중 가장 입문자 친화적인 선택입니다

무료 — 비용 0원
HTML / CSS / JS만 있으면 바로 배포 — 별도 서버 설정 불필요
URL 자동 생성 — https://[사용자명].github.io/[저장소이름]/
수정도 간단 — 파일만 갱신하면 자동 반영

단점도 알아두기

• 정적(static) 페이지만 가능 — 회원가입 · 결제 · DB 같은 동적 기능 X

• 무료 트래픽 · 용량 한도가 있긴 하지만 개인 페이지 수준에선 거의 무한 (월 100GB)

FLOW

전체 흐름 한눈에

당신이 만져야 할 건 단 3단계뿐입니다

당신이 직접 할 일

GitHub 가입 (5분)
Personal Access Token 발급
Claude Code에 한 줄 요청

그 후

Claude가 작업 후 접속 URL 알려줌
그 URL을 브라우저에서 열기
첫 배포 직후엔 1~10분 정도 기다리면 페이지가 살아납니다

STEP 01

GitHub 계정 만들기

이미 가입되어 있다면 건너뛰기
처음이라면 5분이면 됩니다

가입 절차

github.com 접속 → 우측 상단 Sign up
이메일 · 비밀번호 · 사용자명 (username) 입력
이메일로 온 인증 코드 입력
무료 플랜(Free) 선택

로그인 후 Dashboard — 이 화면이 보이면 가입 · 로그인 OK (개인 정보는 모자이크 처리)

사용자명 정할 때 주의

사용자명은 URL에 그대로 들어갑니다

예) 사용자명이 kim-minsu → 페이지 URL: https://kim-minsu.github.io/...

회사용 · 포트폴리오용이면 단정한 영문 이름을 추천. 한글 · 공백 · 특수문자 X

STEP 02

Personal Access Token
(PAT) 발급

Claude Code가 GitHub 작업을 본인 대신 하려면
열쇠(토큰)가 필요합니다

발급 절차 — 5단계

GitHub 로그인 후 우측 상단 프로필 사진 클릭 → Settings

우측 상단 프로필 클릭 → 드롭다운 메뉴에서 Settings 선택

Settings 페이지 좌측 메뉴 맨 아래 Developer settings

Settings 페이지 좌측 메뉴 맨 아래 Developer settings

Settings 화면 — 좌측 메뉴를 맨 아래로 스크롤해서 Developer settings 클릭

Personal access tokens → Tokens (classic) 클릭

Developer settings 좌측 Personal access tokens → Tokens (classic)

Developer settings 화면 — 좌측 메뉴의 Personal access tokens 펼친 뒤 Tokens (classic) 클릭

우측 상단 Generate new token → Generate new token (classic)

Tokens (classic) 페이지 — Generate new token 버튼

Tokens (classic) 목록 — 우측 상단 Generate new token 클릭

아래 항목 입력:
- Note (메모) — claude-code-deploy 같이 알아볼 수 있는 이름
- Expiration (만료) — 90 days 추천 (보안상 영구토큰 비추)
- Select scopes (권한)
  - repo 체크 (저장소 생성 · 읽기 · 쓰기, Pages 활성화 포함)
  - workflow 체크 (선택, GitHub Actions도 쓸 거면)
페이지 맨 아래 Generate token 클릭
ghp_로 시작하는 긴 문자열이 화면에 나타남 → 즉시 복사

New personal access token 폼 — Note → Expiration → repo · workflow 체크 → Generate 순서

입력 완료 모습 — Note "claude-code-deploy" + repo · workflow 체크 → 맨 아래로 스크롤 후 Generate

토큰은 발급 직후 한 번만 보입니다

페이지를 떠나면 다시 못 봅니다

메모장이나 비밀번호 매니저에 즉시 저장하세요

잃어버리면 새로 발급해야 합니다 (이전 건은 폐기 가능)

보안 주의 사항

• 토큰은 비밀번호와 같은 등급의 정보 — 깃에 같이 커밋 X, 공개 채팅 · 이슈에 붙여넣기 X

• 실수로 노출됐다면 즉시 GitHub에서 해당 토큰 Delete(삭제) → 새 토큰 발급

• 만료 기간이 90일이면 그때 자동 만료되니 잊고 있어도 비교적 안전

STEP 03

Claude Code에
한 줄 요청이면 됩니다

이제부터는 본인이 할 일은 프롬프트 한 번
나머지는 Claude가 알아서 처리합니다

프롬프트 만들기

아래 3개 항목만 채우면 두 가지 버전의 프롬프트가 자동으로 생성됩니다. 복사 버튼으로 바로 Claude Code에 붙여넣으세요

YOUR INPUTS

파일명 GitHub 토큰 GitHub 사용자명 저장소 이름

기본 프롬프트

더 짧게

수정 후 다시 올리기

저장소 삭제

Claude 작업이 끝나면 접속 URL을 알려줍니다

그 URL을 브라우저에서 열면 페이지를 확인할 수 있습니다

단, 처음 배포 직후엔 GitHub 내부 처리에 시간이 걸려서 바로 안 보일 수 있습니다 — 1~10분 정도 기다린 뒤 다시 접속해보세요

막히는 게 있으면 Claude가 되묻습니다

예) 토큰 권한이 부족하면 "repo scope가 필요해 보인다" 같은 식으로 알려줍니다

STEP 04

배포 결과 확인하기

Claude가 알려준 URL을 브라우저에 입력하면
페이지가 보입니다

URL 패턴

https://[사용자명].github.io/[저장소이름]/

예: https://kim-minsu.github.io/my-landing/

바로 안 보이는 게 정상입니다

GitHub 내부 처리에 시간이 걸려서 최대 1~10분 정도 기다린 뒤 다시 접속해보세요

그래도 안 보이면 한 번만 더 새로고침 (Cmd+Shift+R / Ctrl+Shift+R)

그래도 안 되면 Claude에게 "GitHub Pages 활성화 상태 확인해줘"라고 물어보면 진단해줍니다

TIPS

공통 팁

토큰 분실 · 만료

GitHub Settings → Developer settings → Tokens에서 새로 발급. 이전 토큰은 해당 토큰 항목에서 Delete로 즉시 삭제 가능. Claude에게 새 토큰을 같이 주면서 "이전 토큰은 만료됐고 새 토큰으로 다시 인증해줘"라고 하면 됩니다

토큰 채팅 노출 주의

Claude Code와 대화할 때만 토큰을 공유하고, 공개 GitHub 이슈 · 블로그 · SNS에는 절대 붙여넣지 말 것. 노출되면 즉시 Delete로 삭제

여러 페이지 배포

저장소를 따로 만들면 됩니다. my-landing, my-portfolio, goods-survey 등 각각 별도 URL

사용자 메인 페이지 (username.github.io)

저장소 이름을 정확히 [사용자명].github.io로 만들면 URL이 깔끔하게 https://[사용자명].github.io/ (서브경로 없음). 본인 메인 포트폴리오에 추천

결과가 이상하면

브라우저 강제 새로고침 (Cmd+Shift+R macOS / Ctrl+Shift+R Windows). GitHub Pages는 캐시가 좀 강해서 변경사항이 늦게 보이는 경우가 있습니다

GitHub Pages 배포는
5분이면 충분합니다

왜 GitHub Pages인가요?

먼저 전체 흐름부터
한눈에 보세요

전체 흐름 한눈에

이제 단계별로
따라해 봅시다