클로드로 콘텐츠 만들어 GitHub 커밋·Cloudflare 배포하기

콘텐츠 제작과 배포를 하나의 흐름으로 보기

웹사이트에 콘텐츠를 늘려 가는 작업은 만들기, 검토하기, 기록하기, 공개하기의 네 단계가 반복됩니다. Claude는 첫 단계의 초안 작성과 코드 생성을 빠르게 도와주지만, 사실 확인과 최종 판단은 사람이 맡아야 합니다. 검토를 마친 결과물은 Git으로 변경 이력을 남기고 GitHub에 올려 두면, 문제가 생겼을 때 이전 상태로 돌아갈 수 있습니다. 마지막으로 Cloudflare Pages가 저장소의 변경을 받아 사이트를 다시 빌드해 공개합니다.

저장소 연결 배포와 직접 업로드 배포의 차이

Cloudflare Pages는 GitHub 저장소를 연결해 두면 푸시할 때마다 자동으로 빌드하고 배포합니다. 이 방식은 빌드에 필요한 환경 변수를 Cloudflare 프로젝트 설정에 직접 등록해야 합니다. 반대로 내 컴퓨터에서 빌드한 결과 폴더를 Wrangler 명령으로 직접 업로드하는 방식도 있으며, 이 경우에는 로컬 빌드에 쓰인 값이 그대로 결과물에 반영됩니다. 어느 쪽이든 API 키 같은 비밀 값은 저장소에 올리지 않도록 .env 파일을 .gitignore에 넣어 관리하세요.

Cloudflare 공식 문서 기준이며, 어느 방식이든 프로젝트를 만든 뒤에는 바꿀 수 없으므로 처음에 신중히 고르세요.

Git 연결 방식의 대시보드 설정 순서

1. Cloudflare 대시보드의 Workers & Pages에서 Create application > Pages > Connect to Git을 고릅니다.
2. GitHub를 선택하고 인증한 뒤, 개인 계정이나 접근을 허용한 조직의 저장소를 고릅니다. 공개·비공개 저장소 모두 가능합니다.
3. Install & Authorize, Begin setup 순서로 진행합니다.
4. 프로젝트 이름, 프로덕션 브랜치(보통 main 또는 master), 프레임워크 프리셋, 빌드 명령, 빌드 출력 폴더, 환경 변수를 설정합니다. 프로덕션 브랜치는 최소 한 번 푸시된 브랜치만 고를 수 있습니다.
5. Save and Deploy를 누르고 빌드 로그를 확인합니다.

Astro 프리셋의 빌드 명령은 npm run build, 출력 폴더는 dist입니다. 프로덕션 브랜치가 아닌 브랜치는 모두 미리보기 배포가 만들어지며, 기본적으로 미리보기는 공개 접근이 가능하다고 문서에 적혀 있으므로 비공개 내용을 올리는 브랜치에는 주의하세요.

GitHub 명령어 예시와 설명

터미널에서 프로젝트 폴더로 이동한 뒤 아래 순서로 실행합니다. 처음 한 번만 필요한 명령과 매번 반복하는 명령이 섞여 있습니다.

• git init

  현재 폴더를 새 Git 저장소로 만듭니다. 이미 저장소라면 다시 실행할 필요가 없습니다.

• git status

  어떤 파일이 바뀌었고 아직 커밋되지 않았는지 보여줍니다. 커밋 전에 .env 같은 파일이 포함되지 않았는지 확인할 때 씁니다.

• git add .

  바뀐 파일 전체를 커밋 대상(스테이징)에 담습니다. 특정 파일만 담으려면 점(.) 대신 파일 경로를 적습니다.

• git commit -m "새 가이드 페이지 추가"

  담아 둔 변경사항을 메시지와 함께 기록합니다. 무엇을 바꿨는지 한 줄로 적어 둡니다.

• git branch -M main

  현재 브랜치 이름을 main으로 바꿉니다. 새 저장소를 처음 만들 때 한 번만 필요합니다.

• git remote add origin https://github.com/내계정/저장소이름.git

  로컬 저장소를 GitHub 저장소(origin)에 연결합니다. 주소는 GitHub 저장소 화면에서 복사합니다.

