Deploy Error Analysis and Solution

📋 문서 정보

• 작성일: 2026-01-28
• 에러 발생 시점: GitHub Actions deploy.yml 워크플로우 실행 중
• 에러 위치: deploy job의 Pre-deployment Validation 단계
• 에러 코드: Exit Code 1

---

🔍 1. 에러 현상 분석

1.1 에러 메시지

##[error]KV namespace ID is still a placeholder in wrangler.jsonc
Please set the KV namespace ID before deploying:
  npx wrangler kv namespace create DOMAIN_KV --env staging
##[error]Process completed with exit code 1.

1.2 에러 발생 위치

• 파일: .github/scripts/steps/deploy.sh
• 함수: validate_cloudflare_config() (.github/scripts/lib/validation.sh)
• 검증 로직: grep -q '"id": "staging_kv_namespace_id"' wrangler.jsonc

1.3 현재 wrangler.jsonc 상태

"env": {
  "staging": {
    "kv_namespaces": [
      {
        "binding": "DOMAIN_KV",
        "id": "staging_kv_namespace_id",  // ← Placeholder 값이 남아있음
        "preview_id": "staging_kv_preview_id"
      }
    ]
  }
}

---

🎯 2. 근본 원인 분석

2.1 GitHub Actions Job 간 데이터 격리 문제

핵심 문제: GitHub Actions의 각 job은 독립적인 runner에서 실행되며, 로컬 파일시스템이 공유되지 않음

현재 워크플로우 구조

┌─────────────────┐
│  validate job   │  ← wrangler.jsonc 체크아웃
└────────┬────────┘
         │
┌────────▼────────┐
│ provision job   │  ← KV namespace 생성
│                 │  ← wrangler.jsonc 업데이트 (로컬 파일시스템)
└────────┬────────┘
         │
┌────────▼────────┐
│  deploy job     │  ← 새로운 runner에서 checkout
│                 │  ← wrangler.jsonc는 원본 상태 (placeholder 포함)
└─────────────────┘

문제점 상세

1. provision job에서:

   • KV namespace 생성 성공
   • update_wrangler_config() 함수로 wrangler.jsonc 업데이트
   • 하지만 이 변경사항은 provision job의 로컬 파일시스템에만 존재

2. deploy job에서:

   • 새로운 runner에서 actions/checkout@v4 실행
   • GitHub 저장소의 원본 wrangler.jsonc를 체크아웃 (placeholder 포함)
   • validate_cloudflare_config() 실행 시 placeholder 감지 → 실패

2.2 워크플로우 의존성 분석

deploy:
  needs: [validate, provision]  # ✅ 의존성은 설정되어 있음

• 의존성 설정은 정상: deploy job은 provision job 완료 후 실행
• 하지만 데이터 전달 메커니즘 부재: Job 간 파일 변경사항이 전달되지 않음

2.3 provision-resources.sh 동작 확인

파일: .github/scripts/steps/provision-resources.sh

# Step 2: Update wrangler.jsonc
if [[ -n "$KV_ID" ]]; then
  echo "📝 Updating wrangler.jsonc..." >&2
  update_wrangler_config "$ENV" "$D1_ID" "$KV_ID"  # ← 로컬 파일만 업데이트
fi

• ✅ KV namespace 생성 성공
• ✅ wrangler.jsonc 업데이트 성공 (로컬)
• ❌ 변경사항이 deploy job으로 전달되지 않음

---

💡 3. 해결방안

3.1 해결방안 비교

방안	장점	단점	우선순위
방안 1: Artifact 전달	간단, 명확	Artifact 업로드/다운로드 오버헤드	⭐⭐⭐
방안 2: Job Output 활용	가벼움, 빠름	wrangler.jsonc 재구성 필요	⭐⭐⭐⭐
방안 3: Git Commit	영구적 기록	자동화 복잡도 증가, 보안 이슈	⭐⭐
방안 4: 동적 검증 제거	즉시 해결	근본 원인 미해결	⭐

3.2 권장 해결방안: Artifact 전달 방식

3.2.1 개요

provision job에서 업데이트된 wrangler.jsonc를 artifact로 저장하고, deploy job에서 다운로드하여 사용

3.2.2 구현 단계

Step 1: provision job에 artifact 업로드 추가

.github/workflows/deploy.yml

provision:
  steps:
    # ... 기존 steps ...

    - name: Upload updated wrangler.jsonc
      if: success()
      uses: actions/upload-artifact@v4
      with:
        name: wrangler-config-${{ steps.env.outputs.environment }}
        path: wrangler.jsonc
        retention-days: 1

Step 2: deploy job에 artifact 다운로드 추가

.github/workflows/deploy.yml

deploy:
  steps:
    - name: Checkout repository
      uses: actions/checkout@v4

    - name: Download updated wrangler.jsonc
      uses: actions/download-artifact@v4
      with:
        name: wrangler-config-${{ steps.env.outputs.environment }}
        path: .
        merge-multiple: false  # 덮어쓰기 모드

    - name: Setup Project
      uses: ./.github/actions/setup-project

    # ... 나머지 steps ...

3.2.3 장점

• ✅ 명확한 데이터 흐름: Artifact를 통한 명시적 전달
• ✅ 검증 가능: 다운로드 후 파일 내용 확인 가능
• ✅ 디버깅 용이: Artifact 저장으로 문제 추적 가능
• ✅ 기존 로직 유지: validate_cloudflare_config() 함수 수정 불필요

3.2.4 주의사항

• Artifact 업로드/다운로드 시간 추가 (보통 1-3초)
• Artifact 저장 공간 사용 (최소한의 파일이므로 문제 없음)

---

3.3 대안: Job Output + 동적 업데이트

3.3.1 개요

