fix: deploy Storybook from immutable source archive

.gitea/workflows/deploy-storybook.yml

@@ -14,18 +14,26 @@ jobs:
   deploy:
     runs-on: ubuntu-latest
     steps:
+      - name: Check out workflow commit
+        uses: actions/checkout@v4
+
       - name: Prepare SSH credentials
         env:
           DEPLOY_SSH_KEY: ${{ secrets.DEPLOY_SSH_KEY }}
           DEPLOY_KNOWN_HOSTS: ${{ vars.DEPLOY_KNOWN_HOSTS }}
         run: |
+          test -n "$DEPLOY_SSH_KEY"
+          test -n "$DEPLOY_KNOWN_HOSTS"
           install -d -m 700 "$HOME/.ssh"
           printf '%s\n' "$DEPLOY_SSH_KEY" > "$HOME/.ssh/deploy_key"
           chmod 600 "$HOME/.ssh/deploy_key"
           printf '%s\n' "$DEPLOY_KNOWN_HOSTS" > "$HOME/.ssh/deploy_known_hosts"
           chmod 600 "$HOME/.ssh/deploy_known_hosts"
 
-      - name: Update checkout and deploy on host
+      - name: Package source checkout
+        run: git archive --format=tar.gz --output="$RUNNER_TEMP/hmdesign-storybook-$GITHUB_SHA.tar.gz" "$GITHUB_SHA"
+
+      - name: Transfer source and deploy on host
         env:
           DEPLOY_HOST: ${{ vars.DEPLOY_HOST }}
           DEPLOY_USER: ${{ vars.DEPLOY_USER }}
@@ -37,19 +45,34 @@ jobs:
           test -n "$DEPLOY_PATH"
           test -n "$DEPLOY_PORT"
           DEPLOY_PATH_B64="$(printf '%s' "$DEPLOY_PATH" | base64 | tr -d '\n')"
+          ARCHIVE="$RUNNER_TEMP/hmdesign-storybook-$GITHUB_SHA.tar.gz"
+          REMOTE_ARCHIVE="/tmp/hmdesign-storybook-$GITHUB_SHA.tar.gz"
+          ssh_options=(
+            -i "$HOME/.ssh/deploy_key"
+            -p "$DEPLOY_PORT"
+            -o BatchMode=yes
+            -o StrictHostKeyChecking=yes
+            -o UserKnownHostsFile="$HOME/.ssh/deploy_known_hosts"
+          )
+          scp_options=(
+            -i "$HOME/.ssh/deploy_key"
+            -P "$DEPLOY_PORT"
+            -o BatchMode=yes
+            -o StrictHostKeyChecking=yes
+            -o UserKnownHostsFile="$HOME/.ssh/deploy_known_hosts"
+          )
+          scp "${scp_options[@]}" "$ARCHIVE" "$DEPLOY_USER@$DEPLOY_HOST:$REMOTE_ARCHIVE"
           ssh \
-            -i "$HOME/.ssh/deploy_key" \
-            -p "$DEPLOY_PORT" \
-            -o BatchMode=yes \
-            -o StrictHostKeyChecking=yes \
-            -o UserKnownHostsFile="$HOME/.ssh/deploy_known_hosts" \
+            "${ssh_options[@]}" \
             "$DEPLOY_USER@$DEPLOY_HOST" \
-            "DEPLOY_PATH_B64=$DEPLOY_PATH_B64 bash -se" <<'REMOTE'
+            "DEPLOY_PATH_B64=$DEPLOY_PATH_B64 RELEASE_SHA=$GITHUB_SHA bash -se" <<'REMOTE'
           set -euo pipefail
           DEPLOY_PATH="$(printf '%s' "$DEPLOY_PATH_B64" | base64 -d)"
-          cd "$DEPLOY_PATH"
-          git fetch origin main
-          git checkout main
-          git pull --ff-only origin main
-          docker compose down && STORYBOOK_PORT=6024 docker compose up -d --build
+          RELEASE_DIR="$DEPLOY_PATH/.storybook-deploy/releases/$RELEASE_SHA"
+          mkdir -p "$RELEASE_DIR"
+          tar -xzf "/tmp/hmdesign-storybook-$RELEASE_SHA.tar.gz" -C "$RELEASE_DIR"
+          rm -f "/tmp/hmdesign-storybook-$RELEASE_SHA.tar.gz"
+          cd "$RELEASE_DIR"
+          STORYBOOK_PORT=6024 docker compose build
+          STORYBOOK_PORT=6024 docker compose up -d --no-build --remove-orphans
           REMOTE

