GitHub Repository Setup

Complete guide to configure GitHub repository for Nebula CI/CD.

Quick Setup Checklist

• Generate SSH deploy key
• Add public key to server
• Add DEPLOY_SSH_KEY secret to GitHub
• Add DEPLOY_HOST variable to GitHub
• Create production environment
• (Optional) Configure branch protection

1. SSH Key Generation

Generate a dedicated deploy key for GitHub Actions:

# Generate ed25519 key (recommended)
ssh-keygen -t ed25519 -C "github-actions-deploy" -f github_deploy_key -N ""

# Output:
# github_deploy_key       <- Private key (for GitHub Secrets)
# github_deploy_key.pub   <- Public key (for server)

Why ed25519?

• Shorter keys (better for secrets storage)
• Faster operations
• Modern and secure

2. Server Configuration

Add the public key to your deployment server:

# Connect to server
ssh root@your-server-ip

# Create .ssh directory if needed
mkdir -p ~/.ssh
chmod 700 ~/.ssh

# Add public key
echo "ssh-ed25519 AAAA... github-actions-deploy" >> ~/.ssh/authorized_keys
chmod 600 ~/.ssh/authorized_keys

# Verify
cat ~/.ssh/authorized_keys

Test connection:

# From local machine
ssh -i github_deploy_key root@your-server-ip "echo 'Connection OK'"

3. GitHub Secrets

Navigate to: Repository → Settings → Secrets and variables → Actions → Secrets

DEPLOY_SSH_KEY

Click "New repository secret":

Field	Value
Name	DEPLOY_SSH_KEY
Secret	Contents of github_deploy_key file

-----BEGIN OPENSSH PRIVATE KEY-----
b3BlbnNzaC1rZXktdjEAAAAABG5vbmUAAAAEbm9uZQAAAAAAAAABAAAAMwAAAAtzc2gtZW
...
-----END OPENSSH PRIVATE KEY-----

Important

Include the full key with headers (-----BEGIN... and -----END...)

4. GitHub Variables

Navigate to: Repository → Settings → Secrets and variables → Actions → Variables

DEPLOY_HOST

Click "New repository variable":

Field	Value
Name	DEPLOY_HOST
Value	Your server IP (e.g., 193.8.184.128)

5. Production Environment

For manual approval of nebulad deployments:

Navigate to: Repository → Settings → Environments

1. Click New environment
2. Name: production
3. Configure:

Setting	Value
Required reviewers	Add yourself or team members
Wait timer	0 minutes (optional)
Deployment branches	Selected branches → main

┌─────────────────────────────────────────────────────────────┐
│                    Environment: production                   │
├─────────────────────────────────────────────────────────────┤
│                                                               │
│  Protection rules                                             │
│  ───────────────                                              │
│  ☑ Required reviewers                                        │
│    └─ @your-username                                         │
│                                                               │
│  ☐ Wait timer                                                │
│                                                               │
│  Deployment branches                                          │
│  ───────────────────                                          │
│  ◉ Selected branches                                         │
│    └─ main                                                   │
│                                                               │
└─────────────────────────────────────────────────────────────┘

6. Branch Protection (Optional)

Navigate to: Repository → Settings → Branches → Add rule

For main branch:

☑ Require a pull request before merging
  ☑ Require approvals: 1
  ☐ Dismiss stale pull request approvals when new commits are pushed

☑ Require status checks to pass before merging
  ☑ Require branches to be up to date before merging
  Required checks:
    • lint
    • test
    • build (linux/amd64)

☐ Require signed commits

☑ Do not allow bypassing the above settings

Verification

Test CI Pipeline

# Create test branch
git checkout -b test-ci
echo "# test" >> README.md
git add . && git commit -m "test: CI pipeline"
git push origin test-ci

# Create PR in GitHub
# CI will run automatically

Test Release Pipeline

# Create pre-release tag (won't deploy to server)
git tag v0.1.0-test
git push origin v0.1.0-test

# Check GitHub Actions
# Should create GitHub Release marked as "Pre-release"
# Should NOT deploy to server

Full Release

# Create stable release
git tag -a v1.0.0 -m "Release v1.0.0"
git push origin v1.0.0

# What happens:
# 1. Build all binaries
# 2. Create GitHub Release with archives
# 3. Deploy agent to nebulactl.com (automatic)
# 4. Request approval for nebulad deploy

Troubleshooting

SSH Connection Failed

# Test connection manually
ssh -i github_deploy_key -v root@your-server-ip "echo test"

# Check key permissions
ls -la github_deploy_key
# Should be: -rw------- (600)

# Verify key on server
ssh root@your-server-ip "cat ~/.ssh/authorized_keys"

Secret Not Found

Error: DEPLOY_SSH_KEY is not set

1. Go to Settings → Secrets → Actions
2. Verify secret name is exactly DEPLOY_SSH_KEY
3. Re-create the secret if needed

Variable Empty

ssh: Could not resolve hostname : Name or service not known

1. Go to Settings → Secrets and variables → Actions → Variables
2. Verify DEPLOY_HOST variable exists and has correct IP

Environment Approval Not Working

1. Check environment name is exactly production
2. Verify you're listed as required reviewer
3. Check deployment branches include main

Deploy Fails on First Run

First deployment needs systemd service setup:

# SSH to server manually
ssh root@your-server-ip

# Check if service file exists
cat /etc/systemd/system/nebulad.service

# If missing, workflow will create it automatically
# Check workflow logs for "First-time setup" message

Security Best Practices

1. Use dedicated deploy key - Don't use personal SSH keys
2. Limit key permissions - Only add key to deployment server
3. Rotate keys periodically - Generate new keys every 6-12 months
4. Restrict environment - Only allow main branch deployments
5. Require reviews - Always require approval for production deploys

Repository Settings Summary

Repository Settings
├── Secrets and variables
│   └── Actions
│       ├── Secrets
│       │   └── DEPLOY_SSH_KEY = [private key content]
│       └── Variables
│           └── DEPLOY_HOST = 193.8.184.128
├── Environments
│   └── production
│       ├── Required reviewers: [@username]
│       └── Deployment branches: main
└── Branches (optional)
    └── main
        ├── Require PR
        └── Require status checks