claudetools/projects/msp-tools/guru-connect/CI_CD_SETUP.md

GuruConnect CI/CD Setup Guide

Version: Phase 1 Week 3 Status: Ready for Installation CI Platform: Gitea Actions

---

Overview

Automated CI/CD pipeline for GuruConnect using Gitea Actions:

• Automated Builds - Build server and agent on every commit
• Automated Tests - Run unit, integration, and security tests
• Automated Deployment - Deploy to production on version tags
• Build Artifacts - Store and version all build outputs
• Version Tagging - Automated semantic versioning

---

Architecture

┌─────────────┐      ┌──────────────┐      ┌─────────────┐
│   Git Push  │─────>│ Gitea Actions│─────>│   Deploy    │
│             │      │   Workflows   │      │  to Server  │
└─────────────┘      └──────────────┘      └─────────────┘
                            │
                            ├─ Build Server (Linux)
                            ├─ Build Agent (Windows)
                            ├─ Run Tests
                            ├─ Security Audit
                            └─ Create Artifacts

---

Workflows

1. Build and Test (build-and-test.yml)

Triggers:

• Push to main or develop branches
• Pull requests to main

Jobs:

• Build Server (Linux x86_64)
• Build Agent (Windows x86_64)
• Security Audit (cargo audit)
• Upload Artifacts (30-day retention)

Artifacts:

• guruconnect-server-linux - Server binary
• guruconnect-agent-windows - Agent binary (.exe)

2. Run Tests (test.yml)

Triggers:

• Push to any branch
• Pull requests

Jobs:

• Unit Tests (server & agent)
• Integration Tests
• Code Coverage
• Linting & Formatting

Artifacts:

• Coverage reports (XML)

3. Deploy to Production (deploy.yml)

Triggers:

• Push tags matching v*.*.* (e.g., v0.1.0)
• Manual workflow dispatch

Jobs:

• Build release version
• Create deployment package
• Deploy to production server (172.16.3.30)
• Create GitHub release
• Upload release assets

Artifacts:

• Deployment packages (90-day retention)

---

Installation Steps

1. Install Gitea Actions Runner

# On the RMM server (172.16.3.30)
ssh guru@172.16.3.30

cd ~/guru-connect/scripts
sudo bash install-gitea-runner.sh

2. Register the Runner

# Get registration token from Gitea:
# https://git.azcomputerguru.com/admin/actions/runners

# Register runner
sudo -u gitea-runner act_runner register \
  --instance https://git.azcomputerguru.com \
  --token YOUR_REGISTRATION_TOKEN \
  --name gururmm-runner \
  --labels ubuntu-latest,ubuntu-22.04

3. Start the Runner Service

sudo systemctl daemon-reload
sudo systemctl enable gitea-runner
sudo systemctl start gitea-runner
sudo systemctl status gitea-runner

4. Upload Workflow Files

# From local machine
cd D:\ClaudeTools\projects\msp-tools\guru-connect

# Copy workflow files to server
scp -r .gitea guru@172.16.3.30:~/guru-connect/

# Copy scripts to server
scp scripts/deploy.sh guru@172.16.3.30:~/guru-connect/scripts/
scp scripts/version-tag.sh guru@172.16.3.30:~/guru-connect/scripts/

# Make scripts executable
ssh guru@172.16.3.30 "cd ~/guru-connect/scripts && chmod +x *.sh"

5. Commit and Push Workflows

# On server
ssh guru@172.16.3.30
cd ~/guru-connect

git add .gitea/ scripts/
git commit -m "ci: add Gitea Actions workflows and deployment automation"
git push origin main

---

Usage

Triggering Builds

Automatic:

• Push to main or develop → Runs build + test
• Create pull request → Runs all tests
• Push version tag → Deploys to production

Manual:

• Go to repository > Actions
• Select workflow
• Click "Run workflow"

Creating a Release

