POTE/docs/GITEA_SECRETS_GUIDE.md

Gitea Secrets Guide for POTE

YES! You Can Store Passwords in Gitea

Gitea has a Secrets feature (like GitHub Actions secrets) that lets you store passwords securely and use them in:

1. CI/CD pipelines (Gitea Actions workflows)
2. Deployment workflows

BUT NOT:

• Directly in your running application on Proxmox
• Accessed by scripts outside of workflows

---

What Gitea Secrets Are Good For

Perfect Use Cases

1. CI/CD Testing - Run tests with real credentials
2. Automated Deployment - Deploy to Proxmox with SSH keys
3. Notifications - Send emails/Slack after builds
4. Docker Registry - Push images with credentials
5. API Keys - Access external services during builds

NOT Good For

1. Runtime secrets - Your deployed app on Proxmox can't access them
2. Local development - Can't use secrets on your laptop
3. Manual scripts - Can't run python script.py with Gitea secrets

---

How to Set Up Gitea Secrets

Step 1: Add Secrets to Gitea

1. Go to your POTE repository in Gitea
2. Click Settings → Secrets (or Actions → Secrets)
3. Click Add Secret

Add these secrets:

Secret Name	Example Value	Used For
SMTP_PASSWORD	your_mail_password	Email reports in CI
DB_PASSWORD	changeme123	Database in CI
PROXMOX_HOST	10.0.10.95	Deployment
PROXMOX_USER	poteapp	Deployment
PROXMOX_SSH_KEY	-----BEGIN...	Deployment
SMTP_HOST	mail.levkin.ca	Email config
SMTP_USER	test@levkin.ca	Email config
FROM_EMAIL	test@levkin.ca	Email config

Step 2: Use Secrets in Workflows

Secrets are accessed with ${{ secrets.SECRET_NAME }} syntax.

---

Example: CI Pipeline with Secrets

File: .github/workflows/ci.yml

name: CI

on:
  push:
    branches: [main, master]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Check out code
        uses: actions/checkout@v4

      - name: Run tests
        env:
          # Use Gitea secrets
          DATABASE_URL: postgresql://user:${{ secrets.DB_PASSWORD }}@localhost/db
          SMTP_HOST: ${{ secrets.SMTP_HOST }}
          SMTP_PASSWORD: ${{ secrets.SMTP_PASSWORD }}
        run: |
          pytest tests/

      - name: Send notification
        if: failure()
        run: |
          # Send email using secrets
          python scripts/send_notification.py \
            --smtp-password "${{ secrets.SMTP_PASSWORD }}"

** I've already updated your CI pipeline to use secrets!**

---

Example: Automated Deployment Workflow

Create .github/workflows/deploy.yml:

name: Deploy to Proxmox

on:
  workflow_dispatch:  # Manual trigger

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Check out code
        uses: actions/checkout@v4

      - name: Setup SSH
        env:
          SSH_KEY: ${{ secrets.PROXMOX_SSH_KEY }}
          SSH_HOST: ${{ secrets.PROXMOX_HOST }}
        run: |
          mkdir -p ~/.ssh
          echo "$SSH_KEY" > ~/.ssh/id_rsa
          chmod 600 ~/.ssh/id_rsa
          ssh-keyscan -H $SSH_HOST >> ~/.ssh/known_hosts

      - name: Deploy to Proxmox
        env:
          PROXMOX_HOST: ${{ secrets.PROXMOX_HOST }}
          PROXMOX_USER: ${{ secrets.PROXMOX_USER }}
          SMTP_PASSWORD: ${{ secrets.SMTP_PASSWORD }}
          DB_PASSWORD: ${{ secrets.DB_PASSWORD }}
        run: |
          # SSH to Proxmox and update
          ssh $PROXMOX_USER@$PROXMOX_HOST << 'ENDSSH'
            cd ~/pote
            git pull
            
            # Update .env with secrets
            echo "SMTP_PASSWORD=${SMTP_PASSWORD}" >> .env
            echo "DATABASE_URL=postgresql://user:${DB_PASSWORD}@localhost/db" >> .env
            
            # Restart services
            source venv/bin/activate
            alembic upgrade head
          ENDSSH

      - name: Health Check
        run: |
          ssh ${{ secrets.PROXMOX_USER }}@${{ secrets.PROXMOX_HOST }} \
            "cd ~/pote && python scripts/health_check.py"

---

How Secrets Flow to Your Server

Option 1: Deploy Workflow Updates .env (Recommended)

# In deployment workflow
- name: Update secrets on server
  run: |
    ssh user@server << 'EOF'
      cd ~/pote
      # Update .env with secrets passed from Gitea
      sed -i "s/SMTP_PASSWORD=.*/SMTP_PASSWORD=${{ secrets.SMTP_PASSWORD }}/" .env
    EOF

Option 2: Use Environment Variables

# In deployment workflow
- name: Deploy with environment variables
  run: |
    ssh user@server << 'EOF'
      cd ~/pote
      # Export secrets as environment variables
      export SMTP_PASSWORD="${{ secrets.SMTP_PASSWORD }}"
      export DB_PASSWORD="${{ secrets.DB_PASSWORD }}"
      # Run scripts
      python scripts/send_daily_report.py
    EOF

Option 3: Secrets File on Server

