Kizuna Help

Appearance

Self-hosted runners let you run CI/CD jobs on your own machines. Use for custom hardware, private networks, or specific environments.

Why Self-Hosted? ​

  • Custom hardware — GPUs, specialized CPUs
  • Private network — Access internal resources
  • Larger storage — Bigger disk than hosted
  • Specific OS — Custom Linux, Windows, macOS
  • Compliance — Data stays on-premise

Installing Runners ​

System Requirements ​

ResourceMinimumRecommended
CPU2 cores4+ cores
RAM4 GB8+ GB
Disk20 GB100+ GB
NetworkOutbound HTTPSLow latency

Download ​

bash
# Create directory
mkdir -p /opt/kizuna-runner
cd /opt/kizuna-runner

# Download latest
curl -O https://kizuna.example.com/runner/download/latest

# Extract
tar xzf kizuna-runner-linux-x64.tar.gz

Configure ​

Get token from repository settings:

  1. Go to Settings → CI/CD → Runners
  2. Click New Self-Hosted Runner
  3. Copy registration token

Configure runner:

bash
./kizuna-runner configure \
  --url https://kizuna.example.com/org/repo \
  --token REGISTRATION_TOKEN \
  --name "my-runner" \
  --labels "gpu,self-hosted"

Install as Service ​

Linux (systemd) ​

bash
sudo ./kizuna-runner install
sudo systemctl start kizuna-runner
sudo systemctl enable kizuna-runner

macOS (launchd) ​

bash
sudo ./kizuna-runner install
sudo launchctl load /Library/LaunchDaemons/kizuna.runner.plist

Windows ​

powershell
.\kizuna-runner.exe install
Start-Service kizuna-runner

Manual Start ​

bash
# Run interactively
./kizuna-runner run

Runner Labels ​

Labels route jobs to specific runners:

Assign Labels ​

bash
./kizuna-runner configure \
  --labels "gpu,cuda,linux"

Use Labels in Workflow ​

yaml
jobs:
  train-model:
    runs-on: [self-hosted, gpu, cuda]
    steps:
      - run: nvidia-smi
      - run: python train.py

Common Labels ​

LabelUse Case
self-hostedAny self-hosted runner
linuxLinux OS
windowsWindows OS
macosmacOS
gpuGPU available
arm64ARM architecture
productionProduction deployment

Runner Groups ​

Organize runners into groups:

bash
# Create group via API
curl -X POST /api/v1/runner-groups \
  -d '{
    "name": "gpu-runners",
    "visibility": "selected",
    "repositories": ["org/ml-project"]
  }'

Assign runner to group:

bash
./kizuna-runner configure \
  --group "gpu-runners"

Security ​

Job Isolation ​

Each job runs in clean environment:

  • Fresh working directory
  • Isolated network (optional)
  • No access to previous job state

Network Security ​

Restrict runner network:

bash
# Firewall rules
sudo ufw default deny outgoing
sudo ufw allow out to kizuna.example.com
sudo ufw allow out to npm registry
sudo ufw enable

Secrets ​

Runners access repository secrets. Protect them:

  • Limit runner access to specific repos
  • Use runner groups with visibility controls
  • Rotate credentials regularly

Monitoring ​

Runner Status ​

View in Settings → CI/CD → Runners:

my-runner
├── Status: Online
├── Last seen: 2 minutes ago
├── Jobs: 47 completed, 0 failed
└── Labels: [linux, gpu]

Logs ​

bash
# View runner logs
journalctl -u kizuna-runner -f

# Or from runner directory
./kizuna-runner logs

Metrics ​

bash
curl /api/v1/runners/my-runner/metrics

Returns:

json
{
  "status": "online",
  "jobs_completed": 47,
  "jobs_failed": 0,
  "average_job_duration": 245,
  "disk_usage_percent": 65,
  "cpu_percent": 23
}

Maintenance ​

Update Runner ​

bash
# Stop service
sudo systemctl stop kizuna-runner

# Download new version
curl -O https://kizuna.example.com/runner/download/latest
tar xzf kizuna-runner-linux-x64.tar.gz

# Start service
sudo systemctl start kizuna-runner

Clean Working Directory ​

bash
# Remove old job directories
./kizuna-runner cleanup

# Or manually
rm -rf /opt/kizuna-runner/_work/*

Remove Runner ​

bash
# Unregister
./kizuna-runner remove --token REGISTRATION_TOKEN

# Remove service
sudo systemctl disable kizuna-runner
sudo rm /etc/systemd/system/kizuna-runner.service

Troubleshooting ​

Runner Won't Start ​

Check:

  1. Token is valid
  2. URL is correct
  3. Network connectivity
  4. Permissions on runner directory
bash
# Test connectivity
curl https://kizuna.example.com/api/v1/health

# Check logs
./kizuna-runner logs

Jobs Not Running ​

Check:

  1. Runner is online
  2. Labels match workflow
  3. Runner has access to repository

Out of Disk Space ​

bash
# Clean up
./kizuna-runner cleanup

# Or set auto-cleanup
./kizuna-runner configure --auto-cleanup

Network Timeouts ​

Increase timeouts in configuration:

bash
./kizuna-runner configure \
  --http-timeout 60 \
  --job-timeout 3600

Summary ​

Self-hosted runners provide:

  • Custom environments — Your hardware, your OS
  • Private resources — Internal network access
  • Scalability — Add runners as needed
  • Security — Data stays in your control

They're essential for specialized CI/CD needs.