.gitignore

@@ -14,6 +14,7 @@ theme-dist/
 !.env.example
 
 _local/
+.storybook-deploy/
 .claude/settings.local.json
 
 # Generated recruitment exports and local test output.

README.md

@@ -71,9 +71,9 @@ docker compose up -d --build
 
 ### Gitea Actions 배포
 
-`.gitea/workflows/deploy-storybook.yml`은 `main`에 push되거나 수동 실행될 때 SSH로 배포 서버의 기존 저장소를 갱신하고, 그 서버에서 `docker compose down && docker compose up -d --build`를 실행합니다. 빌드와 호스팅은 배포 서버에서 이뤄지며 Storybook 산출물을 별도로 전송하지 않습니다. 서비스는 배포 서버의 **6024 포트**를 사용합니다.
+`.gitea/workflows/deploy-storybook.yml`은 `main`에 push되거나 수동 실행될 때 해당 실행 커밋의 소스 archive를 SSH로 배포 서버에 보내고, 서버에서 Docker build와 Compose 갱신을 수행합니다. 기존 Git 작업 트리는 건드리지 않고 빌드는 서버에서 이뤄지며, 빌드 산출물은 Actions Runner에서 전송하지 않습니다. 실행 커밋별 소스는 `.storybook-deploy/releases/`에 보관하고 서비스는 배포 서버의 **6024 포트**를 사용합니다. 새 이미지 빌드가 끝난 뒤 Compose가 컨테이너를 교체하므로 빌드 중에는 현재 서비스를 유지합니다.
 
-저장소 Actions Variables에 `DEPLOY_HOST` (`10.13.10.4`), `DEPLOY_USER` (`user`), `DEPLOY_PATH` (`/home/user/services/HMDesign`), `DEPLOY_PORT` (`22`), `DEPLOY_KNOWN_HOSTS` (배포 서버의 검증된 SSH host key)를 설정하고, Actions Secret에 `DEPLOY_SSH_KEY`를 등록합니다. 배포 서버 계정은 해당 경로의 저장소에서 `origin/main`을 가져올 수 있어야 하며 Docker Engine/Compose plugin 실행 권한이 필요합니다. Actions Runner는 SSH로 배포 서버에 접속할 수 있어야 합니다.
+저장소 Actions Variables에 `DEPLOY_HOST` (`10.13.10.4`), `DEPLOY_USER` (`user`), `DEPLOY_PATH` (`/home/user/services/HMDesign`), `DEPLOY_PORT` (`22`), `DEPLOY_KNOWN_HOSTS` (배포 서버의 검증된 SSH host key)를 설정하고, Actions Secret에 `DEPLOY_SSH_KEY`를 등록합니다. 배포 서버 계정은 지정한 경로에 `.storybook-deploy/releases/`를 만들고 Docker Engine/Compose plugin을 실행할 권한이 필요합니다. Actions Runner는 SSH와 SCP로 배포 서버에 접속할 수 있어야 합니다.
 
 문서 내부 링크 검사는 프로젝트 루트에서 `node scripts/check-doc-links.mjs`로 실행합니다. `.git`이 있으면 기존 Git 추적·비추적(ignored 제외) Markdown 수집을 유지하고, `.git` 없는 압축 해제본에서는 파일 시스템과 루트·하위 `.gitignore`의 현재 경로·와일드카드·제외/예외 규칙으로 수집합니다. `.git` 메타데이터와 ignored 폴더는 순회하지 않습니다. Node만 있으면 독립 실행할 수 있으며 결과에 `collectionMode`, 실제 MD/링크 수와 문제 목록을 출력합니다. 종료 코드 0은 통과, 1은 링크 오류, 2는 수집 실행 오류입니다. 회귀 검사는 `node --test scripts/check-doc-links.test.mjs`입니다(두 수집 방식 비교에는 Git 필요).
 

compose.yaml

@@ -1,3 +1,5 @@
+name: hmdesign
+
 services:
   storybook:
     build: .