diff --git a/.gitea/SETUP.md b/.gitea/SETUP.md
new file mode 100644
index 0000000..1bff755
--- /dev/null
+++ b/.gitea/SETUP.md
@@ -0,0 +1,49 @@
+# Gitea CI/CD — Setup Checklist
+
+After pushing, the pipeline will run automatically. The following steps are required to unlock all features (especially deploy jobs).
+
+## 1. Repository Secrets (Settings → Actions → Secrets)
+
+| Secret Name | Description |
+|---|---|
+| `SSH_PASSWORD` | SSH password for the deployment server |
+| `SSH_USER` | SSH username for the deployment server |
+| `SSH_HOST` | IP or domain of the deployment server |
+
+## 2. Repository Variables (Settings → Actions → Variables)
+
+| Variable Name | Default | Description |
+|---|---|---|
+| `SSH_PORT` | `22` | SSH port for the deployment server |
+| `SSH_TARGET_DIR` | — | Absolute path on the server where `dist/` contents should be placed |
+| `PRODUCTION_URL` | — | Public URL of the production site |
+| `VITE_API_ORIGIN` | — | (Optional) API base URL passed at build time |
+
+## 3. Allow Gitea Actions
+
+- Go to **Settings → Actions** in your Gitea repository
+- Ensure **"Actions"** are enabled
+- If using self-hosted runners, ensure a runner is registered and online
+
+## 4. Optional: Configure Gitea Actions Runner
+
+If no runner is registered yet on your Gitea instance:
+
+```bash
+# On the runner machine (Docker-based)
+docker run -d \
+  --name gitea-runner \
+  -e GITEA_INSTANCE_URL=https://192.168.3.80 \
+  -e GITEA_RUNNER_REGISTRATION_TOKEN=<your-registration-token> \
+  -e GITEA_RUNNER_NAME=runner-1 \
+  -v /var/run/docker.sock:/var/run/docker.sock \
+  gitea/act_runner:latest
+```
+
+## Pipeline Stages
+
+| Job | Requires Secrets/Vars | Runs on |
+|---|---|---|
+| `lint` | None | Push & PR |
+| `build` | None | Push & PR |
+| `deploy` | SSH secrets + vars | Manual on `develop` |