# Use the version tagging script
cd ~/guru-connect/scripts
./version-tag.sh patch    # Bump patch version (0.1.0 → 0.1.1)
./version-tag.sh minor    # Bump minor version (0.1.1 → 0.2.0)
./version-tag.sh major    # Bump major version (0.2.0 → 1.0.0)

# Push tag to trigger deployment
git push origin main
git push origin v0.1.1

Manual Deployment

# Deploy from artifact
cd ~/guru-connect/scripts
./deploy.sh /path/to/guruconnect-server-v0.1.0.tar.gz

# Deploy latest
./deploy.sh /home/guru/deployments/artifacts/guruconnect-server-latest.tar.gz

---

Monitoring

View Workflow Runs

https://git.azcomputerguru.com/azcomputerguru/guru-connect/actions

Check Runner Status

# On server
sudo systemctl status gitea-runner

# View logs
sudo journalctl -u gitea-runner -f

# In Gitea
https://git.azcomputerguru.com/admin/actions/runners

View Build Artifacts

Repository > Actions > Workflow Run > Artifacts section

---

Deployment Process

Automated Deployment Flow

1. Tag Creation - Developer creates version tag
2. Workflow Trigger - deploy.yml starts automatically
3. Build - Compiles release binary
4. Package - Creates deployment tarball
5. Transfer - Copies to server (via SSH)
6. Backup - Saves current binary
7. Stop Service - Stops GuruConnect systemd service
8. Deploy - Extracts and installs new binary
9. Start Service - Restarts systemd service
10. Health Check - Verifies server is responding
11. Rollback - Automatic if health check fails

Deployment Locations

Backups:    /home/guru/deployments/backups/
Artifacts:  /home/guru/deployments/artifacts/
Deploy Dir: /home/guru/guru-connect/

Rollback

# List backups
ls -lh /home/guru/deployments/backups/

# Rollback to specific version
cp /home/guru/deployments/backups/guruconnect-server-TIMESTAMP \
   ~/guru-connect/target/x86_64-unknown-linux-gnu/release/guruconnect-server

sudo systemctl restart guruconnect

---

Configuration

Secrets (Required)

Configure in Gitea repository settings:

Repository > Settings > Secrets

Required Secrets:

• SSH_PRIVATE_KEY - SSH key for deployment to 172.16.3.30
• SSH_HOST - Deployment server host (172.16.3.30)
• SSH_USER - Deployment user (guru)

Environment Variables

# In workflow files
env:
  CARGO_TERM_COLOR: always
  RUSTFLAGS: "-D warnings"
  DEPLOY_SERVER: "172.16.3.30"
  DEPLOY_USER: "guru"

---

Troubleshooting

Runner Not Starting

# Check status
sudo systemctl status gitea-runner

# View logs
sudo journalctl -u gitea-runner -n 50

# Verify registration
sudo -u gitea-runner cat /home/gitea-runner/.runner/.runner

# Re-register if needed
sudo -u gitea-runner act_runner register --instance https://git.azcomputerguru.com --token NEW_TOKEN

Workflow Failing

Check logs in Gitea:

1. Go to Actions tab
2. Click on failed run
3. View job logs

Common Issues:

• Missing dependencies → Add to workflow
• Rust version mismatch → Update toolchain version
• Test failures → Fix tests before merging

Deployment Failing

# Check deployment logs on server
cat /home/guru/deployments/deploy-TIMESTAMP.log

# Verify service status
sudo systemctl status guruconnect

# Check GuruConnect logs
sudo journalctl -u guruconnect -n 50

# Manual deployment
cd ~/guru-connect/scripts
./deploy.sh /path/to/package.tar.gz

Artifacts Not Uploading

Check retention settings:

• Build artifacts: 30 days
• Deployment packages: 90 days

Check storage:

# On Gitea server
df -h
du -sh /var/lib/gitea/data/actions_artifacts/

---

Security

Runner Security