• git push -u origin main

  로컬 커밋을 GitHub에 올립니다. -u 옵션은 처음 한 번만 쓰며, 이후에는 git push만 실행해도 됩니다.

• git log --oneline

  커밋 이력을 한 줄씩 보여줍니다. 이전 상태를 찾거나 푸시된 내용을 확인할 때 유용합니다.

Cloudflare 명령어 예시와 설명

저장소 연결 방식은 대시보드에서 설정하고, 아래 명령은 내 컴퓨터에서 빌드한 결과를 Wrangler로 직접 배포할 때 사용합니다. 프로젝트 이름은 본인이 정한 이름으로 바꿔서 입력하세요.

• npm run build

  프로젝트를 빌드해 배포용 결과 폴더(Astro는 dist)를 만듭니다. 배포 전에 오류가 없는지 확인하는 단계이기도 합니다.

• npm install -g wrangler

  Cloudflare 배포 도구 Wrangler를 설치합니다. 전역 설치 없이 npx wrangler로 실행해도 됩니다.

• wrangler login

  브라우저가 열리며 Cloudflare 계정에 로그인해 Wrangler 사용을 허용합니다. 처음 한 번만 필요합니다.

• wrangler pages project create 프로젝트이름

  Cloudflare Pages 프로젝트를 새로 만듭니다. 대시보드에서 직접 만들었다면 생략합니다.

• wrangler pages deploy dist --project-name=프로젝트이름 --branch=main

  빌드 결과 폴더를 Pages 프로젝트에 업로드해 배포합니다. --branch=main은 프로덕션(main) 브랜치로 배포되도록 지정하는 옵션입니다.

• wrangler pages deployment list --project-name=프로젝트이름

  해당 프로젝트의 배포 이력을 보여줍니다. 어떤 배포가 현재 반영 중인지 확인할 때 씁니다.

위 Wrangler 명령은 직접 업로드 프로젝트용입니다. 이미 Git 연결로 만든 프로젝트라면 푸시만으로 배포되므로 이 명령을 쓸 일이 없습니다. 프로젝트 생성 명령에는 --production-branch 옵션으로 프로덕션 브랜치를 지정할 수 있고, 배포 명령에는 --commit-message 옵션으로 배포에 메모를 붙일 수 있습니다(Wrangler 공식 문서 기준).

보안 수칙: 비밀 값이 저장소로 새지 않게

• .gitignore를 먼저: .env를 .gitignore에 넣고 그 변경을 커밋한 뒤에 작업을 시작합니다. 단, .gitignore는 이미 Git이 추적 중인 파일에는 적용되지 않습니다. 추적 중이라면 git rm --cached 파일명으로 추적을 해제해야 합니다(GitHub 공식 문서).
• 무엇이 올라가는지 확인: GitHub 문서는 git add .와 git commit -a를 피하고 파일을 개별로 담은 뒤 git diff --cached로 확인하라고 권합니다. 이 글의 git add . 예시는 편의를 위한 것이므로, 비밀 값이 있는 프로젝트라면 git status 확인을 반드시 거치세요.
• Claude Code가 .env를 읽지 못하게: Claude Code 설정 문서는 permissions.deny에 Read(./.env)와 Read(./.env.*) 규칙을 넣는 예시를 보여 줍니다. 설정 파일 위치는 개인용 ~/.claude/settings.json, 팀 공유용 .claude/settings.json 등입니다.
• 푸시 보호: GitHub의 푸시 보호(push protection)는 토큰 같은 비밀 값이 포함된 푸시를 차단합니다. 공개 저장소에는 사용자 수준 보호가 기본으로 켜져 있고, 저장소 수준 보호는 GitHub 보안 기능(Secret Protection)이 필요하며 기본값은 꺼짐입니다. 차단될 때는 비밀 값을 코드에서 지우고 다시 푸시합니다.
• Cloudflare에는 환경 변수로: 빌드에 필요한 값은 프로젝트의 Settings > Environment variables에 등록합니다. 코드에 직접 적지 않습니다.
• 한 번 올라간 비밀 값: 저장소에서 파일을 지워도 이력에 남습니다. GitHub 문서는 먼저 해당 자격 증명을 폐기·교체하고, 그 뒤에 이력 재작성(git-filter-repo 등)이 필요한지 판단하라고 안내합니다. 이력 재작성은 협업자의 복제본과 포크에는 영향을 주지 못하는 번거로운 작업입니다.

