blog › posts › 03-github-저장소-cloudflare-pages-배포.md

03. GitHub 저장소 + Cloudflare Pages 배포

“본인 컴퓨터에서만 보이는 사이트는 사이트가 아니다. 인터넷에 띄워야 사이트가 된다.”

이것을 왜 배우는가?

지금까지 만든 사이트는 본인 컴퓨터에서만 보입니다. 가족·친구·전 세계 누구도 볼 수 없습니다. 인터넷에 띄워야 진짜 블로그입니다.

이 단계가 끝나면:

yourname.pages.dev 같은 주소가 발급됨
전 세계 어디서든 접속 가능
글 쓰고 git push 하면 자동으로 사이트 업데이트
무료 + 광고 수익 가능

왜 두 단계로 나뉘는가:

단계	역할
GitHub	본인 코드·글의 클라우드 저장소 (백업 역할)
Cloudflare Pages	그 코드를 실제 인터넷 사이트로 띄우는 서비스 (호스팅 역할)

GitHub은 “저장”, Cloudflare Pages는 “공개”. 두 회사가 협력하는 구조.

전체 흐름 미리보기

[본인 컴퓨터의 my-blog 폴더]
         │
         │ ① git remote add (연결 설정)
         │ ② git push (업로드)
         ▼
[GitHub 저장소]
         │
         │ ③ Cloudflare가 GitHub과 연결
         │ ④ 자동 빌드 (마크다운 → HTML)
         ▼
[Cloudflare Pages]
         │
         │ ⑤ 전 세계 CDN에 배포
         ▼
[독자들이 yourname.pages.dev 접속]

CDN = Content Delivery Network. “콘텐츠를 빠르게 전달하는 네트워크”. 전 세계 도시에 서버를 둬서 사용자가 가장 가까운 서버에서 받아가게 함. 한국 사용자는 한국·일본 서버에서, 미국은 미국 서버에서.

Step 1. GitHub 저장소 만들기

무엇을 만드는가

저장소(Repository, 레포지토리) = “보관소”. GitHub에서 코드와 글을 모아두는 단위. 폴더 하나처럼 동작.

본인 GitHub 계정 안에 my-blog라는 저장소를 만들 겁니다. 이 저장소에 본인 컴퓨터의 my-blog 폴더 내용을 업로드합니다.

저장소 생성 방법

https://github.com 로그인
우측 상단 + 아이콘 클릭 → “New repository” 선택
다음과 같이 입력:

항목	입력값
Repository name	`my-blog` (또는 본인이 폴더에 쓴 이름)
Description (선택)	“내 개인 블로그”
Public / Private	Public 권장 (이유 아래)
Add a README file	❌ 체크 해제 (이미 있음)
Add .gitignore	❌ 체크 해제 (이미 있음)
Choose a license	❌ 체크 해제 (필요시 나중에)

“Create repository” 클릭

⚠️ README, .gitignore, license 체크 안 하기: 본인 컴퓨터에 이미 있는 my-blog 폴더와 충돌할 수 있음. 빈 저장소로 만들어야 충돌 없음.

Public vs Private 선택

옵션	의미	추천 상황
Public	누구나 코드 볼 수 있음	블로그·오픈소스. 기본값
Private	본인만 볼 수 있음	비밀 코드·민감 정보

왜 블로그는 Public이 좋은가:

글은 어차피 사이트에 공개되므로 코드도 공개해도 됨
Public이면 본인 GitHub 프로필에 활동 표시됨 (나중에 채용에 도움)
Private이면 GitHub 무료 플랜 일부 기능 제한 (액션 사용량 등)

⚠️ 민감 정보 주의: Public 저장소에 비밀번호·API 키 같은 거 올리면 전 세계에 공개됩니다. 블로그 글은 공개해도 OK이지만 환경변수(.env 파일)는 절대 올리면 안 됩니다. (Astro는 기본적으로 .env를 무시함)

저장소 생성 후 화면

생성 직후 화면에 명령어 안내가 나옵니다:

…or push an existing repository from the command line

git remote add origin https://github.com/본인아이디/my-blog.git
git branch -M main
git push -u origin main

→ 이 명령어 3줄을 다음 단계에서 사용합니다. 이 화면 켜둔 채로 다음으로.

Step 2. 본인 컴퓨터 → GitHub 푸시

명령어 의미 미리 이해하기

다음 명령어들을 입력할 텐데, 각각이 무엇을 하는지:

# 1. 본인 폴더와 GitHub 저장소 연결
git remote add origin https://github.com/본인아이디/my-blog.git

# 2. 메인 브랜치 이름을 'main'으로 변경
git branch -M main

# 3. 변경사항 commit (저장점 만들기)
git add .                              # 모든 변경 파일 추가
git commit -m "first commit"           # 메시지와 함께 저장

# 4. GitHub에 업로드
git push -u origin main

remote = “원격”. GitHub 저장소를 “원격 저장소”라 부름. origin = 원격 저장소의 별명. “오리진”으로 불림. branch = “가지”. Git에서 작업 흐름을 분리하는 단위. 보통 main이 기본. commit = “저장점 만들기”. 변경사항을 한 묶음으로 기록. push = “밀어넣기”. 본인 컴퓨터의 commit들을 GitHub에 업로드.

