Cloudflare Pages GitHub 자동 배포: Astro 블로그 연결 방법

이 글에서 다루는 내용

먼저 결론
연결 전에 확인할 것
Cloudflare Pages와 GitHub 연결하기
글 한 편을 발행하는 실제 흐름
자주 막히는 지점
이 블로그에서 확인한 설정
마지막 확인 목록

Cloudflare Pages GitHub 자동 배포: Astro 블로그 연결 방법

한 줄 요약: Cloudflare Pages에 GitHub 저장소를 한 번 연결하면, 이후에는 main 브랜치에 코드를 올리는 것만으로 빌드와 배포가 자동으로 이어져요.

블로그 글이나 디자인을 고친 다음 매번 파일을 직접 업로드하면 빠뜨릴 것이 생기기 쉬워요. GitHub 자동 배포를 연결하면 코드 저장 → GitHub에 올리기 → Cloudflare가 빌드 → 실제 사이트 반영 순서가 한 흐름으로 이어집니다.

이 글은 Astro 프로젝트를 GitHub 저장소에 올려둔 사람을 기준으로 설명해요. AI 실전노트도 비공개 GitHub 저장소의 main 브랜치와 Cloudflare Pages를 연결해 같은 방식으로 운영하고 있습니다. 아래 설정과 제한은 2026년 7월 14일에 Cloudflare 공식 문서로 다시 확인했어요.

먼저 결론

Astro 블로그라면 핵심 설정은 세 가지예요.

항목	입력값
프로덕션 브랜치	`main`
빌드 명령	`npm run build`
빌드 결과 폴더	`dist`

Cloudflare의 Pages 빌드 설정 공식 문서에도 Astro의 기본값이 npm run build와 dist로 안내되어 있습니다.

연결이 끝난 뒤 평소 발행 명령은 아래처럼 단순해져요.

git add .
git commit -m "새 글 발행"
git push origin main

git push는 내 컴퓨터의 변경 내용을 GitHub 저장소에 올리는 명령이에요. Cloudflare가 그 변경을 감지하면 새 버전을 자동으로 만들고 배포합니다.

연결 전에 확인할 것

1. 로컬 빌드가 먼저 성공해야 해요

Cloudflare에 연결하기 전에 프로젝트 폴더에서 실행해보세요.

npm install
npm run build

마지막 명령이 성공하고 dist 폴더가 생기면 기본 준비가 된 거예요. 여기서 실패한다면 Cloudflare 설정을 만지기 전에 로컬 오류부터 고치는 편이 빠릅니다.

2. GitHub에 브랜치가 하나 이상 있어야 해요

Cloudflare의 Git 연동 시작 가이드에 따르면 프로덕션 브랜치를 고르려면 GitHub에 브랜치를 한 번 이상 올려둬야 해요. 보통 main을 사용합니다.

3. 저장소는 비공개여도 괜찮아요

Cloudflare Pages는 공개 저장소와 비공개 저장소를 모두 연결할 수 있어요. 다만 GitHub 권한을 줄 때는 모든 저장소보다 배포할 저장소만 선택하는 편이 안전합니다.

Cloudflare Pages와 GitHub 연결하기

1단계: Git 연결 프로젝트 만들기

Cloudflare 대시보드에서 다음 순서로 들어가요.

Workers & Pages
→ Create application
→ Pages
→ Connect to Git

GitHub 로그인을 승인한 뒤 배포할 저장소를 선택합니다. 다른 저장소까지 접근 권한을 줄 필요는 없어요.

2단계: 빌드 항목 입력하기

Astro 블로그의 일반적인 설정은 아래와 같아요.

Production branch: main
Build command: npm run build
Build output directory: dist

프로젝트가 저장소 최상위가 아니라 blog/ 같은 하위 폴더에 있다면 Root directory에도 그 폴더를 입력해야 해요. 이 값을 빼먹으면 Cloudflare가 package.json을 찾지 못할 수 있습니다.

3단계: 첫 배포 확인하기

Save and Deploy를 누르면 Cloudflare가 의존성을 설치하고 빌드를 실행해요. 성공하면 임시 pages.dev 주소가 만들어집니다.

