cv-site/GITHUB-ACTION-SETUP.md

GitHub Actions Deployment Setup

This guide will help you configure automated deployment for your CV server.

How It Works

When you push to the main branch, GitHub Actions will:

1. SSH into your server
2. Pull the latest code with git pull origin main
3. Restart your systemd service
4. Verify the deployment by checking the health endpoint

Prerequisites

✅ Your server must have:

• Git repository cloned at the deployment path
• Systemd service configured to run go run .
• SSH access configured
• sudo permissions for the user (to restart systemd service)

GitHub Secrets Configuration

Go to your GitHub repository → Settings → Secrets and variables → Actions → New repository secret

Required Secrets

Secret Name	Description	Example Value
SSH_PRIVATE_KEY	Your SSH private key	-----BEGIN OPENSSH PRIVATE KEY----- ... -----END OPENSSH PRIVATE KEY-----
SSH_HOST	Your server's IP or domain	192.168.1.100 or cv.example.com
SSH_USER	SSH username	deploy or ubuntu

Optional Secrets (with defaults)

Secret Name	Description	Default Value
SSH_PORT	SSH port number	22
SERVICE_NAME	Systemd service name	cv-server
REPO_PATH	Path to repository on server	/opt/cv-server

Step-by-Step Setup

1. Generate SSH Key Pair (if you don't have one)

On your local machine:

ssh-keygen -t ed25519 -C "github-actions-cv-deploy" -f ~/.ssh/cv-deploy

This creates:

• ~/.ssh/cv-deploy (private key) - Add to GitHub Secrets
• ~/.ssh/cv-deploy.pub (public key) - Add to server

2. Add Public Key to Server

Copy the public key to your server:

ssh-copy-id -i ~/.ssh/cv-deploy.pub your-user@your-server

Or manually:

# On your server
mkdir -p ~/.ssh
chmod 700 ~/.ssh
echo "YOUR_PUBLIC_KEY_CONTENT" >> ~/.ssh/authorized_keys
chmod 600 ~/.ssh/authorized_keys

3. Add Private Key to GitHub Secrets

# Copy the private key content
cat ~/.ssh/cv-deploy

Copy the entire output (including -----BEGIN and -----END lines) and add it as SSH_PRIVATE_KEY secret in GitHub.

4. Configure Sudoers (for service restart)

Your SSH user needs permission to restart the systemd service without a password:

# On your server
sudo visudo -f /etc/sudoers.d/cv-deploy

Add this line (replace your-user with your SSH username):

your-user ALL=(ALL) NOPASSWD: /bin/systemctl restart cv-server, /bin/systemctl status cv-server, /bin/systemctl is-active cv-server, /usr/bin/journalctl -u cv-server*

Save and verify:

sudo -l  # Should show the commands without requiring password

5. Example Systemd Service

Your systemd service should be configured to run go run .. Example at /etc/systemd/system/cv-server.service:

[Unit]
Description=CV Server - Go Hot Reload
After=network.target

[Service]
Type=simple
User=your-user
WorkingDirectory=/opt/cv-server
Environment="GO_ENV=production"
Environment="PORT=1999"
ExecStart=/usr/local/go/bin/go run .
Restart=always
RestartSec=3

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl daemon-reload
sudo systemctl enable cv-server
sudo systemctl start cv-server

6. Add GitHub Secrets

In your GitHub repository:

1. Go to Settings → Secrets and variables → Actions
2. Click New repository secret
3. Add each secret:

SSH_PRIVATE_KEY: [paste entire private key]
SSH_HOST: your.server.ip.or.domain
SSH_USER: your-ssh-username
SSH_PORT: 22 (if using default, can skip)
SERVICE_NAME: cv-server (if different, update)
REPO_PATH: /opt/cv-server (if different, update)

Testing the Deployment

Manual Trigger

You can manually trigger the deployment:

1. Go to Actions tab in GitHub
2. Click Deploy CV Server workflow
3. Click Run workflow → Run workflow

Automatic Trigger

Simply push to main:

git add .
git commit -m "Test deployment"
git push origin main

Verify Deployment

Check the Actions tab in GitHub to see the deployment progress. The workflow will:

• ✅ Pull latest code
• ✅ Restart service
• ✅ Check service status
• ✅ Verify health endpoint

Troubleshooting

SSH Connection Issues

# Test SSH connection from GitHub Actions
ssh -i ~/.ssh/cv-deploy -p 22 user@host "echo 'Connection successful'"

Service Restart Issues

# Check service logs
sudo journalctl -u cv-server -n 50 --no-pager

# Check service status
sudo systemctl status cv-server

Permission Issues

# Verify sudoers configuration
sudo -l

# Test restart command
sudo systemctl restart cv-server

Health Check Failures

# Test health endpoint on server
curl http://localhost:1999/health

# Check if service is listening
sudo netstat -tlnp | grep 1999

Security Best Practices

✅ Use ED25519 SSH keys (more secure than RSA) ✅ Restrict sudo permissions to specific commands only ✅ Use a dedicated deployment user (not root) ✅ Regularly rotate SSH keys ✅ Enable firewall rules to restrict SSH access ✅ Use SSH key passphrase (store in GitHub Secrets if needed)

Next Steps

After setup is complete:

1. Test the deployment with a small change
2. Monitor the first few deployments
3. Set up notifications for failed deployments (GitHub Actions settings)
4. Consider adding deployment tags/releases for rollback capability