provision job에서 리소스 ID를 job output으로 전달하고, deploy job에서 wrangler.jsonc를 동적으로 업데이트

3.3.2 구현 단계

Step 1: provision job에서 output 설정

provision:
  outputs:
    kv_namespace_id: ${{ steps.provision.outputs.kv_id }}
    d1_database_id: ${{ steps.provision.outputs.d1_id }}

  steps:
    - name: Provision Cloudflare Resources
      id: provision
      run: |
        # ... provisioning logic ...
        echo "kv_id=$KV_ID" >> $GITHUB_OUTPUT
        echo "d1_id=$D1_ID" >> $GITHUB_OUTPUT

Step 2: deploy job에서 동적 업데이트

deploy:
  needs: [validate, provision]

  steps:
    - name: Checkout repository
      uses: actions/checkout@v4

    - name: Update wrangler.jsonc with provisioned IDs
      run: |
        chmod +x .github/scripts/lib/wrangler-config.sh
        source .github/scripts/lib/wrangler-config.sh
        update_wrangler_config \
          "${{ steps.env.outputs.environment }}" \
          "${{ needs.provision.outputs.d1_database_id }}" \
          "${{ needs.provision.outputs.kv_namespace_id }}"

3.3.3 장점

• ✅ 빠른 실행: Artifact 업로드/다운로드 불필요
• ✅ 명시적 의존성: Job output을 통한 명확한 데이터 전달

3.3.4 단점

• ⚠️ 복잡도 증가: deploy job에 추가 단계 필요
• ⚠️ 검증 타이밍: validate_cloudflare_config() 실행 전에 업데이트 필요

---

🔧 4. 구현 계획

4.1 단계별 작업 계획

Phase 1: 즉시 해결 (권장 방안 1)

1. deploy.yml 수정

   • provision job에 artifact 업로드 step 추가
   • deploy job에 artifact 다운로드 step 추가

2. 검증

   • 로컬에서 워크플로우 시뮬레이션
   • GitHub Actions에서 실제 실행 테스트

3. 문서화

   • 변경사항 README 업데이트
   • 트러블슈팅 가이드 추가

Phase 2: 장기 개선 (선택적)

1. Job Output 방식으로 전환 검토

   • 성능 측정 및 비교
   • 필요시 마이그레이션

2. 자동화 강화

   • Provision 실패 시 자동 재시도
   • 리소스 ID 검증 로직 강화

---

📊 5. 예상 효과

5.1 문제 해결

• ✅ deploy job에서 placeholder 에러 제거
• ✅ 워크플로우 정상 완료 가능
• ✅ 배포 파이프라인 안정화

5.2 부수 효과

• ✅ 명확한 데이터 흐름: Job 간 데이터 전달이 명시적으로 추적 가능
• ✅ 디버깅 개선: Artifact 저장으로 문제 발생 시 원인 분석 용이
• ✅ 재현성 향상: 동일한 설정 파일로 재실행 가능

---

⚠️ 6. 주의사항 및 제약사항

6.1 주의사항

1. Artifact 보존 기간

   • retention-days: 1로 설정하여 불필요한 저장 공간 사용 방지
   • 필요시 조정 가능

2. 병렬 실행 시나리오

   • 여러 환경(staging, production) 동시 배포 시 artifact 이름 충돌 방지
   • 환경별 고유 이름 사용 (이미 구현됨: wrangler-config-${{ environment }})

3. 실패 시나리오

   • provision job 실패 시 artifact가 생성되지 않음
   • deploy job의 if: success() 조건으로 자동 스킵 (의도된 동작)

6.2 제약사항

• GitHub Actions artifact 저장 공간 제한 (현재 사용량 낮음, 문제 없음)
• Artifact 업로드/다운로드 시간 추가 (1-3초, 전체 워크플로우 시간에 미미한 영향)

---

📝 7. 검증 방법

7.1 로컬 검증

# 1. provision 시뮬레이션
export DEPLOY_ENV=staging
./.github/scripts/steps/provision-resources.sh

# 2. wrangler.jsonc 확인
grep -A 2 "staging" wrangler.jsonc | grep "id"

# 3. placeholder가 실제 ID로 변경되었는지 확인
# 예상: "id": "a1b2c3d4e5f6..." (32자 hex)

7.2 GitHub Actions 검증

1. 워크플로우 실행

   • main 브랜치에 push하여 자동 트리거
   • 또는 workflow_dispatch로 수동 실행

2. 로그 확인

   • provision job: “Upload updated wrangler.jsonc” step 성공 확인
   • deploy job: “Download updated wrangler.jsonc” step 성공 확인
   • deploy job: “Pre-deployment Checks” 단계에서 에러 없음 확인

3. Artifact 확인

   • GitHub Actions UI에서 artifact 다운로드
   • wrangler.jsonc 내용 확인 (placeholder가 실제 ID로 변경되었는지)

---

🎯 8. 결론

8.1 핵심 문제

GitHub Actions의 job 간 파일시스템 격리로 인해, provision job에서 업데이트한 wrangler.jsonc가 deploy job에 전달되지 않음

8.2 해결책

Artifact를 통한 명시적 데이터 전달 방식 채택

• provision job: 업데이트된 wrangler.jsonc를 artifact로 업로드
• deploy job: artifact를 다운로드하여 사용

8.3 기대 효과

• ✅ 즉시 문제 해결
• ✅ 워크플로우 안정화
• ✅ 향후 유지보수성 향상

---

📚 참고 자료

• GitHub Actions Artifacts 문서
• GitHub Actions Job Dependencies
• .github/workflows/deploy.yml
• .github/scripts/steps/provision-resources.sh
• .github/scripts/lib/wrangler-config.sh
• .github/scripts/lib/validation.sh

---

문서 버전: 1.0
최종 수정일: 2026-01-28