IT/코딩

IT/코딩 자료를 다루는 공간입니다.

DEV_MANUAL

Cloudflare-GitHub 자동 배포(CI/CD) 연동 가이드
dev_manual2026-05-08

Cloudflare-GitHub 자동 배포(CI/CD) 연동 가이드

Cloudflare Workers GitHub 자동 배포(CI/CD) 설정 이 문서는 GitHub 저장소와 Cloudflare Workers를 연결하여 git push만으로 자동 배포(CI/CD)가 이루어지도록 설정하는 방법을 설명합니다. 최초 한 번만 연결해 두면 이후에는 별도의 wrangler deploy 명령 없이 GitHub에 코드를 업로드하는 것만으로 자동 배포가 진행됩니다. 1. 사전 준비 자동 배포를 설정하기 전에 아래 조건이 충족되어 있어야 합니다. 로컬 프로젝트가 Git으로 관리되고 있어야 합니다. GitHub 원격 저장소가 생성되어 있어야 합니다. 로컬 코드가 GitHub main 브랜치까지 정상적으로 Push되어 있어야 합니다. Cloudflare 계정에 대상 Workers 프로젝트가 생성되어 있어야 합니다. 2. GitHub 저장소 연결 2-1. Cloudflare Dashboard 접속 Cloudflare Dashboard에 로그인한 후 아래 메뉴로 이동합니다. Workers & Pages └── 대상 Worker 선택 2-2. 설정 메뉴 이동 상단의 설정(Settings) 탭을 선택합니다. 2-3. Git 저장소 연결 빌드(Build) 또는 Git 연동 항목에서 연결(Connect) 버튼을 클릭합니다. GitHub 인증 창이 나타나면 로그인 후 연결할 저장소를 선택합니다. Cloudflare가 GitHub 저장소에 접근할 수 있도록 권한을 승인합니다. 3. 빌드 설정 확인 대부분의 경우 기본 설정 그대로 사용하면 됩니다. 항목 설정 설명 Production Branch main 배포 대상 브랜치 Build Command 비워두거나 자동 인식 Workers 프로젝트는 대부분 별도 설정이 필요 없습니다. Root Directory / 프로젝트 루트 폴더 설정을 확인한 후 Save and Deploy 버튼을 클릭합니다. 최초 연결 시 Cloudflare가 현재 GitHub 코드를 가져와 한 번 배포를 수행합니다. 4. 자동 배포가 동작하는 원리 GitHub 저장소가 연결되면 이후부터는 Cloudflare가 저장소의 변경 사항을 자동으로 감지합니다. 1단계. 코드 업로드 개발자가 로컬에서 아래 명령어를 실행합니다. git push 2단계. 자동 빌드 Cloudflare가 GitHub 변경 사항을 감지한 후 자동으로 코드를 내려받아 빌드를 시작합니다. 3단계. 자동 배포 빌드가 성공하면 새로운 버전이 즉시 운영 환경에 배포됩니다. 별도의 wrangler deploy 명령을 실행할 필요가 없습니다. 5. 개발 시 권장 워크플로우 평소 개발은 아래 순서로 진행하는 것을 권장합니다. 1단계. 기능 개발 VS Code에서 원하는 기능을 개발합니다. 2단계. 로컬 테스트 npx wrangler dev 브라우저에서 충분히 테스트한 후 이상이 없는지 확인합니다. 3단계. GitHub 업로드 git add . git commit -m "변경 내용" git push Push가 완료되면 Cloudflare가 자동으로 빌드와 배포를 수행합니다. 6. 배포 실패 시 확인 방법 배포에 실패하면 Cloudflare Dashboard에서 원인을 확인할 수 있습니다. 아래 메뉴로 이동합니다. Workers & Pages └── 대상 Worker └── Deployments 배포 목록에서 실패한 항목을 선택하면 빌드 로그와 오류 메시지를 확인할 수 있습니다. 대부분의 배포 실패는 다음과 같은 원인으로 발생합니다. JavaScript 문법 오류 누락된 npm 패키지 환경 변수 미설정 빌드 스크립트 오류 7. 주의사항 GitHub 자동 배포를 사용하는 경우에는 GitHub 저장소를 기준(SSOT, Single Source of Truth)으로 관리하는 것이 좋습니다. 즉, Cloudflare Dashboard의 웹 에디터에서 직접 코드를 수정하지 말고, 항상 로컬 프로젝트에서 수정한 후 GitHub에 Push하는 방식을 유지하는 것을 권장합니다. 이렇게 하면 로컬 프로젝트와 운영 서버의 코드가 항상 동일하게 유지되어 버전 관리와 협업이 훨씬 쉬워집니다. 정리 GitHub 자동 배포를 설정하면 운영 과정이 매우 단순해집니다. 코드 수정 ↓ npx wrangler dev ↓ git add . ↓ git commit -m "변경 내용" ↓ git push ↓ Cloudflare 자동 빌드 ↓ 운영 서버 자동 배포 최초 연결만 완료하면 이후에는 git push 한 번으로 최신 코드가 자동 배포되므로, 보다 안정적이고 효율적인 개발 환경을 구축할 수 있습니다.

