비개발자 연구실

Claude Code ·

새 사이트 만들 때마다, 깃허브 연결부터 자동 배포까지 클로드한테 맡기는 법

사이트를 하나 더 만들 때마다 깃허브 저장소 만들고, Cloudflare에 연결하고, 도메인 다는 과정을 매번 손으로 반복하기엔 번거롭습니다. 로그인 필요한 클릭만 내가 하고, 설정 파일과 연결 과정은 클로드한테 맡기는 순서입니다.


사이트를 한 번 만들어 두면, 그다음부터 “글 하나 올리면 자동으로 배포되는” 흐름이 당연해 보입니다. 그런데 그 흐름이 되기까지는 깃허브 저장소 생성, 배포 설정 파일 작성, Cloudflare와 깃허브 연결, 도메인 등록까지 여러 단계가 필요합니다. 코딩을 모르면 이 중 어디서부터 막히는지도 가늠이 안 됩니다. 저는 이 전체 과정을 한 번 겪고 나서, 두 번째 사이트부터는 거의 전부를 클로드에게 맡겼습니다.

Claude Code에 붙여넣기

역할: <사용 중인 정적 사이트 프레임워크, 예: Astro>로 만든 정적 사이트를 깃허브·Cloudflare와 연결해서, push 한 번으로 자동 배포되게 만드는 담당

맥락: 지금 폴더에 프로젝트가 있다. 깃허브 계정과 Cloudflare 계정은 이미 있고, 로그인이 필요한 화면 조작만 내가 직접 한다.

입력: 사이트 이름 = <예: my-site>, 빌드 명령어 = <예: npm run build>, 빌드 결과 폴더 = <예: ./dist>

작업: 1) 배포에 필요한 설정 파일(예: wrangler.jsonc)이 있는지 확인하고 없으면 만들어라. 2) 빌드 명령어가 실제로 성공하는지 먼저 확인해라. 3) 깃허브 저장소를 만들어야 하는 단계가 오면, 내가 웹 화면에서 눌러야 할 버튼을 순서대로 짚어 주고 화면을 캡처해서 보내면 다음 단계를 알려줘라. 4) Cloudflare에서 "Workers 정적 자산" 배포로 저장소를 연결하는 단계도 같은 방식으로 안내해라.

제약: 계정 로그인, 결제, 도메인 구매처럼 사람 승인이 필요한 조작은 네가 직접 하지 말고 나에게 요청해라. 기존 설정 파일을 덮어쓰기 전엔 먼저 보여줘라.

출력: 지금까지 끝난 단계, 다음에 내가 눌러야 할 버튼, 완료 후 확인해야 할 URL을 정리해라.

전체 흐름이 어떻게 생겼나

Astro 정적 사이트를 Cloudflare Workers에 올리는 흐름은 크게 이렇습니다. ① 로컬에서 빌드가 되는지 확인 → ② 깃허브 저장소 생성·push → ③ Cloudflare에서 그 저장소를 “Workers 정적 자산”으로 연결 → ④ 이후로는 깃허브 main 브랜치에 push할 때마다 Cloudflare가 자동으로 다시 빌드·배포. 한 번 ③번까지 연결해 두면, 그다음부터는 글 하나 추가하고 커밋·푸시만 하면 몇 분 안에 실제 사이트에 반영됩니다.

STEP 1. 설정 파일 하나로 시작

wrangler.jsonc에 사이트 이름, 빌드 결과 폴더(./dist) 정도만 적어 두면 됩니다. 클로드에게 맡기면 이 파일 자체를 자동으로 만들어 줍니다.

{
  "name": "내사이트이름",
  "compatibility_date": "2026-10-09",
  "assets": { "directory": "./dist" }
}

여기서 compatibility_date는 오늘 날짜 근처로 넣으면 되고, 나중에 Cloudflare가 새 기능을 추가해도 이 날짜 기준 동작은 안 바뀝니다.

STEP 2. 로컬 빌드부터 확인

깃허브에 올리기 전에, 먼저 npm run build(또는 해당 프레임워크의 빌드 명령)가 에러 없이 끝나는지 확인합니다. 여기서 실패하면 그 뒤 어떤 단계를 거쳐도 결국 Cloudflare에서도 똑같이 실패합니다. “로컬에서 되는 것”이 배포의 전제 조건입니다.

