[병원 휴가관리 시스템 #2] Github에 올리고 Vercel에 배포하는 자동 파이프라인 구축기

내 코드를 세상에 내보내는 법 — GitHub + Vercel 실전 이야기

병원 휴가관리시스템을 만들면서 실제로 겪은 일들을 솔직하게 씁니다.
"이게 뭔지 모르겠다"는 시점부터 "고치면 바로 배포"가 습관이 된 시점까지.

시작하기 전에: 전체 그림

복잡하게 생각할 것 없습니다. 딱 이겁니다:

내 컴퓨터에서 코드 작성
       ↓
  git commit      ← "이 시점에 저장"
       ↓
  git push        ← "GitHub에 업로드"
       ↓
  vercel --prod   ← "인터넷에 공개"
       ↓
  URL로 누구나 접속 가능!

익숙해지면 코드 고치고 배포하는 데 1분도 안 걸립니다. 처음에만 낯설 뿐이에요.

1. GitHub — "코드의 구글 드라이브"

GitHub가 뭔가요?

쉽게 말하면 코드 전용 구글 드라이브입니다.

내 컴퓨터에만 저장해두면 어떻게 될까요? 컴퓨터가 고장나면 끝입니다. 카페에서 작업하다 맥북을 놓고 왔다면? 역시 끝입니다. GitHub에 올려두면 어디서든 꺼낼 수 있고, 3개월 전 코드로도 돌아갈 수 있어요.

저희 스터디인 "개발환경셋팅"에서는 1주차 첫 시간에 가장 먼저 '깃'에 대해 배웠습니다. 중요한 것은 '커밋'을 해서 작업한 것은 그때그때 저장해 놓는 것이었습니다. 그런데 이렇게 '깃'으로 '커밋'한 것은 로컬 작업 공간에 저장되는 것입니다. 즉, 내 컴퓨터 저장소에만 저장되는 것이죠. 만약 컴퓨터가 고장난다면? 다른 컴퓨터에서 작업하고 싶다면? 우리가 사진을 클라우드에 보관하는 것처럼, 우리의 작업도 클라우드에 저장하고 싶을 때가 있습니다. 그 클라우드 역할을 하는 곳이 '깃허브'입니다.

저장소 만들기

GitHub(github.com)에 접속해서:

1. 오른쪽 위 + 버튼 → New repository

2. 이름: clinic

3. Private 선택 ← 직원 이름, 연차 정보가 들어가니까 비공개 필수!

4. Create repository 클릭

그러면 이런 화면이 나옵니다:

…or push an existing repository from the command line

git remote add origin https://github.com/tearess/clinic.git
git branch -M main
git push -u origin main

GitHub가 친절하게 "이 명령어를 터미널에서 실행하면 연결돼요"라고 알려주는 겁니다. 그대로 복붙하면 됩니다.

2. 첫 커밋 — "저장" 버튼 누르기

Git이 뭔가요?

워드에서 Ctrl+Z로 실수를 되돌리듯, Git은 코드의 변경 이력을 관리합니다. "이 시점에 이런 코드였다"를 저장해두는 행위를 커밋(commit) 이라고 합니다.

실제로 한 것들

프로젝트 폴더에서 터미널을 열고:

# Git 초기화 — 이 폴더를 Git이 관리하게 만들기 (딱 한 번)
git init

# GitHub 저장소와 연결 (딱 한 번)
git remote add origin https://github.com/tearess/clinic.git

그 전에 먼저 해야 할 중요한 일이 있습니다.

절대로 빠뜨리면 안 되는 것: .gitignore

.gitignore 파일을 만들고 이렇게 씁니다:

.env.local
.env*.local
node_modules/
.next/

이게 왜 중요하냐고요?

.env.local에는 Airtable API Key 같은 비밀 정보가 들어있습니다. 이게 GitHub에 올라가면 전 세계 누구나 볼 수 있어요. .gitignore는 "이 파일들은 GitHub에 올리지 마"라고 알려주는 목록입니다.

실제로 이 프로젝트에서도 처음에 .gitignore를 제대로 설정 안 했다가 4ca2d82 커밋에서 뒤늦게 수정했습니다. 처음부터 챙겨두세요.

# 모든 파일을 "올릴 준비" 상태로
git add .

# "첫 생성"이라는 메모와 함께 저장
git commit -m "첫 생성"

# GitHub에 올리기
git push -u origin main

이게 이 프로젝트의 첫 번째 커밋입니다:

631064d  2026-03-26  첫 생성

3월 26일, 드디어 코드가 GitHub에 올라갔습니다.

3. Vercel — "내 앱을 인터넷에 켜두는 서버"

Vercel이 뭔가요?

npm run dev로 실행한 앱은 내 컴퓨터에서만 열립니다. Vercel은 이걸 인터넷 어디서나 접속 가능한 URL로 만들어줍니다.

예전엔 서버를 직접 구매하고, 리눅스를 설치하고, Node.js를 설정하고... 하는 복잡한 과정이 필요했습니다. Vercel을 쓰면 그냥 명령어 하나면 끝납니다.

프로젝트 연결하기

# Vercel CLI 설치 (딱 한 번)
npm install -g vercel

# "이 프로젝트를 Vercel과 연결"
vercel link

vercel link를 실행하면 이런 대화가 나옵니다:

? Set up "~/gpters/clinic"? → Y
? Which scope do you want to deploy to? → 내 계정 선택
? Link to existing project? → N  (새로 만들 거니까)
? What's your project's name? → <font color="#245bdb">clinic</font>
? In which directory is your code located? → ./
✓  Linked to tearess-projects/clinic

완료되면 .vercel/project.json 파일이 생깁니다. 이 파일이 있어야 나중에 vercel --prod 명령어가 "어떤 프로젝트에 올릴지" 알 수 있습니다.

사실 위와 같은 방법으로 하면 됐을테지만, 저는 아무래도 비개발자로서 cli에 익숙하지 않다보니 Vercel 웹사이트에 접속해서 GUI로 입력하는 편을 택했습니다.

Vercel.com에 들어가면 먼저 로그인 창이 뜹니다.

ALT

컴퓨터의 로그인 화면 스크린샷

저는 vercel을 github id로 가입했습니다. github와 vercel이 일체로 움직이는 것을 생각하면, 확실히 vercel은 github id로 가입하는 것이 편합니다. 물론 구글이나 애플, 다른 이메일로 가입하셔도 됩니다.

로그인을 하면 다음과 같이 뭔가 영어로 가득한, 알 수 없는 화면이 나옵니다. 혹시나 한국어 메뉴를 지원하나 둘러보았지만, 그런 것은 없었습니다.

ALT

컴퓨터의 설정 메뉴 스크린샷

여기서 오른쪽 상단의 Add New... 부분의 꺽쇠를 클릭하면

Project, Domain, Store, Integration, Team Member가 나옵니다. 다른 것은 무서워서(?) 건드리지 못하고, 가장 만만하고 위에 있는 Project 메뉴를 클릭합니다.

New Project라고 하면서 이런 화면이 나옵니다. 왼쪽 아래에 보니 저의 Git Repository가 나와 있습니다.

우리가 집중해야 할 곳은 바로 이 곳입니다.

ALT

gi repo 가져오기 - gi repo를 가져오는 방법

제가 안티그래비티에서 버튼 몇 개 눌러서 Git Repository에 몇 개 올려놓은 프로젝트들인데, 여기서 clinic 작업을 import하면 됩니다.

import하면 github repository에 올라와 있는 프로그램이 vercel에 연동됩니다. 그러면 저의 안티그래비티와 github-vercel에 견고한 파이프라인이 생겨서 안티그래비티에서 작업해서 버튼 딸깍하면 깃허브에 올라가고, 그것이 자동으로 vercel까지 배포가 됩니다.

그런데 각각 프로젝트 이름 앞에 있는 아이콘은 뭘까요? 잘 모르겠어서 각각을 클릭해서 살펴보니, 저 아이콘들의 정체는 'Application Preset'이었습니다.

즉, 제 짐작으로는 어떤 애플리케이션을 쓸 것인가, 어떤 애플리케이션이 이 프로젝트에서 돌아가는 것인가? 하는 것을 의미하는 것으로 대충 이해했습니다.

ALT

새 프로젝트 화면의 스크린샷

여하튼 import를 클릭하면, New Project라는 페이지로 넘어가면서, 앞에서 말씀드린 vercel link를 cli에서 실행할 때 나오는 질문을 GUI 형태로 만든 것이 나옵니다.

? Set up "~/gpters/clinic"? → Y
? Which scope do you want to deploy to? → 내 계정 선택
? Link to existing project? → N  (새로 만들 거니까)
? What's your project's name? → <font color="#245bdb">clinic</font>
? In which directory is your code located? → ./
✓  Linked to tearess-projects/clinic

위의 질문들이 결국 이 화면에 GUI 형태로 담아져 있는 것이라 보면 되겠습니다.

Project Name을 설정하고, Application Preset을 설정하고(이거 뭘로 설정하는지 모르시겠으면 클로드 코드에게 물어보시면 됩니다), 맨 아래에 있는 Deploy 버튼을 누르시면 됩니다.

사실 저 Deploy 버튼 바로 위에 있는 두 꺽쇠모양의 버튼에는 무시무시한(?) 내용이 담겨져 있습니다. 그것을 설정해줘야만 하지만, 차마 못하고 그냥 Deploy를 해버렸습니다.

4. 환경 변수 — "비밀번호는 따로 보관"

문제 상황

.env.local에 비밀 정보가 있고, 이 파일은 GitHub에 안 올라갑니다. 그러면 Vercel은 어떻게 Airtable에 접근할까요?

답: Vercel에도 따로 알려줘야 합니다.

vercel env add AIRTABLE_API_KEY production
# → 값을 입력하라고 나옵니다. 붙여넣기 후 Enter

vercel env add AIRTABLE_BASE_ID production
vercel env add NEXTAUTH_SECRET production
vercel env add NEXTAUTH_URL  # 실제 배포 URL로 변경

또는 Vercel 웹사이트(vercel.com)에서 프로젝트 → Settings → Environment Variables에서 GUI로 넣어도 됩니다.

다시 vercel 대시보드로 돌아옵니다. 돌아오는 방법은 좌측 상단의 xxxx(본인 아이디)'s projects를 클릭하시면 됩니다.

돌아오면 이렇게 왼쪽에 Projcts가 선택되어 있고, 오른쪽에는 배포된 프로젝트가 있을 것입니다. 저는 그 중에 하나인 방금 배포한 왼쪽 상단에 있는 프로젝트를 선택하겠습니다.

ALT

어도비 어도비 어도비 어도비 어도비의 스크린샷

프로젝트를 선택하면 이제 배포된 프로젝트의 도메인 주소가 나옵니다. 저 도메인 주소를 클릭하면 해당 웹페이지가 열립니다. 그런데 그 전에 반드시 해 주셔야 할 일이 있습니다. 바로 앞에서 말씀드린 환경변수 설정입니다.

이 화면 왼쪽 맨 아래에 Settings가 있습니다. 이걸 선택하시면 이 프로젝트의 settings을 하실 수 있습니다. 다른 것은 무서워서 못 건드리겠고, 저는 왼쪽 메뉴 중 위에서 4번째 Environment Variables를 선택했습니다.

바로 이 화면이 이 프로젝트에서 가장 중요한 환경변수를 설정하는 화면입니다. 이 환경변수는 Airtable의 Base ID와 Airtable의 API Key가 주요 내용이고, 잘 모르겠지만 NEXTAUTH_URL 값과 NEXTAUTH_SECRET 값도 넣어야 했습니다.

본 프로그램이 Airtable을 이용해서 회원관리를 하기 때문에 당연히 Airtable의 Base와 API 키값을 넣어줘야 연동이 된다는 것은 알겠지만, NEXTAUTH는 뭘까 궁금했습니다(물론 이 프로그램을 만들 당시에는 그런 생각 없이 넣으라는 것을 최대한 빨리 넣기에 급급했습니다).

그래서 클로드 코드에 물어본 결과 아래와 같은 답을 얻었습니다.

NextAuth.js (현재는 Auth.js로 리브랜딩)는 Next.js 전용 인증 라이브러리입니다.

뭘 해주냐면

• 로그인/로그아웃 세션 관리

• Google, GitHub, Kakao 같은 소셜 로그인 (OAuth) 연동

• 이메일/비밀번호 자체 로그인도 지원

• JWT 또는 DB 세션 방식 선택 가능

두 환경변수의 역할

이 프로젝트에서는?

clinic/.env.local을 보면 NEXTAUTH_URL이 Vercel 배포 URL로 설정되어 있고, NEXTAUTH_SECRET은 랜덤 생성된 키입니다. 즉 이 clinic 앱에 로그인 기능이 구현되어 있다는 뜻입니다.

그래서 이렇게 4개의 환경변수를 넣어주어야 합니다.

이걸 빠뜨리면 배포는 성공해도 앱이 안 됩니다. 실제로 처음에 이것 때문에 "배포했는데 왜 로그인이 안 되지?" 하고 한참 헤맸습니다.

5. 첫 배포 — 두근두근

vercel --prod

이걸 실행하면 터미널에 이런 내용이 쭉 나옵니다:

Deploying tearess-projects/clinic
Uploading [====================] (23.4KB)
Building...
✓ Compiled successfully
✓ Generating static pages (37/37)
✓ Build Completed in 31s

Aliased: https://clinic-phi-blue.vercel.app  ← 이게 실제 URL!

저 URL을 브라우저에 붙여넣으면... 실제로 열립니다. 스마트폰으로 접속해도 됩니다. 친구한테 링크 보내줘도 됩니다.

처음 배포했을 때의 그 뿌듯함은 직접 경험해봐야 압니다.

5-1. 이제는 세 개가 한 몸처럼 움직입니다

처음 설정을 마치고 나면, 이제부터 개발 방식이 완전히 달라집니다.

안티그래비티(Claude Code)에서 작업하고 → 커밋하고 → GitHub에 올리면 → Vercel이 자동으로 반영됩니다.

안티그래비티에서 "버튼 색깔 바꿔줘" 라고 말한다
       ↓
  Claude Code가 코드를 수정한다
       ↓
  git commit + git push  ← 이것도 Claude Code가 해줍니다
       ↓
  vercel --prod          ← 이것도요
       ↓
  30초 뒤 실제 사이트에 반영 완료

안티그래비티 — GitHub — Vercel, 이 세 개가 한 몸처럼 연동되는 겁니다.

예전이라면 코드 에디터 열고, 파일 찾아서 수정하고, 터미널에서 git 명령어 치고, Vercel 배포 명령어 치고... 이걸 혼자 다 해야 했습니다. 지금은 대화하듯이 말하면 끝납니다.

"공휴일이 있는 주에는 휴일 신청이 안 되게 해줘"
→ Claude Code가 어느 파일을 고쳐야 하는지 찾고, 로직을 수정하고, 빌드 테스트하고, 커밋 메시지까지 써서 배포합니다.

이게 이 프로젝트를 4일 만에 완성할 수 있었던 이유입니다.

6. 이후 — 고치고, 커밋하고, 배포하고, 반복

첫 배포 이후부터는 이 사이클을 계속 반복합니다. 이 프로젝트에서 실제로 어떻게 진행됐는지 날짜별로 보겠습니다.

3월 26~27일: "일단 만들었다"

631064d  첫 생성
bc98150  1차 검증 완료
f8c55cd  실제 실행 준비작업 완료
4ca2d82  feat: Phase 4 배포 준비 완료 + gitignore 추가

로그인, 연차 신청, 휴일 신청 같은 기본 기능을 만들었습니다. 완벽하지 않아도 일단 돌아가게 만들고 배포했습니다.

핵심 원칙: 완벽하게 만들고 배포하려 하지 마세요. 일단 올리고 고치는 게 훨씬 빠릅니다.

3월 27일: "버그 대잔치"

실제로 써보니까 문제가 쏟아졌습니다:

d0849da  fix: API 응답 이중 래핑 버그 수정
1d2ce94  fix: 캘린더 월 이동 시 리셋되는 버그 수정
9284329  fix: 공휴일 빨간색 표시 CSS 선택자 수정
3c5095b  fix: 토요일 공휴일은 빨간색 우선 표시
43df6f2  fix: 공휴일 이름이 날짜 아래에 잘 보이도록 타일 레이아웃 조정

하루에 버그 수정만 5번 커밋하고 5번 배포했습니다. 이게 이상한 게 아니에요. 실제로 쓰기 전까지는 모르는 버그가 항상 있습니다.

버그를 발견하면:

# 코드 고치기
git add .
git commit -m "fix: 캘린더 월 이동 시 리셋되는 버그 수정"
vercel --prod

이 세 줄이면 1분 안에 배포됩니다.

3월 27일: "회원가입을 추가했더니..."

d35537b  feat: 회원가입 기능 추가
f7947bf  feat: 회원가입 시 관리자 승인 필요하도록 변경
de8ae7d  fix: 회원가입 시 존재하지 않는 EmployeeID 필드 제거

회원가입 기능을 추가하고 테스트했더니, API가 Airtable에 없는 EmployeeID 필드를 보내고 있었습니다. 에러가 났고, 즉시 수정해서 다시 배포했습니다.

새 기능을 추가할 때는 이렇게 커밋 3개가 연달아 나오는 게 정상입니다. 기능 추가 → 테스트 중 문제 발견 → 수정 이 사이클이 반복됩니다.

3월 27~28일: "가입했는데 왜 로그인이 되지?"

6817ab2  fix: 관리자 미승인 계정의 로그인 차단
a55dbc9  feat: 직원 상태를 재직/퇴직/미승인 3단계로 분리
e64e5f1  fix: 직원 정보 수정 시 비밀번호 미입력 허용
f8178db  feat: 관리자 대시보드에 미승인 가입 요청 알림 표시

처음엔 직원 상태가 "재직/퇴직" 두 가지뿐이었습니다. 그런데 "가입 신청한 사람이 관리자 승인 전에 로그인이 된다"는 문제가 발견됐습니다.

해결책: 미승인(pending) 상태를 추가해서 3단계로 만들었습니다.

이렇게 하나를 고치면 다른 곳에 영향이 생깁니다. 그래서 커밋을 잘게 쪼개두면, "어디서 문제가 생겼는지"를 나중에 추적하기 쉽습니다.

3월 28일: "사실 이것도 고쳐야 했어"

5e6418a  feat: 휴일 시스템 개편 — 반차 지원, 1개월 이월, 공휴일 주 미발생
fda1fe6  feat: 캘린더 타일에 휴가/휴일 이벤트를 점 대신 이름 텍스트로 표시
81422eb  fix: 연차 목록 조회 버그 수정 및 캘린더 텍스트 가시성 개선

쓰다 보니 "이건 좀 이상하다"는 게 계속 나왔습니다. 캘린더에 점으로만 표시되던 게 이름 텍스트로 바뀌었고, 휴일 시스템 전체를 개편했습니다.

큰 변경을 할 때는 배포 전에 꼭 확인합니다:

npm run build   # 빌드 오류 없는지 먼저 확인
vercel --prod   # 문제없으면 배포

3월 29일: "있으면 좋겠다"

9e066bc  엑셀 다운로드 버튼
f581e91  잔여 휴일 표시
c9c6519  공휴일 있는 주 휴일 신청 불가 개선
92053e8  신청페이지 날짜 캘린더에 휴일 표시

직접 쓰면서 느낀 불편함들을 하나씩 추가했습니다. "엑셀로 뽑을 수 있으면 좋겠다", "잔여 휴일을 바로 보여주면 좋겠다" 같은 것들이요.

이런 개선이 계속 쌓이면서 프로그램이 점점 쓸 만해집니다.

실전에서 배운 것들

배포 전에 반드시: npm run build

로컬에서는 멀쩡히 작동하다가 Vercel 배포에서 실패한 적이 있었습니다.

error TS2451: Cannot redeclare block-scoped variable 'weekStart'.

dayoff/request/route.ts 파일에서 weekStart라는 변수를 두 군데서 선언했던 겁니다. 개발 모드(npm run dev)에서는 경고만 나오고 넘어가지만, 빌드할 때는 에러로 걸립니다.

vercel --prod 하기 전에 먼저:

npm run build

이걸 실행해서 ✓ Compiled successfully가 나오면 안심하고 배포하세요.

커밋 메시지는 미래의 나에게 쓰는 메모

# 이러면 나중에 아무것도 모릅니다
git commit -m "수정"
git commit -m "ㅇㅇ"
git commit -m "작업중"

# 이렇게 쓰면 3개월 뒤에도 무슨 작업이었는지 알 수 있습니다
git commit -m "fix: 토요일 공휴일은 빨간색 우선 표시"
git commit -m "feat: 회원가입 시 관리자 승인 필요하도록 변경"

관례적으로 앞에 feat: (새 기능), fix: (버그 수정), refactor: (코드 정리) 를 붙입니다. 한눈에 "이게 버그 수정이구나"를 알 수 있어서 편합니다.

자주 커밋하고, 자주 배포하세요

처음엔 "다 완성되면 한꺼번에 올리자"는 생각이 듭니다. 하지 마세요.

# 이렇게 하면 나중에 뭐가 문제인지 못 찾습니다
기능 3개 + 버그 수정 + 디자인 변경 → 한꺼번에 커밋 → 배포

# 이렇게 해야 합니다
기능 A 추가 → 커밋 → 배포
버그 발견 → 수정 → 커밋 → 배포
기능 B 추가 → 커밋 → 배포

Vercel 배포는 30~60초면 됩니다. 하루에 10번 배포해도 전혀 문제없어요.

전체 명령어 치트시트

처음 한 번만 하는 것들

# Git 초기화
git init

# GitHub 저장소 연결
git remote add origin https://github.com/사용자명/프로젝트명.git

# Vercel CLI 설치
npm install -g vercel

# Vercel 프로젝트 연결
vercel link

# 환경 변수 설정
vercel env add AIRTABLE_API_KEY production
vercel env add AIRTABLE_BASE_ID production
vercel env add NEXTAUTH_SECRET production

매번 하는 것들

# 1. 빌드 오류 없는지 먼저 확인
npm run build

# 2. 변경된 파일 모두 스테이징
git add .

# 3. 커밋 (뭘 바꿨는지 명확하게)
git commit -m "feat: 새 기능 설명"

# 4. GitHub에 올리기
git push

# 5. Vercel에 배포
vercel --prod

뭔가 잘못됐을 때

마지막으로

이 프로젝트는 3월 26일 첫 줄부터 3월 29일까지 딱 4일 동안 커밋 40개 이상을 남기며 만들어졌습니다.

처음엔 버그투성이였고, 잘못된 설계로 만든 것도 있었습니다. 그때마다 고치고, 커밋하고, 배포했습니다. 그게 쌓여서 지금의 프로그램이 됐습니다.

개발은 한 번에 완성되지 않습니다. 조금 만들고, 올리고, 확인하고, 고치는 작은 사이클을 빠르게 반복하는 게 전부입니다.