명령어 실행

터미널에서 my-blog 폴더로 이동:

cd ~/code/my-blog        # Mac
# 또는
cd C:\Users\본인이름\code\my-blog    # Windows

❗ 이미 npm create astro 시 git initialized 했으면 일부 단계는 이미 완료됐을 수 있음. 그래도 다음 명령어들 실행해도 안전.

순서대로 입력:

# (1) 원격 저장소 연결 — 본인아이디 자리에 본인 GitHub 사용자명
git remote add origin https://github.com/본인아이디/my-blog.git

# (2) 메인 브랜치 이름 표준화
git branch -M main

# (3) 모든 파일 git에 추가
git add .

# (4) 첫 commit (저장점 만들기)
git commit -m "first commit"

# (5) GitHub에 업로드
git push -u origin main

GitHub 인증 (처음 푸시 시)

git push 시 GitHub 로그인 창이 뜹니다. 두 가지 방법:

방법 1: 브라우저 인증 (가장 쉬움)

자동으로 브라우저 열림
GitHub 로그인하고 권한 허용
끝

방법 2: Personal Access Token (구식)

GitHub에서 Token 만들어 비밀번호 자리에 입력
위 방법 1이 안 되면 사용

⚠️ 2026년 4월 현재: GitHub은 일반 비밀번호 사용 차단. 위 방법 1 또는 Personal Access Token 사용 필수.

푸시 성공 확인

Counting objects: 24, done.
...
To https://github.com/본인아이디/my-blog.git
 * [new branch]      main -> main

→ 이런 메시지 나오면 성공.

브라우저에서 https://github.com/본인아이디/my-blog 접속 → 본인 코드·글이 보이면 ✅

Step 3. Cloudflare Pages에 배포

Cloudflare Pages가 무엇을 하는가

Pages = Cloudflare가 운영하는 정적 사이트 호스팅 서비스. 이름 그대로 “페이지들”을 띄움.

GitHub의 코드를 자동으로 가져다가:

Astro 빌드 (npm run build 자동 실행)
결과 HTML 파일들을 전 세계 CDN에 배포
xxx.pages.dev 주소 발급
HTTPS 자동 적용 (보안 인증서)

→ 본인이 할 일은 GitHub과 연결만. 빌드·배포·인증서 다 자동.

배포 순서

https://dash.cloudflare.com 로그인
좌측 메뉴 “Workers & Pages” 클릭
우측 “Create application” 버튼 클릭
“Pages” 탭 클릭
“Connect to Git” 클릭
GitHub 인증 (처음이면)
- “Connect GitHub” 클릭
- 권한 허용
- 본인 GitHub 계정 연결
저장소 선택 화면에서 my-blog 선택
“Begin setup” 클릭

빌드 설정 (중요)

다음 화면에서 빌드 설정을 입력합니다. Astro 자동 인식되면 거의 자동으로 채워집니다:

항목	입력값	설명
Project name	`my-blog` (자동)	URL의 일부가 됨. `my-blog-xxxx.pages.dev`
Production branch	`main` (자동)	어느 브랜치에서 배포할지
Framework preset	Astro	자동 감지. 안 되면 수동 선택
Build command	`npm run build`	자동 입력
Build output directory	`dist`	자동 입력
Root directory	(비워둠)	저장소 루트에서 빌드

build = 개발용 코드를 실제 사이트용 파일로 변환하는 과정. Astro는 마크다운·.astro 파일을 HTML로 변환. dist = “distribution”의 줄임. 빌드 결과물이 들어가는 폴더 이름. npm run build 실행 후 자동 생성됨.

⚠️ Framework preset이 “None”이거나 안 잡히면: Manual 입력 시:

Build command: npm run build
Build output directory: dist
Node version: 20 또는 22 (환경변수 NODE_VERSION 추가 필요할 수 있음)

환경변수 (대부분 불필요)

기본 Astro 블로그는 환경변수 없어도 동작. 만약 빌드가 Node 버전 때문에 실패하면:

환경변수 이름	값
`NODE_VERSION`	`22`

→ “Environment variables” 섹션에서 추가.

배포 실행

“Save and Deploy” 버튼 클릭.

화면에 빌드 진행 로그가 실시간으로 보입니다:

Cloning repository...
Initializing build...
Installing dependencies...
  npm install
  added 234 packages in 12s
Running build command...
  > astro build
  17:30:01 [build] Building static entrypoints...
  17:30:03 [build] ✓ Completed
Deploying to Cloudflare's global network...
✓ Success! Your project is deployed

3~5분 후 완료. 배포 끝나면 화면에 사이트 주소가 나옵니다:

https://my-blog-xxxx.pages.dev

→ 이 주소가 본인 사이트의 영구 무료 주소. 클릭해서 확인.

✅ 사이트가 인터넷에 보이면 성공.

Step 4. 자동 배포 확인

흐름 이해

이제 이런 흐름이 자동으로 동작합니다:

