# GitHub Secrets Setup Guide

## 🎯 Overview

This guide walks you through setting up all required GitHub secrets and environment variables for the KGraph-MCP CI/CD pipeline using GitHub CLI.

## 🚀 Quick Start

### Option 1: Interactive Setup (Recommended)
```bash
# Install GitHub CLI if not already installed
# macOS: brew install gh
# Ubuntu: sudo apt install gh
# Windows: winget install GitHub.cli

# Authenticate with GitHub
gh auth login

# Run the interactive setup
just gh-setup-secrets

# Or directly run the script
./scripts/setup-github-secrets.sh interactive
```

### Option 2: Development Only Setup
```bash
# Quick setup for just the development environment
just gh-setup-dev
```

### Option 3: Manual Setup
```bash
# Manual input of all values
just gh-setup-secrets manual
```

## 📋 What Gets Set Up

### Repository Secrets (Global)
- `SLACK_WEBHOOK` - Slack webhook URL for notifications
- `SENTRY_DSN` - Sentry DSN for error tracking

### Repository Variables (Public)
- `DOCKER_REGISTRY` - Container registry URL (ghcr.io)
- `IMAGE_NAME` - Docker image name (kgraph-mcp)
- `DEV_URL` - Development environment URL
- `STAGING_URL` - Staging environment URL
- `PROD_URL` - Production environment URL

### Environment-Specific Secrets

#### Development Environment
- `DEV_HOST` - Development server hostname
- `DEV_USER` - Deployment user (default: deploy)
- `DEV_DEPLOY_KEY` - SSH private key for dev deployment

#### Staging Environment
- `STAGING_HOST` - Staging server hostname
- `STAGING_USER` - Deployment user
- `STAGING_DEPLOY_KEY` - SSH private key for staging deployment
- `DB_PASSWORD` - Database password
- `REDIS_PASSWORD` - Redis password

#### Production Environment
- `PROD_HOST` - Production server hostname
- `PROD_USER` - Deployment user
- `PROD_DEPLOY_KEY` - SSH private key for production deployment
- `DB_PASSWORD` - Database password
- `REDIS_PASSWORD` - Redis password
- `SECRET_KEY` - Application secret key
- `GRAFANA_PASSWORD` - Grafana admin password

## 🔑 SSH Key Management

### Automatic Key Generation
The interactive setup automatically generates SSH keys for each environment:

```bash
# Generate SSH keys only (without setting secrets)
just gh-generate-keys

# Keys are stored in:
~/.ssh/kgraph-deploy/dev_deploy_key
~/.ssh/kgraph-deploy/staging_deploy_key
~/.ssh/kgraph-deploy/prod_deploy_key
```

### Manual Key Setup
If you prefer to use existing SSH keys:

```bash
# Copy your existing key
cp ~/.ssh/id_rsa ~/.ssh/kgraph-deploy/dev_deploy_key

# Or generate manually
ssh-keygen -t ed25519 -f ~/.ssh/kgraph-deploy/dev_deploy_key -C "kgraph-deploy-dev"
```

### Adding Keys to Servers
```bash
# Add public key to deployment server
ssh-copy-id -i ~/.ssh/kgraph-deploy/dev_deploy_key.pub deploy@your-dev-server.com

# Or manually append to authorized_keys
cat ~/.ssh/kgraph-deploy/dev_deploy_key.pub | ssh deploy@your-server "mkdir -p ~/.ssh && cat >> ~/.ssh/authorized_keys"
```

## 🔧 GitHub Environments

The script automatically creates three GitHub environments with appropriate protection rules:

### Development Environment
- **Wait Timer**: 0 minutes
- **Required Reviewers**: None
- **Prevent Self Review**: False
- **Auto-Deploy**: On push to `develop`

### Staging Environment
- **Wait Timer**: 0 minutes
- **Required Reviewers**: None (configurable)
- **Prevent Self Review**: True
- **Deploy Trigger**: Push to `release/*`

### Production Environment
- **Wait Timer**: 5 minutes
- **Required Reviewers**: None (configurable)
- **Prevent Self Review**: True
- **Deploy Trigger**: Tagged releases (`v*`)

