실습 노트
AI 코딩 CLI로 만든 첫 홈페이지를 Cloudflare Pages에 배포하는 방법
Codex CLI, Claude Code, Antigravity CLI로 만든 index.html 홈페이지를 GitHub 저장소에 올리고 Cloudflare Pages Git 연동으로 실제 배포 URL을 만드는 초보자용 순서입니다.
앞 글에서 AI 코딩 CLI로 index.html 파일 하나짜리 홈페이지를 만들었습니다.
이번 글에서는 그 파일을 실제 주소로 배포합니다.
목표는 단순합니다.
내 컴퓨터에 있는 index.html을 GitHub에 올리고, Cloudflare Pages로 연결해서 브라우저에서 열리는 URL을 하나 만드는 것입니다.
이 글은 아래 글 다음에 보면 됩니다.
- AI 코딩 CLI로 첫 홈페이지 만들기
- AI 코딩 CLI 설치 후 처음 세팅할 것 7가지
- 윈도우 Codex CLI 설치 가이드
- 윈도우 Claude Code CLI 설치 가이드
- 윈도우 Antigravity CLI 설치 가이드
공식 문서는 GitHub의 로컬 저장소 업로드 문서, Cloudflare Pages Git 연동 문서, Cloudflare Pages Direct Upload 문서를 기준으로 확인했습니다.
참고: GitHub Docs — Adding locally hosted code to GitHub →, Cloudflare Pages — Git integration →, Cloudflare Pages — Direct Upload →
용어 주석
- AI 코딩 CLI: 터미널에서 실행하는 AI 코딩 도구입니다. Codex CLI, Claude Code, Antigravity CLI처럼 폴더 안의 파일을 읽고 수정할 수 있는 도구를 말합니다.
- GitHub: 코드와 파일 변경 기록을 저장하는 온라인 저장소 서비스입니다.
- Cloudflare Pages: HTML, CSS, JavaScript로 만든 정적 홈페이지를 웹 주소로 배포하는 서비스입니다.
- 배포: 내 컴퓨터에만 있던 파일을 인터넷 주소에서 열리게 만드는 과정입니다.
- URL: 브라우저 주소창에 입력하는 웹 주소입니다. 예를 들어
https://first-homepage.pages.dev같은 형태입니다.
먼저 결론
이번 순서는 이렇습니다.
first-homepage폴더에index.html이 있는지 확인합니다.- Git 저장소로 만듭니다.
- GitHub에 새 저장소를 만들고 push합니다.
- Cloudflare Pages에서 GitHub 저장소를 연결합니다.
- 빌드 설정 없이 루트 폴더를 배포합니다.
- 배포 URL을 열어 확인합니다.
- 문구를 한 번 수정하고 다시 push해서 자동 배포를 확인합니다.
Cloudflare Pages에는 Direct Upload 방식도 있습니다. 하지만 이번 글에서는 GitHub 연동 방식을 씁니다.
이유는 간단합니다. GitHub와 연결해두면 이후 수정 사항을 push할 때마다 Cloudflare Pages가 다시 배포합니다. 홈페이지를 한 번 올리고 끝내는 것이 아니라 계속 고쳐볼 생각이라면 Git 연동이 더 자연스럽습니다.
용어 주석
- Git 연동: GitHub 저장소와 배포 서비스를 연결하는 방식입니다. GitHub에 새 변경을 올리면 배포 서비스가 그 변경을 다시 반영합니다.
- Direct Upload: GitHub를 거치지 않고 완성된 파일을 Cloudflare Pages에 직접 올리는 방식입니다.
- push: 내 컴퓨터의 변경 내용을 GitHub 저장소로 올리는 명령입니다.
준비물
아래 4개가 필요합니다.
| 준비물 | 설명 |
|---|---|
first-homepage 폴더 |
앞 글에서 만든 연습용 홈페이지 폴더 |
index.html 파일 |
AI 코딩 CLI가 만든 한 파일짜리 홈페이지 |
| GitHub 계정 | 코드를 올릴 저장소 |
| Cloudflare 계정 | Pages 배포에 사용 |
Git이 설치되어 있어야 합니다.
용어 주석
- Git: 파일이 언제, 어떻게 바뀌었는지 기록하는 도구입니다.
- PowerShell: Windows에서 명령어를 입력하는 프로그램입니다. 이 글의 명령어는 PowerShell 기준입니다.
- 저장소: 프로젝트 파일과 변경 기록을 모아두는 공간입니다. GitHub에서는 repository라고 부릅니다.
PowerShell에서 아래 명령어를 입력합니다.
git --version
버전이 나오면 Git이 설치된 것입니다.
설치되어 있지 않다면 Git for Windows를 먼저 설치합니다.
winget install Git.Git
설치 후 PowerShell을 닫았다가 다시 열고 git --version을 다시 확인합니다.
1단계: 홈페이지 폴더로 이동하기
파일 탐색기에서 바탕화면을 엽니다.
위쪽 주소창에 아래처럼 입력합니다.
powershell
PowerShell이 열리면 앞 글에서 만든 폴더로 들어갑니다.
cd first-homepage
파일이 있는지 확인합니다.
dir
목록에 index.html이 보여야 합니다.
브라우저에서 아직 확인하지 않았다면 파일을 직접 열어봅니다.
start .\index.html
여기서 홈페이지가 열려야 다음 단계로 넘어갈 수 있습니다.
2단계: Git 저장소 만들기
현재 폴더를 Git 저장소로 만듭니다.
git init -b main
Git 버전이 낮아 -b main 옵션이 안 된다면 아래처럼 해도 됩니다.
git init
git branch -M main
이제 파일을 추가하고 첫 커밋을 만듭니다.
git add index.html
git commit -m "Add first homepage"
용어 주석
- commit: 현재 파일 상태를 하나의 기록으로 남기는 작업입니다.
- commit message: 어떤 변경을 했는지 적는 짧은 설명입니다. 위 예시에서는
Add first homepage가 커밋 메시지입니다.
상태를 확인합니다.
git status
working tree clean 또는 커밋할 것이 없다는 문구가 나오면 로컬 준비는 끝난 것입니다.
3단계: GitHub에 저장소 만들기
GitHub에 로그인한 뒤 새 저장소를 만듭니다.
- GitHub 오른쪽 위
+버튼을 누릅니다. New repository를 선택합니다.- 저장소 이름을
first-homepage로 입력합니다. - 공개 여부를 선택합니다.
- README,
.gitignore, License는 체크하지 않습니다. Create repository를 누릅니다.
이미 로컬에 파일이 있으므로 GitHub에서 README를 먼저 만들지 않는 편이 쉽습니다.
용어 주석
- README: 프로젝트 소개와 사용법을 적는 설명 문서입니다.
- .gitignore: Git이 기록하지 않을 파일 목록을 적는 설정 파일입니다.
- License: 다른 사람이 이 코드를 어떤 조건으로 쓸 수 있는지 적는 문서입니다.
저장소가 만들어지면 GitHub가 원격 저장소 주소를 보여줍니다.
예시는 이런 형태입니다.
https://github.com/내아이디/first-homepage.git
PowerShell에서 아래 명령어를 입력합니다.
REMOTE-URL 부분은 자기 GitHub 저장소 주소로 바꿉니다.
git remote add origin REMOTE-URL
git remote -v
git push -u origin main
용어 주석
- remote: 내 컴퓨터 밖에 있는 원격 저장소입니다. 여기서는 GitHub 저장소를 뜻합니다.
- origin: 원격 저장소에 붙이는 기본 이름입니다.
- main: 프로젝트의 기본 작업 가지입니다. GitHub에서 보통 기본 브랜치로 사용합니다.
로그인을 묻는 화면이 나오면 GitHub 계정으로 인증합니다.
push가 끝나면 GitHub 저장소 페이지를 새로고침합니다. index.html 파일이 보이면 성공입니다.
GitHub CLI를 쓰는 경우
GitHub CLI가 설치되어 있다면 저장소 생성과 push를 한 번에 처리할 수 있습니다.
gh auth login
gh repo create first-homepage --source=. --public --remote=origin --push
용어 주석
- GitHub CLI: GitHub 작업을 웹사이트가 아니라 명령어로 처리하는 도구입니다. 명령어 이름은
gh입니다.- public 저장소: 누구나 볼 수 있는 저장소입니다.
- private 저장소: 접근 권한이 있는 사람만 볼 수 있는 저장소입니다.
비공개 저장소로 만들고 싶으면 --public 대신 --private을 사용합니다.
처음이라면 GitHub 웹사이트에서 저장소를 만들고 git remote add origin을 입력하는 방식이 더 이해하기 쉽습니다.
4단계: Cloudflare Pages에서 GitHub 연결하기
Cloudflare 대시보드에 로그인합니다.
- 왼쪽 메뉴에서
Workers & Pages로 갑니다. Create application을 누릅니다.Pages를 선택합니다.Connect to Git을 선택합니다.- GitHub 계정을 연결합니다.
- 방금 만든
first-homepage저장소를 선택합니다.
Cloudflare Pages Git 연동은 GitHub 또는 GitLab 저장소를 연결해서 배포하는 방식입니다. GitHub 저장소를 연결하면 이후 push할 때마다 자동으로 새 배포가 만들어집니다.
용어 주석
- 대시보드: Cloudflare에서 프로젝트, 도메인, 배포 상태를 관리하는 화면입니다.
- Workers & Pages: Cloudflare 안에서 서버리스 기능과 정적 사이트 배포 기능을 관리하는 메뉴입니다.
- GitLab: GitHub와 비슷한 코드 저장소 서비스입니다.
5단계: 빌드 설정하기
이번 홈페이지는 index.html 하나만 있는 정적 사이트입니다.
React, Next.js, Vite 같은 프레임워크를 쓰지 않습니다.
Cloudflare Pages 설정은 아래처럼 잡으면 됩니다.
| 항목 | 값 |
|---|---|
| Framework preset | None 또는 선택하지 않음 |
| Production branch | main |
| Build command | 비워둠 |
| Build output directory | / |
폴더 안에 index.html이 루트에 있기 때문에 Cloudflare Pages는 이 파일을 첫 화면으로 사용합니다.
용어 주석
- Framework preset: React, Next.js, Vite 같은 제작 도구를 Cloudflare가 미리 맞춰주는 설정입니다. 이번 글은
index.html하나만 쓰므로 선택하지 않아도 됩니다.- Production branch: 실제 배포에 사용할 기본 브랜치입니다. 여기서는
main입니다.- Build command: 배포 전에 사이트 파일을 만들어내는 명령어입니다. 이번 실습은 이미
index.html이 있으므로 비워둡니다.- Build output directory: 배포할 파일이 들어 있는 폴더입니다.
/는 현재 프로젝트의 가장 위 폴더를 뜻합니다.- 루트: 폴더 구조의 가장 위 위치입니다.
first-homepage/index.html에서index.html이 바로 보이면 루트에 있는 상태입니다.
설정 후 Save and Deploy를 누릅니다.
6단계: 배포 URL 확인하기
배포가 시작되면 Cloudflare Pages가 로그를 보여줍니다.
처음에는 조금 기다려야 합니다.
용어 주석
- 로그: 서비스가 어떤 작업을 처리했는지 시간순으로 보여주는 기록입니다. 배포가 실패하면 이 로그에서 원인을 찾습니다.
배포가 끝나면 이런 형태의 주소가 나옵니다.
https://first-homepage.pages.dev
실제 주소는 프로젝트 이름과 계정 상태에 따라 다를 수 있습니다.
주소를 클릭해서 홈페이지가 열리는지 확인합니다.
여기서 확인할 것은 4가지입니다.
- 첫 화면이 정상으로 보이는가
- 모바일 화면에서도 글자가 잘리지 않는가
- 버튼이나 링크가 의도한 대로 보이는가
- 수정해야 할 문구가 보이는가
배포 URL이 열리면 이번 실습의 핵심은 끝난 것입니다.
7단계: 문구를 수정하고 다시 배포해보기
GitHub 연동의 장점은 수정 후 다시 push하면 Cloudflare Pages가 자동으로 배포한다는 점입니다.
index.html을 VS Code나 메모장으로 엽니다.
예를 들어 첫 화면 문구를 조금 바꿉니다.
수정 후 PowerShell에서 아래 명령어를 입력합니다.
git status
git add index.html
git commit -m "Update homepage copy"
git push
Cloudflare Pages 대시보드로 돌아가면 새 배포가 시작됩니다.
배포가 끝난 뒤 같은 URL을 새로고침합니다.
문구가 바뀌었다면 GitHub 연동 배포 흐름까지 확인한 것입니다.
자주 막히는 지점
index.html이 안 보이는 경우
PowerShell 위치가 잘못됐을 수 있습니다.
pwd
dir
현재 위치가 first-homepage 폴더인지, index.html이 그 안에 있는지 확인합니다.
git push에서 로그인이 막히는 경우
GitHub 인증이 필요합니다.
브라우저 로그인 창이 뜨면 안내에 따라 로그인합니다.
GitHub CLI를 쓴다면 아래 명령어로 먼저 인증할 수 있습니다.
gh auth login
Cloudflare에서 저장소가 안 보이는 경우
GitHub 연결 권한 문제일 수 있습니다.
Cloudflare Pages에서 GitHub 연결을 다시 진행하고, 저장소 접근 권한을 확인합니다. 조직 저장소라면 조직 권한이 추가로 필요할 수 있습니다.
배포는 됐는데 404가 나오는 경우
대부분 index.html 위치 문제입니다.
Cloudflare Pages가 배포한 폴더의 루트에 index.html이 있어야 합니다.
이번 실습 구조는 아래처럼 단순해야 합니다.
first-homepage/
└─ index.html
first-homepage/index.html을 다시 한 번 확인합니다.
Direct Upload는 언제 쓰나
Cloudflare Pages에는 GitHub 연결 없이 파일을 직접 올리는 Direct Upload 방식도 있습니다.
내 컴퓨터에서 만든 파일을 빠르게 올려보고 싶을 때는 이 방식도 괜찮습니다.
다만 이번 실습에서는 Git 연동을 추천합니다.
이유는 이후 수정 흐름 때문입니다.
index.html수정git commitgit push- Cloudflare Pages 자동 배포
- 같은 URL에서 결과 확인
이 반복이 만들어져야 AI 코딩 CLI로 만든 결과물을 계속 고쳐볼 수 있습니다.
Cloudflare 문서 기준으로 Git 연동 프로젝트와 Direct Upload 프로젝트는 나중에 서로 전환할 수 없으므로, 처음 만들 때 방식을 나눠서 생각하는 편이 좋습니다.
다음 단계
여기까지 하면 index.html 하나로 만든 홈페이지가 실제 URL을 갖게 됩니다.
이제 AI 코딩 CLI에게 이런 식으로 요청할 수 있습니다.
현재 홈페이지를 모바일에서 더 읽기 좋게 수정해줘.
수정 후 어떤 부분을 바꿨는지 설명하고, 내가 git diff로 확인할 수 있게 해줘.
수정이 마음에 들면 다시 commit하고 push합니다.
git status
git diff
git add index.html
git commit -m "Improve mobile layout"
git push
이 흐름이 만들어지면 AI 코딩 CLI 실습은 채팅에서 끝나지 않습니다.
파일이 바뀌고, GitHub에 기록되고, Cloudflare Pages에 배포되고, 실제 URL에서 확인됩니다.
AI 코딩 CLI 배포 실습이 필요하다면
Codex CLI, Claude Code, GitHub, Cloudflare Pages를 한 번에 실습하는 교육이 필요하면 문의할 수 있습니다.
초보자 기준으로 설치, 첫 홈페이지 제작, GitHub 업로드, Cloudflare Pages 배포, 도메인 연결까지 순서대로 다룹니다.