배포 화면에서는 다음 세 가지를 확인하세요.

상태가 Success인지
연결된 커밋이 방금 올린 커밋인지
임시 주소에서 홈과 글 상세 페이지가 열리는지

커스텀 도메인이 있다면 첫 배포가 성공한 뒤 연결하는 편이 문제를 나누어 보기 쉬워요.

글 한 편을 발행하는 실제 흐름

자동 배포를 연결한 뒤에는 Cloudflare 대시보드에서 파일을 다시 올릴 필요가 없습니다.

src/content/posts/에 Markdown 글을 추가해요.
npm run build로 오류가 없는지 확인해요.
변경 파일만 커밋해요.
git push origin main으로 GitHub에 올려요.
Cloudflare 배포가 성공했는지 확인해요.
실제 주소에서 제목, 이미지, 링크를 다시 봐요.

코드가 GitHub에 올라간 것과 사이트에 정상 표시된 것은 다른 확인 단계예요. 배포 성공 표시만 보고 끝내지 말고 실제 페이지까지 열어보는 것이 안전합니다.

자주 막히는 지점

`package.json`을 찾지 못해요

프로젝트가 저장소 하위 폴더에 있는데 Root directory를 비워둔 경우가 많아요. package.json이 있는 폴더를 기준으로 설정하세요.

빌드는 성공했는데 빈 페이지가 나와요

Build output directory가 dist인지 먼저 확인하세요. Astro가 만든 결과와 Cloudflare가 업로드하는 폴더가 달라지면 실제 파일이 빠질 수 있어요.

새 커밋을 올려도 배포가 시작되지 않아요

프로덕션 브랜치가 main인지, 자동 프로덕션 배포가 켜져 있는지 확인하세요. Cloudflare의 브랜치 배포 설정 문서에서 자동 배포할 브랜치를 조절할 수 있습니다.

Git 연동과 Direct Upload를 섞어도 되나요?

처음부터 운영 방식을 정하는 것이 좋아요. Cloudflare 공식 문서는 Git 연동으로 만든 Pages 프로젝트를 나중에 Direct Upload 프로젝트로 전환할 수 없다고 안내합니다. Git 연동 프로젝트에서 자동 빌드만 끄고 Wrangler로 배포하는 별도 방식은 있지만, 일반적인 블로그 운영에서는 Git 자동 배포를 그대로 유지하는 편이 단순해요.

무료 플랜이면 글을 몇 번까지 올릴 수 있나요?

Cloudflare의 Pages 제한 문서 기준으로 무료 플랜은 월 500회 빌드, 동시에 1개 빌드를 제공합니다. 글 한 편마다 한 번 배포하는 작은 블로그라면 보통 충분하지만, 사소한 수정도 계속 푸시하면 빌드 횟수가 늘어납니다.

이 블로그에서 확인한 설정

AI 실전노트의 현재 운영 흐름은 아래와 같아요.

Astro Markdown 글 작성
→ npm run build
→ 비공개 GitHub 저장소 main 브랜치에 push
→ Cloudflare Pages 자동 빌드
→ blog.promptkit.biz에 반영

별도의 CMS나 유료 배포 도구를 추가하지 않았어요. 글 본문은 정적 파일로 두고, 댓글·좋아요 같은 동적 기능은 나중으로 미뤄서 초기 구조와 비용을 단순하게 유지하고 있습니다.

키워드를 찾고 글을 구성하는 흐름이 먼저 필요하다면 AI 블로그 롱테일 키워드 실전 글도 이어서 볼 수 있어요.

마지막 확인 목록

로컬에서 npm run build가 성공한다.
Cloudflare의 프로덕션 브랜치가 main이다.
빌드 명령은 npm run build다.
출력 폴더는 dist다.
하위 폴더 프로젝트라면 Root directory를 입력했다.
푸시 뒤 Cloudflare 배포 상태가 성공이다.
실제 도메인에서 새 글과 대표 이미지가 열린다.

이 일곱 가지만 확인하면 매번 수동으로 파일을 올리지 않고, 글 작성과 검증에 더 집중할 수 있어요.