Add GitHub Actions workflow for KVM-based testing of debi.sh

.github/workflows/README.md

@@ -0,0 +1,218 @@
+# GitHub Actions Workflow for Testing debi.sh
+
+## Overview
+
+This workflow tests the Debian Network Reinstall Script (`debi.sh`) using KVM virtualization in GitHub Actions. It validates that the script correctly prepares a system for Debian installation, performs the actual installation, and verifies the newly installed system.
+
+## Test Matrix
+
+The workflow uses a semantic matrix strategy to test ~15 different configurations across:
+
+- **Debian Versions**: 10 (Buster), 11 (Bullseye), 12 (Bookworm)
+- **Mirrors**: Default, USTC (China), Cloudflare
+- **Network Interface Naming**: Standard (`ethx`) or predictable names
+- **User Account**: `root` or `debian`
+- **Network Console**: Always enabled for remote installation monitoring
+
+**Key combinations tested:**
+- Debian 10 with default mirror (baseline)
+- Debian 11 with all mirrors and both naming schemes
+- Debian 12 with all mirrors and various user configurations
+
+**Base Image**: All tests use Debian 11 (Bullseye) cloud image as the starting point, regardless of target version.
+
+## How It Works
+
+### 1. Environment Setup
+- Enables KVM support on GitHub Actions runner
+- Caches APT packages for faster subsequent runs
+- Installs QEMU and related tools (qemu-kvm, cloud-utils, sshpass, etc.)
+
+### 2. Base Image Caching
+- Downloads Debian 11 cloud image (only once, then cached)
+- Reuses cached image across all matrix jobs
+- Significantly speeds up workflow execution
+
+### 3. VM Preparation
+- Creates a copy-on-write disk image from the cached base image
+- Generates cloud-init configuration for initial VM setup
+- Configures root SSH access with password `rootpass123`
+
+### 4. VM Execution
+- Starts QEMU VM with KVM acceleration
+- Waits for SSH to become available
+- Uploads `debi.sh` script to the VM
+
+### 5. Script Testing
+- **Builds arguments dynamically** from matrix parameters:
+  - `--version` from `matrix.version`
+  - `--ustc` or `--cloudflare` from `matrix.mirror`
+  - `--ethx` from `matrix.ethx`
+  - `--network-console` (always enabled)
+  - `--user` and `--password` from `matrix.user`
+- Executes `debi.sh` with built arguments
+- Captures output for debugging
+
+### 6. Installation Validation
+The workflow validates that the script:
+- Successfully downloads Debian installer components to `/boot/debian-*/`
+- Creates the required `linux` and `initrd.gz` files
+- Updates GRUB configuration with Debian Installer entry
+- Sets GRUB default to boot into the installer
+
+### 7. Full Installation Test
+After validation, the workflow:
+- Reboots the VM to start the Debian installer
+- Waits for the installation to complete (up to 30 minutes)
+- Polls for SSH availability with the **new password** (`newpass123`)
+- Verifies the newly installed system
+
+### 7. Success Criteria
+
+A test passes if:
+- ✓ Script executes without critical errors
+- ✓ Installer files exist in `/boot/debian-*/`
+- ✓ GRUB configuration contains "Debian Installer" entry
+- ✓ VM successfully reboots into installer
+- ✓ Installation completes automatically
+- ✓ New system boots and is accessible via SSH with new credentials
+
+## Running the Tests
+
+### Automatic Execution
+Tests run automatically on:
+- Push to `master` or `main` branch
+- Pull requests targeting `master` or `main`
+
+### Manual Execution
+You can manually trigger the workflow:
+1. Go to Actions tab in GitHub
+2. Select "Test Debian Installation Script"
+3. Click "Run workflow"
+
+## Test Artifacts
+
+Each test run uploads:
+- `debi-output.log` - Complete output from script execution
+- `serial.log` - VM serial console log
+
+Access artifacts from the workflow run summary page.
+
+## Interpreting Results
+
+### ✅ Success
+- All validation checks pass
+- New system is accessible with new credentials
+- Green checkmark in GitHub Actions UI
+
+### ❌ Failure
+Common failure scenarios and debugging:
+
+1. **SSH connection timeout (old credentials)**
+   - Check serial console log
+   - Verify cloud-init configuration
+
+2. **Installer files not downloaded**
+   - Review debi-output.log
+   - Check network connectivity
+   - Verify mirror availability
+
+3. **GRUB update failed**
+   - Check for GRUB installation issues
+   - Verify disk partitioning
+
+4. **Installation timeout**
+   - Installation may take longer than expected
+   - Check serial console for installer progress
+   - Verify network connectivity to mirrors
+
+5. **Cannot connect with new credentials**
+   - Installation may have failed
+   - Check serial console for installation errors
+   - Verify preseed configuration
+
+## Password Strategy
+
+The workflow uses two different passwords to verify installation success:
+
+| Phase | User | Password | Purpose |
+|-------|------|----------|---------|
+| Initial VM (cloud-init) | root | `rootpass123` | Access the base system to run debi.sh |
+| New System (installed) | root/debian | `newpass123` | Verify the new system was installed |
+
+If SSH connects with `newpass123`, it proves the new Debian system was installed successfully.
+
+## Limitations
+
+This workflow tests the complete installation process:
+- ✓ Script argument parsing
+- ✓ Installer file downloads
+- ✓ GRUB configuration updates
+- ✓ Reboot into installer
+- ✓ Unattended installation
+- ✓ New system verification
+
+Note: Full installation takes 10-30 minutes per test case.
+
+## Performance Optimization
+
+The workflow includes several optimizations:
+
+1. **APT Package Caching**: Dependencies are cached across workflow runs
+2. **Base Image Caching**: Debian 11 cloud image is downloaded once and reused
+3. **Single Base Image**: All tests use Debian 11 as starting point (smaller cache footprint)
+4. **Matrix Exclusions**: Intelligent filtering reduces redundant test combinations
+
+## Adding New Test Cases
+
+The workflow uses a semantic matrix. To modify test coverage:
+
+**Add a new Debian version:**
+```yaml
+matrix:
+  version: [10, 11, 12, 13]  # Add 13
+```
+
+**Test with a new mirror:**
+```yaml
+matrix:
+  mirror: ['default', 'ustc', 'cloudflare', 'tuna']  # Add tuna
+```
+
+**Modify exclusions:**
+```yaml
+exclude:
+  # Add exclusions to prevent unwanted combinations
+  - version: 13
+    mirror: 'ustc'  # Skip USTC for Debian 13
+```
+
+The workflow automatically builds command-line arguments from matrix parameters.
+
+## Troubleshooting
+
+### KVM not available
+If KVM is not available, the workflow will fail. GitHub Actions runners support KVM, but some self-hosted runners may not.
+
+### Network timeouts
+If downloads fail, consider:
+- Adding retry logic
+- Using alternative mirrors
+- Checking GitHub Actions network restrictions
+
+### VM boot failures
+Check the serial console log artifact for kernel messages and boot errors.
+
+### Installation hangs
+If the installation takes too long:
+- Check the serial console for progress
+- Verify mirror connectivity
+- Consider using a faster mirror (USTC, Cloudflare)
+
+### Cache issues
+To clear caches and force fresh downloads:
+1. Go to Actions tab → Caches
+2. Delete relevant cache entries
+3. Re-run the workflow
+
+Cache keys are based on workflow file hash, so modifying the workflow automatically invalidates caches.