## 📊 Verification

### List Current Secrets
```bash
# List all secrets and variables
just gh-list-secrets

# Or use GitHub CLI directly
gh secret list
gh variable list

# List environment-specific secrets
gh api repos/:owner/:repo/environments/development/secrets
gh api repos/:owner/:repo/environments/staging/secrets
gh api repos/:owner/:repo/environments/production/secrets
```

### Test the Setup
```bash
# Test development deployment
git checkout develop
git commit --allow-empty -m "test: trigger dev deployment"
git push origin develop

# Check GitHub Actions
gh run list
gh run view <run-id>
```

## 🛠️ Advanced Configuration

### Adding Required Reviewers
```bash
# Add required reviewers for production environment
gh api repos/:owner/:repo/environments/production -X PUT \
  --field reviewers='[{"type":"User","id":12345}]'

# Or use team reviewers
gh api repos/:owner/:repo/environments/production -X PUT \
  --field reviewers='[{"type":"Team","id":67890}]'
```

### Custom Wait Times
```bash
# Set 30-minute wait for production
gh api repos/:owner/:repo/environments/production -X PUT \
  --field wait_timer=1800
```

### Branch Protection Rules
```bash
# Protect main branch
gh api repos/:owner/:repo/branches/main/protection -X PUT \
  --field required_status_checks='{"strict":true,"contexts":["ci"]}' \
  --field enforce_admins=true \
  --field required_pull_request_reviews='{"required_approving_review_count":1}' \
  --field restrictions=null

# Protect develop branch
gh api repos/:owner/:repo/branches/develop/protection -X PUT \
  --field required_status_checks='{"strict":true,"contexts":["ci"]}' \
  --field enforce_admins=false \
  --field required_pull_request_reviews=null \
  --field restrictions=null
```

## 🔐 Security Best Practices

### Secret Rotation
```bash
# Rotate deployment keys periodically
ssh-keygen -t ed25519 -f ~/.ssh/kgraph-deploy/prod_deploy_key -C "kgraph-deploy-prod"

# Update the secret
cat ~/.ssh/kgraph-deploy/prod_deploy_key | gh secret set PROD_DEPLOY_KEY --env production

# Update on server
ssh-copy-id -i ~/.ssh/kgraph-deploy/prod_deploy_key.pub deploy@prod-server.com
```

### Password Generation
```bash
# Generate secure passwords
openssl rand -base64 32  # For database passwords
openssl rand -base64 64  # For secret keys
```

### Audit Secrets
```bash
# Check secret usage in workflows
gh api repos/:owner/:repo/actions/secrets

# Review environment protection rules
gh api repos/:owner/:repo/environments
```

## 🚨 Troubleshooting

### Common Issues

1. **GitHub CLI not authenticated**
   ```bash
   gh auth status
   gh auth login
   ```

2. **SSH key permission issues**
   ```bash
   chmod 600 ~/.ssh/kgraph-deploy/*_deploy_key
   chmod 644 ~/.ssh/kgraph-deploy/*_deploy_key.pub
   ```

3. **Environment creation fails**
   ```bash
   # Check repository permissions
   gh api repos/:owner/:repo | jq '.permissions'
   
   # Ensure you have admin access
   ```

4. **Secret setting fails**
   ```bash
   # Check if secret name is valid (no spaces, special chars)
   # Verify environment exists
   gh api repos/:owner/:repo/environments
   ```

### Getting Help
```bash
# Show setup help
just help-gh-secrets

# GitHub CLI help
gh secret --help
gh variable --help
gh api --help
```

## 📚 Next Steps

After setting up secrets:

1. **Configure Deployment Servers**: Set up your dev/staging/prod servers
2. **Test Deployments**: Create a test PR to verify the pipeline
3. **Set Up Monitoring**: Configure Prometheus/Grafana dashboards
4. **Create Runbooks**: Document operational procedures

---

*This guide ensures secure, automated setup of all CI/CD secrets using modern GitHub CLI tools.*