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:

# 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:

# 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:

# 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! 🚀