배포 후 되돌리기와 제한 사항

Cloudflare Pages 프로젝트의 Deployments에서 되돌리고 싶은 배포의 메뉴(점 세 개)를 열어 Rollback to this deployment를 선택하고 확인하면 프로덕션이 즉시 그 배포로 바뀝니다. 빌드에 성공한 프로덕션 배포만 되돌릴 대상이 되며 미리보기 배포는 대상이 아닙니다. 되돌린 뒤에도 더 새로운 배포로 다시 앞으로 갈 수 있습니다. 무료 플랜의 한도는 공식 문서 기준(2026년 10월 확인)으로 월 500회 빌드, 사이트당 파일 20,000개, 파일 하나당 25MiB, 빌드 제한 시간 20분입니다. 정책은 바뀔 수 있으니 현재 값을 확인하세요.

문제 해결: 자주 만나는 증상

흔한 실수

• 검토 없이 커밋·푸시한다: 푸시하는 순간 Git 연결 프로젝트는 자동 배포되므로, 푸시 전이 마지막 검토 지점입니다.
• 두 가지 배포 방식을 섞는다: Git 연결 프로젝트에 Wrangler 직접 업로드를 겹쳐 쓰려고 하는 경우입니다. 프로젝트 하나는 한 가지 방식입니다.
• 환경 변수를 로컬에만 둔다: Git 연결 방식은 Cloudflare 쪽에서 빌드하므로 프로젝트 설정에 변수를 등록해야 합니다.
• CLAUDE.md의 금지 문구만 믿는다: 지침은 참고 문맥이라 강제되지 않습니다. 막아야 하는 동작은 권한 규칙으로 막습니다.
• 커밋 메시지를 비워 두거나 "수정"으로만 쓴다: 나중에 되돌릴 지점을 찾기 어려워집니다.

가상 예시: 새 페이지 하나를 올리는 하루

가상 예시입니다. 개인 블로그 저장소에 새 글을 추가한다고 가정합니다. 오전에 Claude Code에게 기존 글 파일과 같은 구조로 새 글 초안을 요청하고(2단계), 오후에 사실과 링크를 직접 확인한 뒤 로컬 빌드로 오류가 없는지 봅니다(3단계).git status로 새 글 파일 한 개만 바뀌었는지, .env가 목록에 없는지 확인하고(4단계) 파일을 담아 한 줄 메시지로 커밋합니다(5단계). git push 후 Cloudflare 배포 목록에서 빌드가 성공했는지 보고, 발급된 주소에서 새 글이 보이는지 확인합니다(6~8단계). 만약 오타를 뒤늦게 발견하면 파일을 고쳐 다시 커밋·푸시하면 새 배포가 생깁니다. 실제 사례나 수치가 아닌 흐름을 보여 주는 시나리오입니다.

한계와 알아둘 점

이 글은 Astro 같은 정적 빌드 사이트와 GitHub 저장소를 기준으로 합니다. SSR 사이트(어댑터 설치 필요), 모노레포(루트 디렉터리 설정), 사용자 지정 도메인 연결, GitHub Actions를 쓴 배포는 다루지 않습니다. Cloudflare 대시보드 문구와 한도, Claude Code의 설치 방식은 업데이트로 달라질 수 있으니 각 공식 문서를 우선하세요. 명령은 본인 저장소와 계정에서만 실행하고, 삭제·덮어쓰기 성격의 작업(이력 재작성, 강제 푸시)은 백업 후에 진행하세요.

함께 보면 좋은 가이드

커밋과 푸시가 처음이라면 깃허브(GitHub) 기초 사용법을, Claude를 처음 쓴다면 클로드(Claude) AI 기초 사용법을 먼저 확인해보세요. 사이트를 어디에 올릴지 고민 중이라면 웹 호스팅 종류 가이드도 도움이 됩니다. 계정 보안은 2단계 인증 가이드와 비밀번호 관리자 기초, 도메인 연결은 DNS 레코드 종류를 참고하세요.

자주 묻는 질문