Homepage/GITEA-SETUP.md

Gitea Actions Auto-Deploy Setup

Prerequisites

• Gitea instance with Actions enabled
• Kubernetes cluster access
• kubectl configured locally

Setup Steps

1. Enable Gitea Actions

In your Gitea instance admin panel:

• Go to Site Administration → Actions
• Enable Actions if not already enabled
• Ensure Actions runners are configured

2. Configure Repository Secrets

Go to your repository → Settings → Secrets

Add the following secret:

KUBE_CONFIG

Your kubeconfig file content. You have two options:

Option 1: Base64 encoded (recommended)

# Get your kubeconfig in base64 format (single line)
cat ~/.kube/config | base64 -w 0

Option 2: Raw kubeconfig content

# If base64 fails, use raw content
cat ~/.kube/config

Copy the output and paste it as the value for KUBE_CONFIG secret.

Note

: The workflow automatically handles both base64-encoded and raw kubeconfig formats.

3. Configure Environment (Optional but Recommended)

Go to repository → Settings → Environments

Create environment named: production

• Add environment protection rules if needed
• Set required reviewers for production deployments

4. Verify Actions Runner

Ensure you have an Actions runner available:

• Check Repository Settings → Actions → Runners
• If no runners, set up a self-hosted runner or use Gitea's shared runners

How It Works

1. Push to main/master triggers the workflow automatically
2. Manual trigger available via Actions tab → "Deploy to Kubernetes"
3. Workflow applies Kustomize configuration
4. ConfigMap changes automatically restart pods
5. Deployment status is verified before completion

Workflow Features

• ✅ Automatic deployment on push to main/master
• ✅ Manual deployment trigger available
• ✅ Kubernetes connection verification
• ✅ Deployment rollout status monitoring
• ✅ Security cleanup (kubeconfig removed after use)
• ✅ Pod and service verification

Monitoring Deployments

Via Gitea

• Go to Actions tab to see workflow runs
• Click on specific run for detailed logs

Via kubectl

# Check deployment status
kubectl rollout status deployment/homepage -n homepage

# View pods
kubectl get pods -n homepage

# View services  
kubectl get svc -n homepage

# View configmap (note the hash suffix)
kubectl get configmap -n homepage

Troubleshooting

Runner Issues

• Verify Actions runner is online in repository settings
• Check runner has sufficient resources and network access to K8s

Authentication Issues

• Ensure KUBE_CONFIG secret is properly base64 encoded
• Verify the kubeconfig has necessary permissions for the homepage namespace
• Test kubeconfig locally: kubectl --kubeconfig=<path> get pods -n homepage

Deployment Issues

• Check workflow logs in Gitea Actions tab
• Verify namespace exists: kubectl get namespace homepage
• Check for resource quotas or RBAC restrictions

Security Notes

• KUBE_CONFIG secret contains cluster admin access - keep secure
• Workflow automatically cleans up kubeconfig after each run
• Consider using service accounts with limited permissions instead of admin kubeconfig
• Environment protection can require manual approval for production deployments

Configuration Updates

To update your homepage configuration:

1. Edit files in k8s/configmap-files/
2. Commit and push to main/master
3. Actions workflow automatically deploys changes
4. ConfigMap hash changes trigger pod restart with new config

Example:

# Edit configuration
nano k8s/configmap-files/services.yaml

# Commit and push
git add k8s/configmap-files/services.yaml
git commit -m "Update services configuration"
git push origin main

# Deployment happens automatically!