turbovault-app/docs/GITEA_SECRETS.md

# Gitea Secrets Configuration

This document explains what secrets you need to configure in Gitea for automatic builds and deployments.

## Required Secrets

### 1. GITEA_TOKEN

**Purpose:** Allows Gitea Actions to push Docker images to Gitea Container Registry

**How to create:**

1. Go to Gitea → **Settings** → **Applications**
2. Under **"Generate New Token"**, enter name: `gitea-actions`
3. Select scopes:
   - ✅ `write:package` (push container images)
   - ✅ `read:package` (pull container images)
4. Click **"Generate Token"**
5. Copy the token (starts with `glpat-...` or similar)

**How to add to repository:**

1. Go to your Gitea repository: `gitea.kazcloud.dev/ryankazokas/turbovault-app`
2. Click **Settings** → **Secrets**
3. Click **"Add Secret"**
4. Name: `GITEA_TOKEN`
5. Value: Paste the token you copied
6. Click **"Add Secret"**

---

### 2. KUBECONFIG

**Purpose:** Allows Gitea Actions to deploy to your Kubernetes cluster

**How to create:**

```bash
# Export your kubeconfig as base64
cat ~/.kube/config | base64 -w 0 > kubeconfig-base64.txt

# Copy the contents of kubeconfig-base64.txt
cat kubeconfig-base64.txt
```

**How to add to repository:**

1. Go to your Gitea repository: `gitea.kazcloud.dev/ryankazokas/turbovault-app`
2. Click **Settings** → **Secrets**
3. Click **"Add Secret"**
4. Name: `KUBECONFIG`
5. Value: Paste the base64-encoded kubeconfig
6. Click **"Add Secret"**

**⚠️ Security Note:** This gives Gitea Actions full access to your Kubernetes cluster. Only add this to trusted repositories!

---

## Optional: Scoped Kubeconfig (More Secure)

Instead of using your full kubeconfig, create a limited service account:

```bash
# Create service account for deployments
kubectl create serviceaccount turbovault-deployer -n turbovault

# Create role with deployment permissions
cat <<EOF | kubectl apply -f -
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: turbovault-deployer
  namespace: turbovault
rules:
- apiGroups: ["apps"]
  resources: ["deployments"]
  verbs: ["get", "list", "patch", "update"]
- apiGroups: [""]
  resources: ["pods"]
  verbs: ["get", "list"]
- apiGroups: ["apps"]
  resources: ["deployments/status"]
  verbs: ["get"]
EOF

# Bind role to service account
kubectl create rolebinding turbovault-deployer \
  --role=turbovault-deployer \
  --serviceaccount=turbovault:turbovault-deployer \
  -n turbovault

# Get service account token
kubectl create token turbovault-deployer -n turbovault --duration=87600h > token.txt

# Create minimal kubeconfig
cat <<EOF > deployer-kubeconfig.yaml
apiVersion: v1
kind: Config
clusters:
- cluster:
    server: https://100.101.31.99:6443
    # Add certificate-authority-data from your main kubeconfig if needed
    insecure-skip-tls-verify: true
  name: k3s
contexts:
- context:
    cluster: k3s
    namespace: turbovault
    user: turbovault-deployer
  name: k3s
current-context: k3s
users:
- name: turbovault-deployer
  user:
    token: $(cat token.txt)
EOF

# Encode for Gitea
cat deployer-kubeconfig.yaml | base64 -w 0 > deployer-kubeconfig-base64.txt

# Use this in KUBECONFIG secret instead
cat deployer-kubeconfig-base64.txt
```

This limits Gitea Actions to only deploying TurboVault, not full cluster access.

---

## Verifying Secrets

After adding secrets, you can verify they're set:

1. Go to repository → **Settings** → **Secrets**
2. You should see:
   - `GITEA_TOKEN` ✅
   - `KUBECONFIG` ✅

**Note:** You can't view secret values after creation (security feature).

---

## Testing the Workflow

After secrets are configured:

```bash
# Create a test tag
git tag v0.0.1-test
git push origin v0.0.1-test
```

Watch the workflow at:
`gitea.kazcloud.dev/ryankazokas/turbovault-app/actions`

The workflow should:
1. ✅ Build Docker image
2. ✅ Push to Gitea registry
3. ✅ Deploy to Kubernetes
4. ✅ Wait for rollout to complete

---

## Troubleshooting

### "Error: authentication required"
- Check `GITEA_TOKEN` is set and has `write:package` scope

### "Error: Unable to connect to the server"
- Check `KUBECONFIG` secret is set correctly
- Verify base64 encoding (no line breaks with `-w 0`)
- Test kubeconfig works locally: `kubectl --kubeconfig=<file> get pods -n turbovault`

### "Error: deployment not found"
- Make sure initial deployment is done first: `./scripts/deploy-k8s.sh`
- Workflow only updates existing deployments, doesn't create them

---

## Security Best Practices

✅ **DO:**
- Use service account with minimal permissions (Role, not ClusterRole)
- Rotate tokens regularly
- Only add secrets to repositories you control

❌ **DON'T:**
- Share secrets in code or documentation
- Use admin kubeconfig if possible
- Commit secrets to git

---

## Summary

**Two secrets required:**

1. **GITEA_TOKEN** - For pushing container images
2. **KUBECONFIG** - For deploying to Kubernetes

Both added at: `gitea.kazcloud.dev/ryankazokas/turbovault-app/settings/secrets`

After setup, just push tags to trigger automatic builds and deployments! 🚀