자세히 보기 →

DEV_MANUAL

VS Code에서 GitHub 저장소 연결 및 Git 코드 관리 가이드
dev_manual2026-05-08

VS Code에서 GitHub 저장소 연결 및 Git 코드 관리 가이드

GitHub 저장소 연결 및 코드 업로드(Git Push) 본 문서는 로컬에서 개발한 프로젝트를 GitHub 저장소에 효율적으로 업로드하고 관리하는 방법, 그리고 Git 인증 시 발생할 수 있는 일반적인 오류 해결 방안을 상세히 안내합니다. 최초 한 번의 설정만으로 이후에는 간결한 명령어를 통해 GitHub와의 연동 및 코드 업로드를 손쉽게 진행할 수 있습니다. 1. Git 사용자 정보 등록 (최초 1회 설정) Git은 커밋 작성자를 식별하기 위해 사용자 이름과 이메일 정보를 필요로 합니다. 이 설정은 개발 환경 PC당 한 번만 수행하면 영구적으로 적용됩니다. 1-1. 이메일 등록 git config --global user.email "사용자 이메일" 예시 git config --global user.email "example@gmail.com" 1-2. 사용자 이름 등록 git config --global user.name "사용자 이름" 예시 git config --global user.name "Hong Gil Dong" TIP 등록된 사용자 정보는 다음 명령어를 통해 언제든지 확인할 수 있습니다. git config --global --list 2. 로컬 저장소 초기화 및 첫 커밋 생성 프로젝트 폴더를 Git 저장소로 초기화하고, 현재 작업 내용을 첫 번째 버전으로 기록합니다. 2-1. Git 저장소 초기화 git init 현재 작업 디렉터리가 Git 저장소로 변환됩니다. 2-2. 변경 파일 스테이징 git add . 현재 디렉터리의 모든 변경된 파일을 커밋 대상으로 등록(스테이징)합니다. 2-3. 첫 번째 커밋 생성 git commit -m "Initial commit" 프로젝트의 현재 상태를 하나의 확정된 버전으로 저장합니다. 3. GitHub 원격 저장소 연결 로컬 Git 저장소와 GitHub 상의 원격 저장소를 연결하는 과정입니다. 3-1. GitHub 저장소 주소 연결 GitHub에서 해당 저장소의 Code → HTTPS 섹션에서 저장소 주소를 복사한 후, 다음 명령어를 실행합니다. git remote add origin https://github.com/사용자명/저장소명.git 예시 git remote add origin https://github.com/example/my-project.git 3-2. 기본 브랜치를 main으로 설정 git branch -M main GitHub의 기본 브랜치인 main과 일치시켜 브랜치 충돌 가능성을 최소화하는 것을 권장합니다. 4. 최초 코드 업로드(Push) 로컬 저장소의 내용을 GitHub 원격 저장소로 최초 업로드하는 단계입니다. git push -u origin main 여기서 -u 옵션은 원격 저장소 'origin'의 'main' 브랜치를 현재 로컬 브랜치의 상위 스트림(upstream)으로 설정하여, 이후부터는 단순히 git push 명령만으로 업로드가 가능하게 합니다. 5. Git 인증 오류 해결 방법 (Windows 환경) Windows 환경에서 git push 실행 시 인증 창이 나타나지 않고 터미널이 무한 대기 상태가 되는 경우가 발생할 수 있습니다. 증상 git push 실행 후 시스템 반응 없음 인증 팝업 창이 나타나지 않음 터미널이 지속적으로 대기 모드 유지 원인 Git Credential Manager의 로그인 창이 백그라운드에 숨겨졌거나, 인증 세션이 정상적으로 연결되지 않을 때 발생합니다. 해결 방법 VS Code 좌측 사이드바에서 Source Control 메뉴를 선택합니다. Publish Branch 또는 Sync Changes 버튼을 클릭합니다. VS Code 상단에 표시되는 알림에서 Allow를 선택하여 인증을 허용합니다. 자동으로 브라우저가 열리면 GitHub 계정으로 로그인 과정을 완료합니다. 인증이 완료된 후 VS Code로 돌아와 코드 업로드가 정상적으로 완료되었는지 확인합니다. 한 번 성공적으로 인증을 완료하면, 이후부터는 대부분 별도의 로그인 절차 없이 Git 작업을 수행할 수 있습니다. 6. 일상적인 Git 작업 순서 프로젝트 수정 후에는 다음 세 가지 명령어를 반복하여 Git 저장소를 관리합니다. 1단계. 변경 파일 스테이징 git add . 2단계. 변경 내용 커밋 git commit -m "변경한 내용 요약" 예시 git commit -m "로그인 기능 추가 및 버그 수정" 3단계. GitHub에 업로드 git push 정리 최초 설정은 다소 번거롭게 느껴질 수 있지만, 한 번만 완료하면 됩니다. 이후에는 다음 세 가지 필수 Git 명령어만 기억하면 대부분의 버전 관리 작업을 효율적으로 수행할 수 있습니다. git add . git commit -m "변경 내용 요약" git push 이 세 단계의 반복적인 숙달을 통해 프로젝트의 버전 관리와 GitHub를 통한 안전한 코드 백업을 체계적으로 진행할 수 있습니다.