# In deployment workflow
- name: Create secrets file
  run: |
    ssh user@server << 'EOF'
      # Create secure secrets file
      cat > /etc/pote/secrets << 'SECRETS'
      export SMTP_PASSWORD="${{ secrets.SMTP_PASSWORD }}"
      export DB_PASSWORD="${{ secrets.DB_PASSWORD }}"
      SECRETS
      chmod 600 /etc/pote/secrets
    EOF

---

Recommended Setup for Your POTE Project

For CI/CD (Testing):

Use Gitea Secrets

# .github/workflows/ci.yml (already updated!)
env:
  SMTP_PASSWORD: ${{ secrets.SMTP_PASSWORD }}
  DB_PASSWORD: ${{ secrets.DB_PASSWORD }}

For Deployed Server (Proxmox):

Keep using .env file

Why?

• Simpler for manual SSH access
• No need for complex deployment workflows
• Easy to update: just nano .env

BUT: Use Gitea secrets in a deployment workflow to UPDATE the .env file automatically!

---

Complete Workflow: Gitea → Proxmox

1. Store Secrets in Gitea

Repository Settings → Secrets:
- SMTP_PASSWORD: your_password
- PROXMOX_HOST: 10.0.10.95
- PROXMOX_SSH_KEY: (your SSH private key)

2. Create Deployment Workflow

See .github/workflows/deploy.yml (I'll create this next)

3. Trigger Deployment

# From Gitea UI:
Actions → Deploy to Proxmox → Run workflow

# Or commit and push:
git commit -m "Update code"
git push origin main
# Workflow runs automatically

4. Workflow Updates Proxmox

• SSH to Proxmox
• Pull latest code
• Update .env with secrets from Gitea
• Run migrations
• Health check

---

Important Limitations

Gitea Secrets CAN'T:

Be accessed outside of workflows Be used in local python script.py runs Be read by cron jobs on Proxmox (directly) Replace .env for runtime application config

Gitea Secrets CAN:

Secure your CI/CD pipeline Deploy safely without exposing passwords in git Update .env on server during deployment Run automated tests with real credentials

---

Security Best Practices

DO:

1. Store ALL sensitive data as Gitea secrets

   • SMTP passwords
   • Database passwords
   • API keys
   • SSH keys

2. Use secrets in workflows

   env:
     PASSWORD: ${{ secrets.PASSWORD }}
   

3. Never echo secrets

BAD - exposes in logs

• run: echo "${{ secrets.PASSWORD }}"

GOOD - masked automatically

• run: use_password "${{ secrets.PASSWORD }}"

4. **Rotate secrets regularly**
- Update in Gitea UI
- Re-run deployment workflow

### DON'T:

1. **Commit secrets to git** (even private repos)
2. **Share secrets via Slack/email**
3. **Use same password everywhere**
4. **Expose secrets in workflow logs**

---

## Comparison: Where to Store Secrets

| Storage | CI/CD | Deployed App | Easy Updates | Security |
|---------|-------|--------------|--------------|----------|
| **Gitea Secrets** | Perfect | No | Via workflow | |
| **`.env` file** | No | Perfect | `nano .env` | |
| **Environment Vars** | Yes | Yes | Harder | |
| **Both (Recommended)** | Yes | Yes | Automated | |

---

## My Recommendation for You

### Use BOTH:

1. **Gitea Secrets** - For CI/CD and deployment workflows
2. **`.env` file** - For runtime on Proxmox

### Workflow:

1. Store password in Gitea Secrets
2. Commit code changes
3. Push to Gitea
4. Workflow runs:

• Tests with Gitea secrets
• Deploys to Proxmox
• Updates .env with secrets

5. Proxmox app reads from .env

**This gives you:**
- Secure CI/CD
- Easy manual SSH access
- Automated deployments
- No passwords in git

---

## Next Steps

### 1. Add Secrets to Gitea (5 minutes)

1. Go to https://git.levkin.ca/ilia/POTE/settings/secrets
2. Add:
   • SMTP_PASSWORD: your_mail_password
   • DB_PASSWORD: changeme123
   • SMTP_HOST: mail.levkin.ca
   • SMTP_USER: test@levkin.ca
   • FROM_EMAIL: test@levkin.ca

### 2. Test CI Pipeline (Already Updated!)

```bash
git push origin main
# Watch Actions tab in Gitea
# CI should use secrets automatically

3. Create Deployment Workflow (Optional)

I can create .github/workflows/deploy.yml if you want automated deployments!

---

Quick Commands

Add SSH Key to Gitea (for deployment):

# On your local machine
cat ~/.ssh/id_rsa  # Copy this

# In Gitea:
Repository → Settings → Secrets → Add Secret
Name: PROXMOX_SSH_KEY
Value: (paste private key)

Test Gitea Secrets:

# Push a test commit
git commit --allow-empty -m "Test secrets"
git push

# Check Gitea Actions tab
# Look for green checkmarks

---

See Also

• docs/13_secrets_management.md - All secrets options
• .github/workflows/ci.yml - Updated with secrets support
• DEPLOYMENT_AND_AUTOMATION.md - Full deployment guide

---

Summary

YES, use Gitea secrets! They're perfect for:

• CI/CD pipelines
• Automated deployments
• Keeping passwords out of git

But ALSO keep .env on Proxmox for:

• Runtime application config
• Manual SSH access
• Cron jobs

Best of both worlds: Gitea secrets deploy and update the .env file automatically!