STEP 3. 깃허브 저장소 만들기

깃허브는 화면 조작이 필요한 구간이라, 클로드가 “Create repository 눌러줘”, “저장소 이름 뭘로 할지”, “비공개로 할지” 같은 걸 하나씩 물어보면 그대로 답하면서 진행하면 됩니다. 비공개 저장소로 시작해도 Cloudflare 연결에는 문제없습니다.

STEP 4. 코드 push

저장소가 만들어지면 git remote add, git push까지는 클로드가 명령어를 직접 실행해 줄 수 있습니다. 이 단계는 터미널 작업이라 로그인이 필요 없어서, 보통 가장 빨리 끝납니다.

STEP 5. Cloudflare에서 연결

Cloudflare 대시보드 → Workers 및 Pages → Create application → 방금 만든 깃허브 저장소를 선택하는 순서입니다. 여기서 제일 헷갈렸던 지점이 있었습니다.

“저장소가 목록에 안 보임” 문제. Cloudflare가 깃허브 저장소 목록을 불러오는데, 방금 만든 저장소가 안 보이는 경우가 있습니다. 대부분 Cloudflare GitHub 앱의 저장소 접근 권한이 그 저장소까지 열려 있지 않아서입니다. 깃허브 → 설정(Settings) → Applications → Cloudflare Workers and Pages → Configure로 들어가서, 접근 허용 저장소 목록에 새 저장소를 추가하면 바로 보입니다.

Cloudflare Workers 대시보드는 화면이 자주 바뀌는 편이라, 그때그때 화면을 캡처해서 “여기서 어떻게 해야 돼?” 물어보면서 진행하는 게 문서를 따라가는 것보다 빨랐습니다.

이메일 등록하면 이어서 보기

STEP 6. 빌드 설정 확인

Cloudflare가 저장소를 연결하면 빌드 명령어와 출력 폴더를 입력하는 화면이 나옵니다. STEP 1에서 wrangler.jsonc에 적어 둔 값과 일치하는지 확인하고 배포를 누르면 첫 빌드가 시작됩니다.

STEP 7. 도메인 연결(선택)

기본으로 주어지는 *.workers.dev 주소로도 바로 접속은 되지만, 직접 산 도메인을 쓰고 싶다면 Cloudflare에서 그 도메인의 네임서버를 관리하도록 설정한 뒤, Workers 설정의 Custom Domains에서 도메인을 추가합니다. DNS가 전파되는 데 최대 몇 분 정도 걸릴 수 있습니다.

STEP 8. 연결이 끝나면 push만으로 끝

한 번 연결해 두면, 그 다음부터 글을 추가하고 git push만 하면 Cloudflare가 자동으로 다시 빌드해서 몇 분 안에 반영됩니다. 사이트가 여러 개면, 계정 하나로 저장소마다 따로 연결해 가면 됩니다.

자주 막히는 지점

증상 원인 해결
Cloudflare에서 내 깃허브 저장소가 목록에 안 보임 Cloudflare GitHub 앱 권한이 그 저장소까지 안 열려 있음 깃허브 앱 설정에서 저장소 접근 권한 추가
push했는데 사이트가 안 바뀜 빌드 실패했거나 아직 배포 중 Cloudflare 대시보드의 배포 로그에서 에러 확인
주소창에 도메인 쳐도 사이트가 안 뜸 도메인 DNS 연결이 아직 안 끝남 Cloudflare 도메인 설정에서 연결 상태 재확인(최대 몇 분 소요)
로컬에선 되는데 Cloudflare 빌드만 실패 Node.js 버전 차이, 또는 빌드 출력 폴더 경로가 다름 Cloudflare 빌드 로그의 에러 메시지를 그대로 클로드에 붙여넣기

돌아보며

처음 한 번은 깃허브 저장소가 뭔지, Cloudflare의 “Workers 정적 자산”이 뭔지부터 설명을 들어야 했지만, 그 과정 자체를 한 번 클로드와 끝까지 해 보고 나니 두 번째 사이트부터는 거의 대화만으로 끝났습니다. 로그인·결제·버튼 클릭처럼 사람만 할 수 있는 부분과, 설정 파일 작성·에러 원인 추적처럼 AI가 더 잘하는 부분을 나눠서 맡기는 게 핵심이었습니다.

← AI 활용법 목록