mirror of https://github.com/bohanyang/debi
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
218 lines
6.9 KiB
218 lines
6.9 KiB
# 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.
|
|
|