• Runner runs as dedicated gitea-runner user
• Limited permissions (no sudo)
• Isolated working directory
• Automatic cleanup after jobs

Deployment Security

• SSH key-based authentication
• Automated backups before deployment
• Health checks before considering deployment successful
• Automatic rollback on failure
• Audit trail in deployment logs

Artifact Security

• Artifacts stored with limited retention
• Accessible only to repository collaborators
• Build artifacts include checksums

---

Performance

Build Times (Estimated)

• Server build: ~2-3 minutes
• Agent build: ~2-3 minutes
• Tests: ~1-2 minutes
• Total pipeline: ~5-8 minutes

Caching

Workflows use cargo cache to speed up builds:

• Cache hit: ~1 minute
• Cache miss: ~2-3 minutes

Concurrent Builds

• Multiple workflows can run in parallel
• Limited by runner capacity (1 runner = 1 job at a time)

---

Maintenance

Runner Updates

# Stop runner
sudo systemctl stop gitea-runner

# Download new version
RUNNER_VERSION="0.2.12"  # Update as needed
cd /tmp
wget https://dl.gitea.com/act_runner/${RUNNER_VERSION}/act_runner-${RUNNER_VERSION}-linux-amd64
sudo mv act_runner-* /usr/local/bin/act_runner
sudo chmod +x /usr/local/bin/act_runner

# Restart runner
sudo systemctl start gitea-runner

Cleanup Old Artifacts

# Manual cleanup on server
rm /home/guru/deployments/backups/guruconnect-server-$(date -d '90 days ago' +%Y%m%d)*
rm /home/guru/deployments/artifacts/guruconnect-server-$(date -d '90 days ago' +%Y%m%d)*

Monitor Disk Usage

# Check deployment directories
du -sh /home/guru/deployments/*

# Check runner cache
du -sh /home/gitea-runner/.cache/act/

---

Best Practices

Branching Strategy

main        - Production-ready code
develop     - Integration branch
feature/*   - Feature branches
hotfix/*    - Emergency fixes

Version Tagging

• Use semantic versioning: vMAJOR.MINOR.PATCH
• MAJOR: Breaking changes
• MINOR: New features (backward compatible)
• PATCH: Bug fixes

Commit Messages

feat: Add new feature
fix: Fix bug
docs: Update documentation
ci: CI/CD changes
chore: Maintenance tasks
test: Add/update tests

Testing Before Merge

1. All tests must pass
2. No clippy warnings
3. Code formatted (cargo fmt)
4. Security audit passed

---

Future Enhancements

Phase 2 Improvements

• Add more test runners (Windows, macOS)
• Implement staging environment
• Add smoke tests post-deployment
• Configure Slack/email notifications
• Add performance benchmarking
• Implement canary deployments
• Add Docker container builds

Monitoring Integration

• Send build metrics to Prometheus
• Grafana dashboard for CI/CD metrics
• Alert on failed deployments
• Track build duration trends

---

Reference Commands

# Runner management
sudo systemctl status gitea-runner
sudo systemctl restart gitea-runner
sudo journalctl -u gitea-runner -f

# Deployment
cd ~/guru-connect/scripts
./deploy.sh <package.tar.gz>

# Version tagging
./version-tag.sh [major|minor|patch]

# Manual build
cd ~/guru-connect
cargo build --release --target x86_64-unknown-linux-gnu

# View artifacts
ls -lh /home/guru/deployments/artifacts/

# View backups
ls -lh /home/guru/deployments/backups/

---

Support

Documentation:

• Gitea Actions: https://docs.gitea.com/usage/actions/overview
• Act Runner: https://gitea.com/gitea/act_runner

Repository:

• https://git.azcomputerguru.com/azcomputerguru/guru-connect

Contact:

• Open issue in Gitea repository

---

Last Updated: 2026-01-18 Phase: 1 Week 3 - CI/CD Automation Status: Ready for Installation