[본인 컴퓨터에서 글 추가/수정]
        ↓
[git add .]
[git commit -m "메시지"]
[git push]
        ↓
[GitHub에 업로드됨]
        ↓
[Cloudflare가 자동 감지]
        ↓
[자동 빌드 + 배포]
        ↓
[30초~2분 후 사이트에 반영]

테스트해보기

본인 컴퓨터에서 사이트 제목 살짝 바꿔봅시다:

src/consts.ts 열고:

export const SITE_TITLE = '김민수의 블로그 (수정됨)';   // 끝에 '(수정됨)' 추가

저장 후 터미널에서:

git add .
git commit -m "test: update title"
git push

Cloudflare 대시보드 → my-blog 프로젝트 → “Deployments” 탭에서 새 배포가 시작되는 거 보임. 1~2분 후 사이트 새로고침하면 제목 바뀜.

✅ 자동 배포 작동 확인 = 셋업 완료. 이제부터는 글 쓰고 git push만 반복.

Step 5. (옵션) 사이트 주소 변경

기본 주소가 마음에 안 들면

my-blog-xxxx.pages.dev의 xxxx 부분이 랜덤이라 외우기 어렵습니다.

옵션 A: 프로젝트 이름 변경 (간단)

Cloudflare 대시보드 → my-blog → Settings → “Project name” 옆 Edit

새 이름: kimminsoo-blog 같이 본인 이름
저장하면 kimminsoo-blog.pages.dev 주소로 변경

⚠️ 기존 주소는 작동 안 함. 외부에서 링크된 게 있으면 깨짐. 처음 배포 직후에 바꾸는 게 안전.

옵션 B: 본인 도메인 연결 (선택, 유료)

yourname.com 같은 도메인 사면 그걸 연결 가능. → 05-monetize.md에서 다룸.

정리 및 체크리스트

□ GitHub에 my-blog 저장소 만들었음 (Public 권장)
□ 저장소 생성 시 README/gitignore/license 체크 안 함 (충돌 방지)
□ git remote add origin로 본인 폴더와 GitHub 연결
□ git push로 본인 코드를 GitHub에 업로드 성공
□ GitHub 저장소 페이지에서 본인 코드 보임
□ Cloudflare Pages에서 GitHub 연동
□ Framework preset: Astro 자동 인식 또는 수동 입력
□ 첫 배포 성공, my-blog-xxxx.pages.dev 주소 발급
□ 브라우저에서 그 주소 접속하면 본인 사이트 보임
□ 본인 컴퓨터에서 변경 → git push → 30초 후 사이트 반영 확인

흔한 실수 모음

실수	결과	해결
GitHub 저장소 만들 때 README 체크	git push 시 충돌 에러	`git pull --rebase origin main` 후 다시 푸시
`git remote add` 시 URL 오타	push 안 됨	`git remote remove origin` 후 다시 add
GitHub 비밀번호 입력	인증 거부됨	Personal Access Token 또는 브라우저 인증 사용
Cloudflare에서 Framework preset 잘못 선택	빌드 실패	Settings에서 Astro로 수정
Build output directory 잘못 입력	사이트 빈 화면	`dist` (소문자) 정확히 입력
한글 commit 메시지 깨짐	git log에서 깨짐	UTF-8 인코딩 확인 또는 영문 메시지 사용
`git push` 시 “branch protection”	보호 규칙 때문 차단	새 저장소면 보통 없음. 있으면 GitHub Settings에서 해제

자주 묻는 질문

Q: 첫 배포 후 빌드 시간이 너무 오래 걸려요 (5분+)

A: 첫 빌드는 의존 패키지 다 설치하므로 오래 걸림. 두 번째부터는 캐시 사용해서 30초~2분.

Q: 사이트 주소를 바꾸고 싶어요

A: Cloudflare 대시보드 → 프로젝트 → Settings → Project name 변경. 또는 본인 도메인 연결 (05번 가이드).

Q: 깃허브 비공개로 해도 Cloudflare 배포 되나요?

A: ✅ 됩니다. Private 저장소도 Cloudflare 연동 가능. 단 GitHub 무료 플랜의 일부 자동화 기능 제한 가능.

Q: 빌드가 자꾸 실패해요

A: Cloudflare 대시보드 → 프로젝트 → Deployments → 실패한 배포 클릭 → 로그 확인. 보통 다음 중 하나:

Node 버전 문제 → 환경변수 NODE_VERSION=22 추가
패키지 설치 실패 → package-lock.json 삭제 후 재푸시
코드 에러 → 본인 컴퓨터에서 npm run build 먼저 시도해보기

💡 핵심 포인트

이 단계의 핵심: GitHub = 저장소, Cloudflare Pages = 호스팅. 둘이 자동 연결되면 글 쓰고 git push만 반복.

한 번 셋업했으면 이 가이드는 다시 볼 일 거의 없습니다. 다음으로 가서 실제 글 쓰기 시작합니다.

다음 단계

04-daily-write.md — 마크다운 사용법, 첫 글 작성, 매일 글 쓰는 흐름