150 lines
4.0 KiB
Markdown
150 lines
4.0 KiB
Markdown
# Release Workflow Documentation
|
|
|
|
This document describes the automated release workflow for the Android File Handler ADB tool.
|
|
|
|
## Overview
|
|
|
|
The release workflow automatically builds and publishes native binaries for multiple platforms when a new tag is pushed. It creates:
|
|
|
|
- **Linux Binary**: Native executable for Linux systems
|
|
- **Windows Binary**: Native executable (.exe) for Windows systems
|
|
- **DEB Packages**: Debian/Ubuntu packages (.deb)
|
|
- **RPM Packages**: Red Hat/Fedora packages (.rpm)
|
|
- **AUR Package**: Arch User Repository submission
|
|
|
|
## Triggering a Release
|
|
|
|
1. **Create and push a tag**:
|
|
```bash
|
|
git tag v1.0.0
|
|
git push origin v1.0.0
|
|
```
|
|
|
|
2. **Manual workflow dispatch** (optional):
|
|
- Go to Actions tab in GitHub
|
|
- Select "Release" workflow
|
|
- Click "Run workflow"
|
|
- Optionally enable "Dry Run" mode
|
|
|
|
## Required Repository Secrets
|
|
|
|
For AUR publishing, configure these secrets in repository settings:
|
|
|
|
| Secret Name | Description |
|
|
|-------------|-------------|
|
|
| `AUR_SSH_PRIVATE_KEY` | SSH private key for AUR publishing |
|
|
| `AUR_USER_NAME` | Git username for AUR commits |
|
|
| `AUR_USER_EMAIL` | Git email for AUR commits |
|
|
|
|
## Workflow Features
|
|
|
|
### Multi-Platform Builds
|
|
- **Linux**: Built on Ubuntu with PyInstaller
|
|
- **Windows**: Cross-compiled on Ubuntu with PyInstaller
|
|
- **Arch Linux**: Built in native Arch container
|
|
|
|
### Security Features
|
|
- SHA256 checksums for all release assets
|
|
- Comprehensive file validation
|
|
- Binary integrity verification
|
|
|
|
### Package Management
|
|
- **DEB**: Created with `fpm` for APT repositories
|
|
- **RPM**: Created with `fpm` for DNF/YUM repositories
|
|
- **AUR**: Automated PKGBUILD generation and submission
|
|
|
|
### Quality Assurance
|
|
- Binary size validation (must be > 1MB)
|
|
- File existence verification
|
|
- Build success validation
|
|
- Comprehensive error reporting
|
|
|
|
## Dry Run Mode
|
|
|
|
Enable dry run mode to test the workflow without publishing:
|
|
|
|
1. Go to Actions → Release workflow
|
|
2. Click "Run workflow"
|
|
3. Check "Enable dry run mode"
|
|
4. Click "Run workflow"
|
|
|
|
In dry run mode:
|
|
- All builds are executed
|
|
- Validation is performed
|
|
- No actual publishing occurs
|
|
- Assets are still created for review
|
|
|
|
## Build Outputs
|
|
|
|
### Release Assets
|
|
All builds create files in the `release-assets/` directory:
|
|
|
|
```
|
|
release-assets/
|
|
├── android-file-handler # Linux binary
|
|
├── android-file-handler.exe # Windows binary
|
|
├── android-file-handler_*.deb # Debian packages
|
|
├── android-file-handler-*.rpm # RPM packages
|
|
└── SHA256SUMS # Checksums file
|
|
```
|
|
|
|
### Validation Reports
|
|
The workflow provides comprehensive build quality assessment:
|
|
|
|
- ✅/❌ Binary creation success
|
|
- ✅/❌ Package count validation
|
|
- 📊 File size verification
|
|
- 🔒 SHA256 checksum generation
|
|
|
|
## Troubleshooting
|
|
|
|
### Common Issues
|
|
|
|
1. **No release assets created**
|
|
- Check artifact download step
|
|
- Verify PyInstaller execution
|
|
- Review build logs for errors
|
|
|
|
2. **Binary validation fails**
|
|
- Ensure binaries are > 1MB
|
|
- Check file permissions
|
|
- Verify executable format
|
|
|
|
3. **AUR publishing fails**
|
|
- Verify SSH key configuration
|
|
- Check AUR credentials
|
|
- Ensure PKGBUILD syntax
|
|
|
|
### Debug Steps
|
|
|
|
1. **Enable dry run mode** to test without publishing
|
|
2. **Check build logs** for specific error messages
|
|
3. **Verify dependencies** in pyproject.toml
|
|
4. **Test locally** with PyInstaller before pushing
|
|
|
|
## Maintenance
|
|
|
|
### Updating the Workflow
|
|
|
|
When modifying the workflow:
|
|
|
|
1. Test changes in a fork first
|
|
2. Use dry run mode for validation
|
|
3. Monitor build quality metrics
|
|
4. Update this documentation
|
|
|
|
### Version Requirements
|
|
|
|
- Python 3.8+ (specified in workflow)
|
|
- Poetry for dependency management
|
|
- ADB platform tools (bundled)
|
|
|
|
## Security Considerations
|
|
|
|
- SSH keys are properly secured and permissioned
|
|
- Checksums provide integrity verification
|
|
- Secrets are never logged or exposed
|
|
- Build artifacts are validated before release
|
|
|
|
This workflow ensures reliable, secure, and comprehensive multi-platform releases for the Android File Handler ADB tool.
|