자세히 보기 →

DEV_MANUAL

VS Code 설치 및 Cloudflare 배포 매뉴얼 (D1 데이터베이스 생성)
dev_manual2026-05-07

VS Code 설치 및 Cloudflare 배포 매뉴얼 (D1 데이터베이스 생성)

Cloudflare Workers + D1 개발 환경 구축 이 문서는 Cloudflare Workers 프로젝트 생성부터 D1 데이터베이스 생성, 테이블 구축, 로컬 개발 및 최초 배포까지의 과정을 순서대로 정리한 매뉴얼입니다. 처음 Cloudflare를 사용하는 경우에도 그대로 따라 하면 개발 환경을 구축할 수 있습니다. 1. 로컬 개발 환경 준비 Cloudflare Workers는 Node.js 기반으로 개발되므로 먼저 개발 환경을 준비해야 합니다. Windows에서는 Scoop을 이용하면 Node.js와 VS Code를 간편하게 설치할 수 있습니다. 1-1. PowerShell 실행 Windows의 PowerShell 또는 Windows Terminal을 실행합니다. TIP PowerShell 버전이 오래되면 Scoop 설치가 정상적으로 진행되지 않을 수 있습니다. 가능하면 최신 PowerShell을 설치한 후 진행하는 것을 권장합니다. 1-2. Scoop 설치 PowerShell에서 아래 명령어를 차례대로 실행합니다. Set-ExecutionPolicy RemoteSigned -Scope CurrentUser iwr -useb get.scoop.sh | iex 설치가 완료되면 scoop 명령어를 사용할 수 있습니다. 1-3. Node.js 설치 아래 명령어를 실행합니다. scoop install nodejs Node.js는 Cloudflare Workers 및 Wrangler 실행에 반드시 필요합니다. 1-4. Visual Studio Code 설치 아래 명령어를 실행합니다. scoop install vscode 설치가 완료되면 VS Code를 실행합니다. 1-5. 작업 폴더 열기 VS Code에서 프로젝트를 저장할 폴더를 엽니다. 메뉴 → File → Open Folder 예시 Z:\workspace\nodejs 2. Cloudflare Workers 프로젝트 생성 2-1. 프로젝트 생성 VS Code에서 Ctrl + ~를 눌러 터미널을 연 뒤 아래 명령어를 실행합니다. npm create cloudflare@latest 프로젝트명 예시 npm create cloudflare@latest my-worker 잠시 후 여러 질문이 나타나며 아래와 같이 선택합니다. 2-2. 프로젝트 생성 옵션 질문 선택 설명 Which template would you like to use? Worker only 가장 기본적인 Workers 프로젝트를 생성합니다. Which language do you want to use? JavaScript 빠르게 개발하기에 가장 적합합니다. Do you want to add an AGENTS.md file? Yes AI 코딩 도구가 프로젝트 구조를 이해하는 데 도움이 됩니다. Do you want to use git? Yes 버전 관리를 위해 Git 사용을 권장합니다. Do you want to deploy your application? No 먼저 로컬에서 테스트 후 배포합니다. 3. 로컬 실행 및 최초 배포 3-1. 프로젝트 폴더 이동 cd 프로젝트명 VS Code를 현재 프로젝트로 다시 엽니다. code . -r 3-2. 코드 수정 Explorer에서 src/index.js 파일을 열고 원하는 코드를 작성한 후 저장합니다. 3-3. 로컬 서버 실행 npx wrangler dev 브라우저에서 아래 주소를 열어 정상적으로 동작하는지 확인합니다. http://localhost:8787 수정한 내용이 출력되면 로컬 실행이 성공한 것입니다. 3-4. Cloudflare 로그인 (최초 1회) 로컬 서버를 종료합니다. Ctrl + C 이후 아래 명령어를 실행합니다. npx wrangler login 브라우저가 열리며 Cloudflare 로그인을 진행하면 Wrangler와 계정이 연결됩니다. 최초 한 번만 수행하면 됩니다. 3-5. Workers 배포 npx wrangler deploy 배포가 완료되면 Workers URL이 출력됩니다. 브라우저에서 접속하여 정상적으로 서비스되는지 확인합니다. 4. Cloudflare D1 데이터베이스 생성 (선택 사항) 4-1. Cloudflare Dashboard 접속 Cloudflare Dashboard에 로그인합니다. 4-2. D1 메뉴 이동 왼쪽 메뉴에서 Workers & Pages └── D1 을 선택합니다. 4-3. 데이터베이스 생성 Create database 버튼을 클릭합니다. Database Name에 원하는 이름을 입력한 뒤 생성합니다. 4-4. Database ID 저장 데이터베이스 상세 화면에서 Database ID를 복사하여 보관합니다. 이 값은 나중에 wrangler.jsonc 또는 wrangler.toml 설정 시 필요합니다. 5. D1 테이블 생성 5-1. SQL Console 열기 생성한 D1 데이터베이스를 선택한 뒤 상단의 Console 탭을 클릭합니다. 5-2. SQL 작성 예시 CREATE TABLE tb_dream ( id INTEGER PRIMARY KEY AUTOINCREMENT, title TEXT NOT NULL, content TEXT, reg_date DATETIME DEFAULT CURRENT_TIMESTAMP ); 필요한 컬럼을 프로젝트에 맞게 수정합니다. 5-3. SQL 실행 오른쪽 아래의 Execute 버튼을 클릭합니다. Success 메시지가 출력되면 테이블 생성이 완료됩니다. 다음 단계 이제 Workers에서 D1을 바인딩한 후 SQL을 실행하여 데이터를 조회하거나 저장할 수 있습니다.

자세히 보기 →