ci(k-skill-proxy): replace local pm2+cloudflared with Cloud Run auto-deploy via GitHub Actions

main에 머지되면 GitHub Actions가 자동으로 Workload Identity Federation으로 GCP 인증 후 Artifact Registry에 컨테이너 이미지를 빌드/푸시하고 Cloud Run(asia-northeast1) 서비스 k-skill-proxy를 재배포한다. 시크릿은 GCP Secret Manager에서 런타임에 주입된다. - add .github/workflows/deploy-k-skill-proxy.yml (WIF, on push to main) - add packages/k-skill-proxy/Dockerfile (multi-stage node:20-alpine, port bridge) - add docs/deploy-k-skill-proxy.md (1회성 GCP 셋업 + 운영 점검 절차) - remove ecosystem.config.cjs (PM2 root config) - remove scripts/run-k-skill-proxy.sh (local secrets.env source + node launcher) - remove wrangler devDependency (unused Cloudflare Workers CLI) - update AGENTS.md, CLAUDE.md, CONTRIBUTING.md, docs/features/k-skill-proxy.md, packages/k-skill-proxy/README.md to describe the new Cloud Run + GHA flow - clean dead k-skill-proxy-cloudrun entries from .gitignore
2026-06-24 02:04:11 +00:00 · 2026-05-21 13:45:06 +09:00 · 2026-05-21 13:45:06 +09:00 · 80e7805681
commit 80e7805681
parent 2f68b1ab4b
11 changed files with 464 additions and 40 deletions
--- a/.dockerignore
+++ b/.dockerignore
@ -0,0 +1,38 @@
+.git
+.github
+.gitignore
+.DS_Store
+.omx
+.sisyphus
+.venv
+.env
+.env.*
+*.dec
+*.plaintext
+__pycache__
+**/__pycache__
+**/node_modules
+**/dist
+**/.next
+**/.cache
+docs
+tests
+test
+**/test
+**/tests
+**/*.test.js
+**/*.test.py
+**/*.spec.js
+scripts/build-manus-bundle.js
+*.md
+LICENSE
+CONTRIBUTING.md
+CHANGELOG.md
+**/CHANGELOG.md
+**/README.md
+**/*.test.js
+.changeset
+.claude
+.agents
+.cursor
+.kiro
--- a/.github/workflows/deploy-k-skill-proxy.yml
+++ b/.github/workflows/deploy-k-skill-proxy.yml
@ -0,0 +1,147 @@
+name: Deploy k-skill-proxy to Cloud Run
+
+# Live: https://k-skill-proxy.nomadamas.org
+# GCP project: k-skill-proxy, region: asia-northeast1
+# Auth: Workload Identity Federation. Setup: docs/deploy-k-skill-proxy.md
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch: {}
+
+permissions:
+  contents: read
+  id-token: write
+
+concurrency:
+  group: deploy-k-skill-proxy
+  cancel-in-progress: false
+
+env:
+  GCP_PROJECT_ID: k-skill-proxy
+  GCP_REGION: asia-northeast1
+  AR_REPO: k-skill
+  SERVICE_NAME: k-skill-proxy
+  IMAGE_NAME: k-skill-proxy
+
+jobs:
+  deploy:
+    name: Build and deploy
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Authenticate to Google Cloud (Workload Identity Federation)
+        id: auth
+        uses: google-github-actions/auth@v3
+        with:
+          project_id: ${{ env.GCP_PROJECT_ID }}
+          workload_identity_provider: ${{ secrets.GCP_WIF_PROVIDER }}
+          service_account: ${{ secrets.GCP_DEPLOY_SERVICE_ACCOUNT }}
+          token_format: access_token
+
+      - name: Set up gcloud CLI
+        uses: google-github-actions/setup-gcloud@v2
+        with:
+          project_id: ${{ env.GCP_PROJECT_ID }}
+
+      - name: Configure Docker for Artifact Registry
+        run: gcloud auth configure-docker ${{ env.GCP_REGION }}-docker.pkg.dev --quiet
+
+      - name: Resolve image URI
+        id: image
+        run: |
+          IMAGE_URI="${GCP_REGION}-docker.pkg.dev/${GCP_PROJECT_ID}/${AR_REPO}/${IMAGE_NAME}:${GITHUB_SHA}"
+          echo "uri=${IMAGE_URI}" >> "$GITHUB_OUTPUT"
+          echo "Image: ${IMAGE_URI}"
+
+      - name: Build container image
+        run: |
+          docker build \
+            --tag "${{ steps.image.outputs.uri }}" \
+            --file packages/k-skill-proxy/Dockerfile \
+            .
+
+      - name: Push image to Artifact Registry
+        run: docker push "${{ steps.image.outputs.uri }}"
+
+      - name: Deploy to Cloud Run
+        id: deploy
+        uses: google-github-actions/deploy-cloudrun@v3
+        with:
+          service: ${{ env.SERVICE_NAME }}
+          region: ${{ env.GCP_REGION }}
+          image: ${{ steps.image.outputs.uri }}
+          secrets: |-
+            AIR_KOREA_OPEN_API_KEY=AIR_KOREA_OPEN_API_KEY:latest
+            KMA_OPEN_API_KEY=KMA_OPEN_API_KEY:latest
+            SEOUL_OPEN_API_KEY=SEOUL_OPEN_API_KEY:latest
+            HRFCO_OPEN_API_KEY=HRFCO_OPEN_API_KEY:latest
+            OPINET_API_KEY=OPINET_API_KEY:latest
+            BLUE_RIBBON_SESSION_ID=BLUE_RIBBON_SESSION_ID:latest
+            DATA_GO_KR_API_KEY=DATA_GO_KR_API_KEY:latest
+            KEDU_INFO_KEY=KEDU_INFO_KEY:latest
+            DATA4LIBRARY_AUTH_KEY=DATA4LIBRARY_AUTH_KEY:latest
+            FOODSAFETYKOREA_API_KEY=FOODSAFETYKOREA_API_KEY:latest
+            KAKAO_REST_API_KEY=KAKAO_REST_API_KEY:latest
+            KRX_API_KEY=KRX_API_KEY:latest
+            KOSIS_API_KEY=KOSIS_API_KEY:latest
+            NAVER_SEARCH_CLIENT_ID=NAVER_SEARCH_CLIENT_ID:latest
+            NAVER_SEARCH_CLIENT_SECRET=NAVER_SEARCH_CLIENT_SECRET:latest
+          env_vars: |-
+            KSKILL_PROXY_HOST=0.0.0.0
+            KSKILL_PROXY_NAME=k-skill-proxy
+            KSKILL_PROXY_CACHE_TTL_MS=300000
+            KSKILL_PROXY_RATE_LIMIT_WINDOW_MS=60000
+            KSKILL_PROXY_RATE_LIMIT_MAX=60
+          flags: >-
+            --platform=managed
+            --allow-unauthenticated
+            --cpu=1
+            --memory=512Mi
+            --min-instances=0
+            --max-instances=3
+            --concurrency=80
+            --timeout=60
+            --execution-environment=gen2
+            --cpu-boost
+
+      - name: Smoke test /health on the new revision
+        env:
+          SERVICE_URL: ${{ steps.deploy.outputs.url }}
+        run: |
+          set -euo pipefail
+          echo "Service URL: ${SERVICE_URL}"
+          for attempt in 1 2 3 4 5; do
+            if curl -fsS --max-time 15 "${SERVICE_URL}/health" >/tmp/health.json; then
+              break
+            fi
+            echo "Health probe attempt ${attempt} failed, retrying in 5s..."
+            sleep 5
+          done
+          python3 -c "
+          import json, sys
+          data = json.load(open('/tmp/health.json'))
+          if not data.get('ok'):
+              print('Health response is not ok:', data)
+              sys.exit(1)
+          missing = [k for k, v in data.get('upstreams', {}).items() if k.endswith('Configured') and v is not True]
+          if missing:
+              print('Upstreams not configured:', missing)
+              sys.exit(1)
+          print('Health OK. All upstreams configured.')
+          "
+
+      - name: Smoke test custom domain (k-skill-proxy.nomadamas.org)
+        run: |
+          set -euo pipefail
+          if curl -fsS --max-time 15 https://k-skill-proxy.nomadamas.org/health >/tmp/prod-health.json; then
+            python3 -c "
+          import json
+          data = json.load(open('/tmp/prod-health.json'))
+          print('Prod /health ok:', data.get('ok'))
+          "
+          else
+            echo "::warning::Custom domain /health probe failed; revision may need traffic split or DNS warm-up."
+          fi
--- a/.gitignore
+++ b/.gitignore
@ -9,3 +9,5 @@ node_modules/
 __pycache__/
 dist/
 .sisyphus/
+
+.agents/
--- a/AGENTS.md
+++ b/AGENTS.md
@ -47,10 +47,11 @@ These rules are repo-specific and apply to everything under this directory.
 ## Proxy server development

 - 개발 repo (`dev` 브랜치)에서 proxy 코드를 수정하고, main에 merge하면 프로덕션에 반영된다.
- 프로덕션 배포본은 `~/.local/share/k-skill-proxy`에 main 브랜치 단독 clone으로 존재한다.
- cron job (`0 * * * *`)이 매시 정각에 `~/.local/share/k-skill-proxy/scripts/auto-update-proxy.sh`를 실행해 origin/main fetch → fast-forward pull → package-lock 변경 시 npm ci → pm2 restart 순서로 자동 배포한다.
- 로그: `/tmp/k-skill-proxy-update.log`
+- 프로덕션 배포 대상은 **Google Cloud Run** (`asia-northeast1`, GCP project `k-skill-proxy`)이며, 커스텀 도메인 `k-skill-proxy.nomadamas.org`로 노출된다.
+- `main` 브랜치에 merge되면 `.github/workflows/deploy-k-skill-proxy.yml`이 Workload Identity Federation으로 GCP 인증 → Artifact Registry로 image build/push → Cloud Run 재배포 → `/health` smoke test까지 자동으로 수행한다.
+- 따라서 **dev에서 route를 추가/수정한 뒤 main에 merge되기 전까지는 프로덕션 proxy에 반영되지 않는다.**
 - proxy 서버 코드: `packages/k-skill-proxy/src/server.js`
+- 컨테이너 이미지 빌드 정의: `packages/k-skill-proxy/Dockerfile`
 - proxy 서버 테스트: `packages/k-skill-proxy/test/server.test.js`
- proxy 환경변수(API key 등)는 `~/.config/k-skill/secrets.env`에 넣고, `scripts/run-k-skill-proxy.sh`가 source한다.
- **dev에서 route를 추가/수정한 뒤 main에 merge되기 전까지는 프로덕션 proxy에 반영되지 않는다.** 로컬 테스트는 `node packages/k-skill-proxy/src/server.js`로 직접 실행한다.
+- 로컬 테스트: `node packages/k-skill-proxy/src/server.js` (환경변수는 `~/.config/k-skill/secrets.env` 등에서 직접 export해서 띄운다)
+- 프로덕션 시크릿은 GCP Secret Manager에 보관되고 Cloud Run runtime에 주입된다. WIF / Secret Manager 1회 셋업과 운영 점검 절차는 [`docs/deploy-k-skill-proxy.md`](docs/deploy-k-skill-proxy.md) 참고.
--- a/CLAUDE.md
+++ b/CLAUDE.md
@ -14,9 +14,9 @@

 ## Proxy server development

- 개발 repo: `/Users/jeffrey/Projects/k-skill` (이 디렉토리, `dev` 브랜치)
- 프로덕션 배포본: `~/.local/share/k-skill-proxy` (main 브랜치 단독 clone)
- **cron job** 이 매시 정각에 `origin/main` fetch → fast-forward pull → pm2 restart 실행
+- 개발 repo: 이 디렉토리, `dev` 브랜치
+- 프로덕션 배포 대상: **Google Cloud Run** (project `k-skill-proxy`, region `asia-northeast1`, custom domain `k-skill-proxy.nomadamas.org`)
+- `main` 브랜치에 merge되면 `.github/workflows/deploy-k-skill-proxy.yml`이 자동으로 Cloud Run 재배포를 수행한다. 인증은 Workload Identity Federation, 이미지 빌드 정의는 `packages/k-skill-proxy/Dockerfile`, 시크릿은 GCP Secret Manager에서 주입된다. WIF/Secret Manager 셋업은 `docs/deploy-k-skill-proxy.md` 참고.
 - 따라서 proxy route 변경은 **main에 merge되어야 프로덕션에 반영**된다. dev에서 코드를 바꿔도 프로덕션 proxy에는 영향 없음.
 - 로컬 테스트는 `node packages/k-skill-proxy/src/server.js` 로 직접 실행하거나 `node --test packages/k-skill-proxy/test/server.test.js` 로 확인.
 - **Proxy 편입 규칙**: k-skill-proxy에 route를 추가하려면 upstream이 API 키를 필요로 해야 한다. 공개 엔드포인트(키 불필요)는 skill 코드에서 직접 호출하고 프록시를 거치지 않는다.
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@ -60,11 +60,11 @@

 - 프록시 서버 코드: `packages/k-skill-proxy/src/server.js`
 - 프록시 서버 테스트: `packages/k-skill-proxy/test/server.test.js`
- 로컬 테스트: `node packages/k-skill-proxy/src/server.js`
- 프록시 환경변수와 API key는 `~/.config/k-skill/secrets.env`에 두고, `scripts/run-k-skill-proxy.sh`가 source합니다.
- 프로덕션 프록시는 `~/.local/share/k-skill-proxy`에 있는 `main` 브랜치 단독 clone입니다.
- cron job은 매시 정각 `scripts/auto-update-proxy.sh`를 실행해 `origin/main` fetch → fast-forward pull → `package-lock` 변경 시 `npm ci` → `pm2 restart` 순서로 배포합니다.
- 배포 로그는 `/tmp/k-skill-proxy-update.log`에서 확인합니다.
+- 컨테이너 이미지 정의: `packages/k-skill-proxy/Dockerfile`
+- 로컬 테스트: 필요한 upstream 환경변수를 export한 상태에서 `node packages/k-skill-proxy/src/server.js`. 로컬에서 시크릿을 모아두는 표준 위치는 `~/.config/k-skill/secrets.env` 입니다.
+- 프로덕션 프록시는 **Google Cloud Run** (project `k-skill-proxy`, region `asia-northeast1`)에서 운영하며 `k-skill-proxy.nomadamas.org` 도메인에 매핑되어 있습니다.
+- `main` 브랜치에 머지되면 `.github/workflows/deploy-k-skill-proxy.yml` 워크플로가 Workload Identity Federation으로 GCP 인증 → Artifact Registry로 이미지 빌드/푸시 → Cloud Run 재배포 → `/health` smoke test까지 자동 수행합니다.
+- 프로덕션 시크릿은 GCP Secret Manager에 보관되고 Cloud Run 런타임에 주입됩니다. 프록시 운영자(maintainer)가 한 번 수행해야 하는 WIF/Secret Manager 셋업과 운영 점검 절차는 [`docs/deploy-k-skill-proxy.md`](docs/deploy-k-skill-proxy.md)에 정리되어 있습니다.
 - `dev`에서 route를 추가하거나 수정해도 `main`에 머지되기 전까지는 프로덕션 프록시에 반영되지 않습니다.

 ## 검증
--- a/docs/deploy-k-skill-proxy.md
+++ b/docs/deploy-k-skill-proxy.md
@ -0,0 +1,211 @@
+# k-skill-proxy 배포 가이드 (Cloud Run + GitHub Actions)
+
+`k-skill-proxy`는 Google Cloud Run에서 운영되고, `main` 브랜치에 머지되면 GitHub Actions가 자동으로 재배포합니다.
+
+이 문서는 그 자동 배포 파이프라인의 **1회성 셋업 절차**와 **운영 점검 절차**를 정리합니다. 일반 contributor는 읽지 않아도 되며, 프록시 운영을 담당하는 maintainer(현재 `jeffrey@markr.ai`)가 인프라를 처음 만들거나 수리할 때 참고합니다.
+
+## 운영 사실
+
+| 항목 | 값 |
+| --- | --- |
+| GCP project ID | `k-skill-proxy` |
+| Region | `asia-northeast1` (도쿄) |
+| Cloud Run service | `k-skill-proxy` |
+| Artifact Registry repo | `asia-northeast1-docker.pkg.dev/k-skill-proxy/k-skill` |
+| 공개 도메인 | `https://k-skill-proxy.nomadamas.org` (Cloud Run domain mapping) |
+| 컨테이너 이미지 정의 | `packages/k-skill-proxy/Dockerfile` |
+| 워크플로 | `.github/workflows/deploy-k-skill-proxy.yml` |
+| 인증 | Workload Identity Federation (long-lived JSON key 없음) |
+| 시크릿 저장소 | GCP Secret Manager (이름 = 환경변수 이름) |
+
+## 배포 흐름
+
+1. `dev` 브랜치에서 작업, PR을 `dev`에 보낸다.
+2. `dev` → `main` 머지 PR이 `@vkehfdl1`에 의해 머지된다.
+3. `main` push가 `.github/workflows/deploy-k-skill-proxy.yml`을 트리거한다.
+4. 워크플로가:
+   - WIF로 `${GCP_DEPLOY_SERVICE_ACCOUNT}`로 impersonate
+   - `packages/k-skill-proxy/Dockerfile`로 컨테이너 빌드
+   - Artifact Registry에 `:${GITHUB_SHA}` 태그로 push
+   - Cloud Run `k-skill-proxy` 서비스를 새 이미지로 재배포 (Secret Manager 시크릿 + 런타임 env 주입)
+   - 새 revision의 `*.run.app` URL과 `https://k-skill-proxy.nomadamas.org/health`에 smoke test
+5. 실패 시 GitHub Actions 페이지에서 로그 확인. Cloud Run 자체는 마지막 healthy revision에 트래픽을 유지한다.
+
+## 1회성 GCP 셋업
+
+> 이미 한 번 셋업되어 있다면 다시 실행할 필요 없음. 새 maintainer가 인계받거나 SA를 새로 만들 때만 사용.
+
+```bash
+export PROJECT_ID="k-skill-proxy"
+export PROJECT_NUMBER="$(gcloud projects describe "$PROJECT_ID" --format='value(projectNumber)')"
+export GH_REPO="NomaDamas/k-skill"          # owner/repo
+export POOL_ID="github-actions-pool"
+export PROVIDER_ID="github-actions-provider"
+export DEPLOY_SA="k-skill-proxy-deploy"
+export DEPLOY_SA_EMAIL="${DEPLOY_SA}@${PROJECT_ID}.iam.gserviceaccount.com"
+```
+
+### 1) 필요한 API 활성화
+
+```bash
+gcloud services enable \
+  iamcredentials.googleapis.com \
+  run.googleapis.com \
+  artifactregistry.googleapis.com \
+  secretmanager.googleapis.com \
+  --project="$PROJECT_ID"
+```
+
+### 2) Workload Identity Pool + GitHub OIDC provider
+
+```bash
+gcloud iam workload-identity-pools create "$POOL_ID" \
+  --project="$PROJECT_ID" \
+  --location=global \
+  --display-name="GitHub Actions"
+
+gcloud iam workload-identity-pools providers create-oidc "$PROVIDER_ID" \
+  --project="$PROJECT_ID" \
+  --location=global \
+  --workload-identity-pool="$POOL_ID" \
+  --display-name="GitHub OIDC" \
+  --issuer-uri="https://token.actions.githubusercontent.com" \
+  --attribute-mapping="google.subject=assertion.sub,attribute.repository=assertion.repository,attribute.repository_owner=assertion.repository_owner" \
+  --attribute-condition="assertion.repository == '${GH_REPO}'"
+```
+
+> `attribute-condition`은 토큰 발급 단계에서 우리 저장소만 허용해 풀 자체를 좁힙니다. 임의의 다른 repo가 같은 풀을 통해 SA를 impersonate하지 못하게 막는 핵심 가드입니다.
+
+### 3) Deploy service account 생성
+
+```bash
+gcloud iam service-accounts create "$DEPLOY_SA" \
+  --project="$PROJECT_ID" \
+  --display-name="GitHub Actions k-skill-proxy deployer"
+```
+
+### 4) 풀 → service account impersonation 허용
+
+```bash
+gcloud iam service-accounts add-iam-policy-binding "$DEPLOY_SA_EMAIL" \
+  --project="$PROJECT_ID" \
+  --role=roles/iam.workloadIdentityUser \
+  --member="principalSet://iam.googleapis.com/projects/${PROJECT_NUMBER}/locations/global/workloadIdentityPools/${POOL_ID}/attribute.repository/${GH_REPO}"
+```
+
+### 5) deploy SA에 필요한 권한 부여
+
+```bash
+gcloud projects add-iam-policy-binding "$PROJECT_ID" \
+  --member="serviceAccount:${DEPLOY_SA_EMAIL}" \
+  --role=roles/run.admin
+
+gcloud projects add-iam-policy-binding "$PROJECT_ID" \
+  --member="serviceAccount:${DEPLOY_SA_EMAIL}" \
+  --role=roles/artifactregistry.writer
+
+gcloud projects add-iam-policy-binding "$PROJECT_ID" \
+  --member="serviceAccount:${DEPLOY_SA_EMAIL}" \
+  --role=roles/iam.serviceAccountUser
+```
+
+`iam.serviceAccountUser`는 Cloud Run의 런타임 service account(`${PROJECT_NUMBER}-compute@developer.gserviceaccount.com`)를 deploy SA가 대신 지정할 수 있게 하기 위함입니다.
+
+### 6) Cloud Run 런타임 SA에 Secret Manager accessor 부여
+
+```bash
+RUNTIME_SA="${PROJECT_NUMBER}-compute@developer.gserviceaccount.com"
+for s in \
+  AIR_KOREA_OPEN_API_KEY KMA_OPEN_API_KEY SEOUL_OPEN_API_KEY HRFCO_OPEN_API_KEY \
+  OPINET_API_KEY BLUE_RIBBON_SESSION_ID DATA_GO_KR_API_KEY KEDU_INFO_KEY \
+  DATA4LIBRARY_AUTH_KEY FOODSAFETYKOREA_API_KEY KAKAO_REST_API_KEY KRX_API_KEY \
+  KOSIS_API_KEY NAVER_SEARCH_CLIENT_ID NAVER_SEARCH_CLIENT_SECRET; do
+  gcloud secrets add-iam-policy-binding "$s" \
+    --project="$PROJECT_ID" \
+    --member="serviceAccount:${RUNTIME_SA}" \
+    --role=roles/secretmanager.secretAccessor \
+    --condition=None >/dev/null
+done
+```
+
+### 7) WIF provider 리소스 이름 확인
+
+```bash
+gcloud iam workload-identity-pools providers describe "$PROVIDER_ID" \
+  --project="$PROJECT_ID" \
+  --location=global \
+  --workload-identity-pool="$POOL_ID" \
+  --format='value(name)'
+# 예: projects/123456789/locations/global/workloadIdentityPools/github-actions-pool/providers/github-actions-provider
+```
+
+이 값과 `${DEPLOY_SA_EMAIL}`을 GitHub에 등록합니다.
+
+## GitHub repository secrets
+
+다음 두 개의 **secret**을 `Settings → Secrets and variables → Actions → Repository secrets`에 등록합니다.
+
+| Name | Value |
+| --- | --- |
+| `GCP_WIF_PROVIDER` | 위 7번에서 얻은 provider 리소스 전체 이름 |
+| `GCP_DEPLOY_SERVICE_ACCOUNT` | `k-skill-proxy-deploy@k-skill-proxy.iam.gserviceaccount.com` |
+
+> 값 자체가 민감하진 않지만, 외부에 노출되면 reconnaissance에 도움이 될 수 있으므로 secret으로 둡니다. variable로 옮겨도 동작은 동일합니다.
+
+## Secret Manager에 upstream key 업로드
+
+```bash
+KEYS=(
+  AIR_KOREA_OPEN_API_KEY KMA_OPEN_API_KEY SEOUL_OPEN_API_KEY HRFCO_OPEN_API_KEY
+  OPINET_API_KEY BLUE_RIBBON_SESSION_ID DATA_GO_KR_API_KEY KEDU_INFO_KEY
+  DATA4LIBRARY_AUTH_KEY FOODSAFETYKOREA_API_KEY KAKAO_REST_API_KEY KRX_API_KEY
+  KOSIS_API_KEY NAVER_SEARCH_CLIENT_ID NAVER_SEARCH_CLIENT_SECRET
+)
+
+set -a; source ~/.config/k-skill/secrets.env; set +a
+
+for k in "${KEYS[@]}"; do
+  value="${!k:-}"
+  [[ -z "$value" ]] && { echo "skip $k (empty)"; continue; }
+  if gcloud secrets describe "$k" --project="$PROJECT_ID" >/dev/null 2>&1; then
+    printf '%s' "$value" | gcloud secrets versions add "$k" --data-file=- --project="$PROJECT_ID"
+  else
+    printf '%s' "$value" | gcloud secrets create "$k" --data-file=- --replication-policy=automatic --project="$PROJECT_ID"
+  fi
+done
+```
+
+키 값을 회전(rotate)할 때도 같은 명령을 다시 실행하면 새 version이 추가됩니다. Cloud Run은 `:latest`로 바인딩되어 있어 다음 배포부터 자동 반영됩니다(즉시 적용이 필요하면 새 revision을 한 번 더 deploy).
+
+## 운영 점검 절차
+
+- 자동 배포 상태: GitHub `Actions` 탭의 "Deploy k-skill-proxy to Cloud Run" 워크플로
+- 라이브 헬스체크: `curl -fsS https://k-skill-proxy.nomadamas.org/health`
+- Cloud Run revision/로그: GCP Console → Cloud Run → `k-skill-proxy` (`asia-northeast1`)
+- 이미지 태그: `asia-northeast1-docker.pkg.dev/k-skill-proxy/k-skill/k-skill-proxy:<commit-sha>`
+- 트래픽 롤백: 이전 revision으로 traffic split을 100% 되돌리거나, 직전 commit을 revert해서 main에 머지 → 워크플로가 다시 돈다.
+
+## 로컬에서 동일한 배포를 수동으로 돌리고 싶을 때
+
+`gcloud auth login`으로 maintainer 계정에 로그인된 상태에서:
+
+```bash
+SHA="$(git rev-parse HEAD)"
+IMAGE_URI="asia-northeast1-docker.pkg.dev/k-skill-proxy/k-skill/k-skill-proxy:${SHA}"
+
+gcloud auth configure-docker asia-northeast1-docker.pkg.dev --quiet
+docker build -t "$IMAGE_URI" -f packages/k-skill-proxy/Dockerfile .
+docker push "$IMAGE_URI"
+
+gcloud run deploy k-skill-proxy \
+  --image="$IMAGE_URI" \
+  --region=asia-northeast1 \
+  --platform=managed \
+  --allow-unauthenticated \
+  --execution-environment=gen2 \
+  --cpu=1 --memory=512Mi --min-instances=0 --max-instances=3 \
+  --concurrency=80 --timeout=60 --cpu-boost \
+  --project=k-skill-proxy
+```
+
+이 명령은 평상시에는 필요 없습니다. GitHub Actions가 같은 일을 하기 때문입니다.
--- a/docs/features/k-skill-proxy.md
+++ b/docs/features/k-skill-proxy.md
@ -66,38 +66,32 @@ client/skill -> k-skill-proxy -> upstream public API

 ## 프로덕션 배포 구조

-프로덕션 proxy 서버는 개발 repo와 분리된 별도 clone으로 운영한다.
+프로덕션 proxy 서버는 **Google Cloud Run**에서 운영한다.

- 배포 디렉토리: `~/.local/share/k-skill-proxy` (main 브랜치 단독 clone)
- PM2 프로세스: `k-skill-proxy`
- Cloudflare Tunnel ingress: `k-skill-proxy.nomadamas.org -> http://localhost:4020`
+- GCP project: `k-skill-proxy`
+- Region: `asia-northeast1` (도쿄)
+- Cloud Run service: `k-skill-proxy`
+- 공개 도메인: `k-skill-proxy.nomadamas.org` (Cloud Run domain mapping)
+- 컨테이너 이미지 정의: `packages/k-skill-proxy/Dockerfile`
+- 시크릿(upstream API key): GCP Secret Manager에 보관, Cloud Run runtime에 주입

-### 자동 배포 (cron)
+### 자동 배포 (GitHub Actions)

-`~/.local/share/k-skill-proxy/scripts/auto-update-proxy.sh`가 매시 정각에 실행된다.
+`main` 브랜치에 push/merge되면 `.github/workflows/deploy-k-skill-proxy.yml` 워크플로가 실행되어 다음 순서로 동작한다.

-```
-0 * * * * PATH=/usr/bin:/opt/homebrew/bin:/opt/homebrew/lib/node_modules/.bin:$PATH ~/.local/share/k-skill-proxy/scripts/auto-update-proxy.sh >> /tmp/k-skill-proxy-update.log 2>&1
-```
-
-동작 순서:
-
-1. `git fetch origin main`
-2. local SHA == remote SHA 이면 종료 (up-to-date)
-3. `git pull --ff-only`
-4. `package-lock.json` 변경 시 `npm ci`
-5. `pm2 restart k-skill-proxy --update-env`
+1. Workload Identity Federation으로 GCP 인증
+2. `packages/k-skill-proxy/Dockerfile`로 이미지 빌드
+3. Artifact Registry (`asia-northeast1-docker.pkg.dev/k-skill-proxy/k-skill/k-skill-proxy:<sha>`)에 push
+4. Cloud Run service `k-skill-proxy` 재배포 (Secret Manager 시크릿 + 런타임 환경변수 주입)
+5. 직접 Cloud Run URL과 `https://k-skill-proxy.nomadamas.org/health` smoke test

 따라서 **main에 merge되어야 프로덕션에 반영**된다. dev 브랜치 변경은 프로덕션에 영향 없음.

-로그: `/tmp/k-skill-proxy-update.log`
+배포 상태와 로그는 GitHub Actions의 "Deploy k-skill-proxy to Cloud Run" 워크플로 실행 페이지와 GCP Console의 Cloud Run revision/log에서 확인한다.

-### 초기 설정 (PM2 + cloudflared)
+### 초기 셋업 (운영자 1회 수행)

-1. `pm2 start ecosystem.config.cjs`
-2. `pm2 save`
-3. `pm2 startup` 출력대로 launchd 등록
-4. Cloudflare Tunnel ingress 에 `k-skill-proxy.nomadamas.org -> http://localhost:4020` 추가
+WIF pool/provider, deploy service account, Secret Manager 시크릿 생성 등 1회성 GCP 셋업 절차와 GitHub repository secrets/variables 등록 방법은 [`docs/deploy-k-skill-proxy.md`](../deploy-k-skill-proxy.md)에 정리되어 있다.

 ## 기본 공개 정책

--- a/package.json
+++ b/package.json
@ -10,7 +10,7 @@
  "scripts": {
    "build": "npm run build --workspaces --if-present",
    "build:manus-bundle": "node scripts/build-manus-bundle.js",
-  "lint": "node --check scripts/skill-docs.test.js scripts/korean_character_count.js scripts/test_korean_character_count.js scripts/build-manus-bundle.js scripts/test_build_manus_bundle.js && python3 -m py_compile scripts/k_skill_cleaner.py scripts/test_k_skill_cleaner.py corporate-registration-consulting/scripts/fill_official_hwp.py k-skill-cleaner/scripts/k_skill_cleaner.py scripts/fine_dust.py scripts/test_fine_dust.py scripts/ktx_booking.py scripts/test_ktx_booking.py scripts/sillok_search.py scripts/test_sillok_search.py scripts/korean_spell_check.py scripts/test_korean_spell_check.py scripts/patent_search.py scripts/test_patent_search.py scripts/mfds_drug_safety.py scripts/test_mfds_drug_safety.py scripts/nts_business_registration.py scripts/test_nts_business_registration.py scripts/mfds_food_safety.py scripts/test_mfds_food_safety.py scripts/zipcode_search.py scripts/test_zipcode_search.py scripts/subway_lost_property.py scripts/test_subway_lost_property.py scripts/geeknews_search.py scripts/test_geeknews_search.py nts-business-registration/scripts/nts_business_registration.py scripts/test_naver_blog_search.py scripts/test_korean_slang_writing.py scripts/kakaotalk_mac.py scripts/test_kakaotalk_mac.py scripts/test_coupang_partners_mcp_wrapper.py scripts/test_ohou_today_deal.py scripts/ticket_availability.py scripts/test_ticket_availability.py scripts/test_danawa_price_search.py ticket-availability/scripts/ticket_availability.py coupang-product-search/scripts/coupang_partners_mcp.py ohou-today-deal/scripts/ohou_today_deal.py kakaotalk-mac/scripts/kakaotalk_mac.py naver-blog-research/scripts/_naver_http.py naver-blog-research/scripts/naver_search.py naver-blog-research/scripts/naver_read.py naver-blog-research/scripts/naver_download_images.py korean-slang-writing/scripts/_slang_http.py korean-slang-writing/scripts/slang_search.py korean-slang-writing/scripts/slang_lookup.py korean-scholarship-search/scripts/scholarship_filter.py korean-scholarship-search/scripts/test_scholarship_filter.py korean-scholarship-search/scripts/university_search_plan.py danawa-price-search/scripts/danawa_search.py kosis-stats/scripts/run_kosis_stats.py kosis-stats/tests/test_run_kosis_stats.py kstartup-search/scripts/run_kstartup.py kstartup-search/tests/test_run_kstartup.py intercity-bus-booking/scripts/intercity_bus_search.py daangn-used-goods-search/scripts/daangn_used_goods.py daangn-realty-search/scripts/daangn_realty.py daangn-jobs-search/scripts/daangn_jobs.py daangn-cars-search/scripts/daangn_cars.py && npm run lint --workspaces --if-present && ./scripts/validate-skills.sh",
+    "lint": "node --check scripts/skill-docs.test.js scripts/korean_character_count.js scripts/test_korean_character_count.js scripts/build-manus-bundle.js scripts/test_build_manus_bundle.js && python3 -m py_compile scripts/k_skill_cleaner.py scripts/test_k_skill_cleaner.py corporate-registration-consulting/scripts/fill_official_hwp.py k-skill-cleaner/scripts/k_skill_cleaner.py scripts/fine_dust.py scripts/test_fine_dust.py scripts/ktx_booking.py scripts/test_ktx_booking.py scripts/sillok_search.py scripts/test_sillok_search.py scripts/korean_spell_check.py scripts/test_korean_spell_check.py scripts/patent_search.py scripts/test_patent_search.py scripts/mfds_drug_safety.py scripts/test_mfds_drug_safety.py scripts/nts_business_registration.py scripts/test_nts_business_registration.py scripts/mfds_food_safety.py scripts/test_mfds_food_safety.py scripts/zipcode_search.py scripts/test_zipcode_search.py scripts/subway_lost_property.py scripts/test_subway_lost_property.py scripts/geeknews_search.py scripts/test_geeknews_search.py nts-business-registration/scripts/nts_business_registration.py scripts/test_naver_blog_search.py scripts/test_korean_slang_writing.py scripts/kakaotalk_mac.py scripts/test_kakaotalk_mac.py scripts/test_coupang_partners_mcp_wrapper.py scripts/test_ohou_today_deal.py scripts/ticket_availability.py scripts/test_ticket_availability.py scripts/test_danawa_price_search.py ticket-availability/scripts/ticket_availability.py coupang-product-search/scripts/coupang_partners_mcp.py ohou-today-deal/scripts/ohou_today_deal.py kakaotalk-mac/scripts/kakaotalk_mac.py naver-blog-research/scripts/_naver_http.py naver-blog-research/scripts/naver_search.py naver-blog-research/scripts/naver_read.py naver-blog-research/scripts/naver_download_images.py korean-slang-writing/scripts/_slang_http.py korean-slang-writing/scripts/slang_search.py korean-slang-writing/scripts/slang_lookup.py korean-scholarship-search/scripts/scholarship_filter.py korean-scholarship-search/scripts/test_scholarship_filter.py korean-scholarship-search/scripts/university_search_plan.py danawa-price-search/scripts/danawa_search.py kosis-stats/scripts/run_kosis_stats.py kosis-stats/tests/test_run_kosis_stats.py kstartup-search/scripts/run_kstartup.py kstartup-search/tests/test_run_kstartup.py intercity-bus-booking/scripts/intercity_bus_search.py daangn-used-goods-search/scripts/daangn_used_goods.py daangn-realty-search/scripts/daangn_realty.py daangn-jobs-search/scripts/daangn_jobs.py daangn-cars-search/scripts/daangn_cars.py && npm run lint --workspaces --if-present && ./scripts/validate-skills.sh",
    "typecheck": "tsc --noEmit",
    "test": "python3 -m pip install --user --quiet beautifulsoup4 && node --test scripts/skill-docs.test.js scripts/test_korean_character_count.js scripts/test_build_manus_bundle.js && PYTHONPATH=.:scripts python3 -m unittest scripts.test_k_skill_cleaner scripts.test_fine_dust scripts.test_ktx_booking scripts.test_sillok_search scripts.test_korean_spell_check scripts.test_patent_search scripts.test_mfds_drug_safety scripts.test_nts_business_registration scripts.test_mfds_food_safety scripts.test_zipcode_search scripts.test_subway_lost_property scripts.test_geeknews_search scripts.test_naver_blog_search scripts.test_korean_slang_writing scripts.test_kakaotalk_mac scripts.test_coupang_partners_mcp_wrapper scripts.test_ohou_today_deal scripts.test_ticket_availability scripts.test_danawa_price_search && PYTHONPATH=.:scripts:korean-scholarship-search/scripts python3 -m unittest discover -s korean-scholarship-search/scripts -p 'test_scholarship_filter.py' && PYTHONPATH=.:scripts:kosis-stats/scripts python3 -m unittest discover -s kosis-stats/tests -p 'test_run_kosis_stats.py' && PYTHONPATH=.:scripts:kstartup-search/scripts python3 -m unittest discover -s kstartup-search/tests -p 'test_run_kstartup.py' && npm run test --workspaces --if-present && ./scripts/validate-skills.sh",
    "pack:dry-run": "npm pack --workspace k-lotto --dry-run && npm pack --workspace daiso-product-search --dry-run && npm pack --workspace market-kurly-search --dry-run && npm pack --workspace blue-ribbon-nearby --dry-run && npm pack --workspace kakao-bar-nearby --dry-run && npm pack --workspace cheap-gas-nearby --dry-run && npm pack --workspace public-restroom-nearby --dry-run && npm pack --workspace parking-lot-search --dry-run && npm pack --workspace court-auction-notice-search --dry-run && npm pack --workspace donation-place-search --dry-run && npm pack --workspace gongsijiga-search --dry-run && npm pack --workspace kbl-results --dry-run && npm pack --workspace kleague-results --dry-run && npm pack --workspace lck-analytics --dry-run && npm pack --workspace toss-securities --dry-run && npm pack --workspace hipass-receipt --dry-run && npm pack --workspace used-car-price-search --dry-run && npm pack --workspace k-skill-rhwp --dry-run && npm pack --workspace korean-marathon-schedule --dry-run && npm pack --workspace gangnamunni-clinic-search --dry-run && npm pack --workspace daishin-report-search --dry-run && npm pack --workspace sh-notice-search --dry-run && npm pack --workspace emergency-room-beds --dry-run && npm pack --workspace local-election-candidate-search --dry-run",
@ -19,8 +19,8 @@
    "release:npm": "changeset publish"
  },
  "devDependencies": {
-    "@types/node": "^22.14.1",
    "@changesets/cli": "^2.29.5",
+    "@types/node": "^22.14.1",
    "typescript": "^5.8.2"
  }
 }
--- a/packages/k-skill-proxy/Dockerfile
+++ b/packages/k-skill-proxy/Dockerfile
@ -0,0 +1,26 @@
+# Build context MUST be repo root.
+# packages/k-skill-proxy/src/parking-lots.js does:
+#   require("../../parking-lot-search/src/parse")
+# so this image keeps both packages under /workspace/packages/ to preserve
+# that relative require path. Do not flatten the layout.
+FROM node:20-alpine AS deps
+WORKDIR /app
+COPY packages/k-skill-proxy/package.json ./package.json
+RUN npm install --omit=dev --no-audit --no-fund \
+ && npm cache clean --force
+
+FROM node:20-alpine AS runtime
+WORKDIR /workspace
+ENV NODE_ENV=production \
+    KSKILL_PROXY_HOST=0.0.0.0 \
+    KSKILL_PROXY_PORT=8080
+COPY --from=deps /app/node_modules ./packages/k-skill-proxy/node_modules
+COPY --from=deps /app/package.json ./packages/k-skill-proxy/package.json
+COPY packages/k-skill-proxy/src ./packages/k-skill-proxy/src
+COPY packages/parking-lot-search/src ./packages/parking-lot-search/src
+COPY packages/parking-lot-search/package.json ./packages/parking-lot-search/package.json
+WORKDIR /workspace/packages/k-skill-proxy
+EXPOSE 8080
+USER node
+# Cloud Run injects PORT; the server reads KSKILL_PROXY_PORT. Forward it.
+CMD ["sh", "-c", "KSKILL_PROXY_PORT=${PORT:-8080} node src/server.js"]
--- a/packages/k-skill-proxy/README.md
+++ b/packages/k-skill-proxy/README.md
@ -262,6 +262,11 @@ curl -fsS --get 'http://127.0.0.1:4020/v1/kakao-local/geocode' \
 ```


-## PM2 실행
+## 프로덕션 배포

-루트의 `ecosystem.config.cjs` + `scripts/run-k-skill-proxy.sh` 조합을 사용하면 재부팅 이후에도 같은 환경변수로 다시 올라옵니다.
+프로덕션 프록시는 **Google Cloud Run** (`asia-northeast1`, GCP project `k-skill-proxy`)에서 운영되며, `k-skill-proxy.nomadamas.org` 도메인에 매핑되어 있습니다.
+
+- 컨테이너 이미지: `packages/k-skill-proxy/Dockerfile`
+- 자동 배포: `main` 브랜치 머지 시 `.github/workflows/deploy-k-skill-proxy.yml`이 Workload Identity Federation으로 GCP 인증 후 Artifact Registry로 이미지 빌드/푸시 → Cloud Run 재배포 → `/health` smoke test까지 수행합니다.
+- 시크릿: GCP Secret Manager에서 Cloud Run runtime에 주입됩니다.
+- 운영자 1회 셋업(WIF, Secret Manager, GitHub secrets) 절차는 [`docs/deploy-k-skill-proxy.md`](../../docs/deploy-k-skill-proxy.md) 참고.