diff --git a/.gitea/workflows/deploy-vps.yaml b/.gitea/workflows/deploy-vps.yaml
index 5d1373f..3a0dfff 100644
--- a/.gitea/workflows/deploy-vps.yaml
+++ b/.gitea/workflows/deploy-vps.yaml
@@ -13,8 +13,17 @@ jobs:
       VPS_HOST: ${{ secrets.DEPLOY_VPS_HOST }}
       VPS_USER: ${{ secrets.DEPLOY_VPS_USER }}
     steps:
+      # Manual checkout: job container cannot resolve 'server', so clone via host IP (gateway).
+      # Set secret GITEA_HOST_IP to your runner host's gateway (from job: ip route show default | awk '{print $3}').
       - name: Checkout
-        uses: actions/checkout@v4
+        run: |
+          GITEA_HOST="${GITEA_HOST_IP:-172.20.0.1}"
+          git clone --depth 1 "http://oauth2:${GITHUB_TOKEN}@${GITEA_HOST}:3000/admin/honey-be.git" .
+          git fetch --depth 1 origin "${{ github.sha }}"
+          git checkout -q "${{ github.sha }}"
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+          GITEA_HOST_IP: ${{ secrets.GITEA_HOST_IP }}
 
       - name: Install SSH and Rsync
         run: |
diff --git a/docs/GITEA_VPS_DEPLOY.md b/docs/GITEA_VPS_DEPLOY.md
index c298163..f191955 100644
--- a/docs/GITEA_VPS_DEPLOY.md
+++ b/docs/GITEA_VPS_DEPLOY.md
@@ -135,6 +135,7 @@ Optional secrets (workflow has defaults):
 |------|--------|-------------|
 | `DEPLOY_VPS_HOST` | `188.116.23.7` | Only if your Staged VPS has a different IP. |
 | `DEPLOY_VPS_USER` | `root` | Only if the deploy user is not `root`. |
+| `GITEA_HOST_IP` | e.g. `172.20.0.1` | If checkout fails with "Could not resolve host: server", set this to the **default gateway** seen from the job container. Run a debug job that runs `ip route show default \| awk '{print $3}'` and use that value. The workflow defaults to `172.20.0.1` if unset. |
 
 ---
 
@@ -292,6 +293,9 @@ git push origin main
 
 ## Troubleshooting
 
+- **Could not resolve host: server** (during checkout)  
+  The deploy workflow uses a manual clone via the runner host IP. Set repository secret `GITEA_HOST_IP` to the default gateway as seen from the job container (e.g. run a debug job with `ip route show default | awk '{print $3}'` and use that value, often `172.20.0.1` or `172.17.0.1`). The workflow defaults to `172.20.0.1` if the secret is not set.
+
 - **Permission denied (publickey)**  
   Check: public key in `authorized_keys` on VPS, private key in `DEPLOY_SSH_PRIVATE_KEY`, no extra spaces/newlines when pasting.