docs/deployment/GITHUB_SECRETS_SETUP.md

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)

# 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

# Quick setup for just the development environment
just gh-setup-dev

Option 3: Manual Setup

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

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

# 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

# Add public key to deployment server
ssh-copy-id -i ~/.ssh/kgraph-deploy/dev_deploy_key.pub [email protected]

# 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

# 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

# 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

# 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

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

Branch Protection Rules

# 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

# 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 [email protected]

Password Generation

# Generate secure passwords
openssl rand -base64 32  # For database passwords
openssl rand -base64 64  # For secret keys

Audit Secrets

# 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

   gh auth status
   gh auth login
   

2. SSH key permission issues

   chmod 600 ~/.ssh/kgraph-deploy/*_deploy_key
   chmod 644 ~/.ssh/kgraph-deploy/*_deploy_key.pub
   

3. Environment creation fails

   # Check repository permissions
   gh api repos/:owner/:repo | jq '.permissions'
   
   # Ensure you have admin access
   

4. Secret setting fails

   # Check if secret name is valid (no spaces, special chars)
   # Verify environment exists
   gh api repos/:owner/:repo/environments
   

Getting Help

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