diff --git a/SECRETS_SETUP.md b/SECRETS_SETUP.md
new file mode 100644
index 0000000..2e5a2d9
--- /dev/null
+++ b/SECRETS_SETUP.md
@@ -0,0 +1,87 @@
+# Gitea Secrets Setup
+
+This document describes the secrets required for the HetznerTerra deployment workflow.
+
+## Required Secrets
+
+Add these secrets in your Gitea repository settings:
+**Settings → Secrets → Actions**
+
+### Infrastructure Secrets
+
+#### `HCLOUD_TOKEN`
+- Hetzner Cloud API token
+- Get from: https://console.hetzner.com/projects/{project-id}/security/api-tokens
+- Permissions: Read & Write
+
+#### `S3_ACCESS_KEY` & `S3_SECRET_KEY`
+- Backblaze B2 credentials for Terraform state storage
+- Get from: https://secure.backblaze.com/b2_buckets.htm
+- Create application key with access to your terraform state bucket
+
+#### `S3_ENDPOINT`
+- Backblaze B2 S3 endpoint
+- Example: `https://s3.eu-central-003.backblazeb2.com`
+
+#### `S3_BUCKET`
+- Backblaze B2 bucket name for Terraform state
+- Example: `k8s-terraform-state`
+
+### SSH Secrets
+
+#### `SSH_PRIVATE_KEY` & `SSH_PUBLIC_KEY`
+- SSH key pair for cluster access
+- Generate with: `ssh-keygen -t ed25519 -C "k8s@hetzner" -f ~/.ssh/hetzner_k8s`
+- Private key content (include BEGIN/END lines)
+- Public key content (full line starting with ssh-ed25519)
+
+### Tailscale Secrets
+
+#### `TAILSCALE_AUTH_KEY`
+- Tailscale auth key for node registration
+- Get from: https://login.tailscale.com/admin/settings/keys
+- Type: Reusable, Ephemeral
+- Scope: `devices:core:write`
+
+#### `TAILSCALE_TAILNET`
+- Your Tailscale network name
+- Example: `tail7ec33.ts.net` or your custom domain
+
+#### `TAILSCALE_OAUTH_CLIENT_ID` & `TAILSCALE_OAUTH_CLIENT_SECRET`
+- OAuth credentials for Tailscale Kubernetes Operator
+- Get from: https://login.tailscale.com/admin/settings/oauth
+- Create OAuth client with scope: `devices:core:write`
+
+### Application Secrets
+
+#### `GRAFANA_ADMIN_PASSWORD`
+- Admin password for Grafana
+- Generate a strong password: `openssl rand -base64 32`
+
+## Setting Up Secrets
+
+1. Go to your Gitea repository
+2. Navigate to **Settings → Secrets → Actions**
+3. Click **Add Secret**
+4. Enter the secret name (exact match from above)
+5. Paste the secret value
+6. Click **Add Secret**
+7. Repeat for all secrets
+
+## Verification
+
+After adding all secrets, trigger a workflow run:
+```bash
+git commit --allow-empty -m "ci: trigger workflow with new secrets"
+git push
+```
+
+Check the workflow logs to verify all secrets are being used correctly.
+
+## Security Notes
+
+- Never commit secrets to the repository
+- Use strong, unique passwords for Grafana and other services
+- Rotate Tailscale auth keys periodically
+- Review OAuth client permissions regularly
+- The workflow automatically opens SSH/API access only for the runner's IP during deployment