From 00b4c556128db50cd762dd2aaf299082b24f1d56 Mon Sep 17 00:00:00 2001 From: claudi Date: Wed, 28 Jan 2026 13:14:41 +0100 Subject: [PATCH] feat: Add Forgejo CI/CD pipeline for automated builds and releases - Create .forgejo/workflows/build.yml for automated Windows and macOS builds - Trigger on version tags (v1.0.0, v1.0.1, etc.) or manual dispatch - Windows job builds executable with PyInstaller - macOS job builds DMG package - Automatically generate SHA256 checksums for verification - Create release on Forgejo with all artifacts - Add FORGEJO_CI_CD_SETUP.md with complete setup guide - Add CHANGELOG.md for version tracking - Update DEVELOPMENT_PLAN.md with Phase 3.3 details This enables: - Centralized release hub on Forgejo - Automatic distribution of builds - Foundation for Phase 4.1 auto-update system - Checksum-based integrity verification --- .forgejo/workflows/build.yml | 212 +++++++++++++++++++++++++++++++ CHANGELOG.md | 112 +++++++++++++++++ DEVELOPMENT_PLAN.md | 65 ++++++++++ FORGEJO_CI_CD_SETUP.md | 233 +++++++++++++++++++++++++++++++++++ 4 files changed, 622 insertions(+) create mode 100644 .forgejo/workflows/build.yml create mode 100644 CHANGELOG.md create mode 100644 FORGEJO_CI_CD_SETUP.md diff --git a/.forgejo/workflows/build.yml b/.forgejo/workflows/build.yml new file mode 100644 index 0000000..c71a352 --- /dev/null +++ b/.forgejo/workflows/build.yml @@ -0,0 +1,212 @@ +name: Build WebDrop Bridge + +on: + push: + tags: + - 'v*' + workflow_dispatch: + +jobs: + build-windows: + name: Build Windows Executable + runs-on: windows-latest + + steps: + - name: Checkout code + uses: actions/checkout@v3 + + - name: Set up Python + uses: actions/setup-python@v4 + with: + python-version: '3.13' + + - name: Install dependencies + run: | + python -m pip install --upgrade pip + pip install -r requirements-dev.txt + + - name: Run tests + run: | + python -m pytest tests -v --tb=short + + - name: Build Windows executable + run: | + python build/scripts/build_windows.py + + - name: Generate checksum + run: | + $file = "build\dist\windows\WebDropBridge.exe" + $hash = (Get-FileHash -Path $file -Algorithm SHA256).Hash + $hash | Out-File -FilePath "build\dist\windows\WebDropBridge.exe.sha256" -NoNewline + Write-Host "SHA256: $hash" + + - name: Upload Windows artifacts + uses: actions/upload-artifact@v3 + with: + name: windows-build + path: | + build/dist/windows/WebDropBridge.exe + build/dist/windows/WebDropBridge.exe.sha256 + + build-macos: + name: Build macOS DMG + runs-on: macos-latest + + steps: + - name: Checkout code + uses: actions/checkout@v3 + + - name: Set up Python + uses: actions/setup-python@v4 + with: + python-version: '3.13' + + - name: Install dependencies + run: | + python -m pip install --upgrade pip + pip install -r requirements-dev.txt + brew install create-dmg + + - name: Run tests + run: | + python -m pytest tests -v --tb=short + + - name: Build macOS DMG + run: | + bash build/scripts/build_macos.sh + + - name: Generate checksum + run: | + file="build/dist/macos/WebDropBridge.dmg" + hash=$(shasum -a 256 "$file" | awk '{print $1}') + echo "$hash" > "build/dist/macos/WebDropBridge.dmg.sha256" + echo "SHA256: $hash" + + - name: Upload macOS artifacts + uses: actions/upload-artifact@v3 + with: + name: macos-build + path: | + build/dist/macos/WebDropBridge.dmg + build/dist/macos/WebDropBridge.dmg.sha256 + + release: + name: Create Release + needs: [build-windows, build-macos] + runs-on: ubuntu-latest + if: startsWith(github.ref, 'refs/tags/') + + steps: + - name: Checkout code + uses: actions/checkout@v3 + + - name: Download Windows artifacts + uses: actions/download-artifact@v3 + with: + name: windows-build + path: artifacts/windows + + - name: Download macOS artifacts + uses: actions/download-artifact@v3 + with: + name: macos-build + path: artifacts/macos + + - name: Get version from tag + id: get_version + run: | + VERSION=${GITHUB_REF#refs/tags/} + echo "VERSION=$VERSION" >> $GITHUB_OUTPUT + + - name: Create release + uses: actions/create-release@v1 + env: + GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }} + with: + tag_name: ${{ steps.get_version.outputs.VERSION }} + release_name: Release ${{ steps.get_version.outputs.VERSION }} + body: | + # WebDrop Bridge ${{ steps.get_version.outputs.VERSION }} + + ## Downloads + + ### Windows + - **WebDropBridge.exe** - Standalone executable + - SHA256: See WebDropBridge.exe.sha256 + + ### macOS + - **WebDropBridge.dmg** - DMG package + - SHA256: See WebDropBridge.dmg.sha256 + + ## Installation + + ### Windows + 1. Download `WebDropBridge.exe` + 2. Run the executable + 3. No installation required - it's portable + + ### macOS + 1. Download `WebDropBridge.dmg` + 2. Open the DMG file + 3. Drag WebDropBridge.app to Applications + + ## Verification + + To verify the integrity of downloaded files: + + ```bash + # Windows (PowerShell) + $file = "WebDropBridge.exe" + $expected = Get-Content "WebDropBridge.exe.sha256" + $actual = (Get-FileHash -Path $file -Algorithm SHA256).Hash + if ($actual -eq $expected) { Write-Host "OK" } else { Write-Host "MISMATCH" } + + # macOS/Linux + shasum -c WebDropBridge.dmg.sha256 + ``` + + ## What's New + + See [CHANGELOG.md](CHANGELOG.md) for details. + draft: false + prerelease: false + + - name: Upload Windows executable + uses: actions/upload-release-asset@v1 + env: + GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }} + with: + upload_url: ${{ steps.create_release.outputs.upload_url }} + asset_path: artifacts/windows/WebDropBridge.exe + asset_name: WebDropBridge.exe + asset_content_type: application/octet-stream + + - name: Upload Windows checksum + uses: actions/upload-release-asset@v1 + env: + GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }} + with: + upload_url: ${{ steps.create_release.outputs.upload_url }} + asset_path: artifacts/windows/WebDropBridge.exe.sha256 + asset_name: WebDropBridge.exe.sha256 + asset_content_type: text/plain + + - name: Upload macOS DMG + uses: actions/upload-release-asset@v1 + env: + GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }} + with: + upload_url: ${{ steps.create_release.outputs.upload_url }} + asset_path: artifacts/macos/WebDropBridge.dmg + asset_name: WebDropBridge.dmg + asset_content_type: application/octet-stream + + - name: Upload macOS checksum + uses: actions/upload-release-asset@v1 + env: + GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }} + with: + upload_url: ${{ steps.create_release.outputs.upload_url }} + asset_path: artifacts/macos/WebDropBridge.dmg.sha256 + asset_name: WebDropBridge.dmg.sha256 + asset_content_type: text/plain diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..f2e354f --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,112 @@ +# Changelog + +All notable changes to WebDrop Bridge will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [1.0.0] - 2026-01-28 + +### Added +- **Core Features** + - Qt6-based desktop application for web-to-file drag-and-drop + - PySide6 integration with WebEngine for embedded browser + - Path validation and security with whitelist-based access control + - Drag-and-drop event interception and handling + - Real-time drag state monitoring + +- **UI/UX** + - Professional main window with toolbar navigation + - Restricted web view with URL whitelist enforcement + - Kiosk-mode support (restricted browsing) + - Beautiful default welcome page for unconfigured instances + - Responsive layout with proper window management + +- **Configuration** + - Environment-based configuration system (.env file support) + - Configurable allowed root directories for file access + - URL whitelist with wildcard support (*.example.com) + - Window size and appearance settings + - Logging level and output control + +- **Logging & Monitoring** + - Structured logging with INFO, DEBUG, ERROR levels + - Optional file-based logging + - Comprehensive error messages and diagnostics + - Application startup and shutdown logging + +- **Build & Distribution** + - PyInstaller configuration for Windows and macOS + - Standalone executable generation (195.7 MB for Windows) + - Dependency bundling (PySide6, Qt6, Chromium) + - Resource embedding (webapp, icons, stylesheets) + - Cross-platform support (Windows .exe, macOS .dmg) + +- **Testing & Quality** + - 99 unit and integration tests + - 84% code coverage + - Ruff linting and Black code formatting + - mypy type checking + - Comprehensive test fixtures and mocking + +- **CI/CD** + - Forgejo Actions workflow for automated builds + - Windows executable build on tag push + - macOS DMG build on tag push + - SHA256 checksum generation + - Automatic release creation on Forgejo + +- **Documentation** + - Comprehensive API documentation with docstrings + - Architecture documentation (ARCHITECTURE.md) + - Development plan (DEVELOPMENT_PLAN.md) + - Setup and quickstart guides + - Contributing guidelines + +### Technical Details +- **Language**: Python 3.13 +- **Framework**: PySide6 6.10.1 (Qt6) +- **Web Engine**: Qt6 WebEngine with Chromium +- **Build Tool**: PyInstaller 6.18.0 +- **Testing**: pytest with coverage +- **Linting**: Ruff + Black + +### Known Limitations +- Requires .NET or macOS for native integration (future enhancement) +- No automatic updater yet (Phase 4.1) +- No multi-window support (Phase 4.2) +- Requires configuration for custom web applications + +## [Unreleased] + +### Planned for Phase 4 +- **Auto-Update System** with Forgejo integration +- **Enhanced Logging** with monitoring dashboard +- **Advanced Configuration** UI +- **User Documentation** and tutorials +- **Code Signing** for Windows MSI +- **Apple Notarization** for macOS DMG + +--- + +## Version Numbering + +- **MAJOR**: Significant feature additions or breaking changes +- **MINOR**: New features, backward compatible +- **PATCH**: Bug fixes, improvements + +Example: `1.0.0` = Version 1, Release 0, Patch 0 + +## Release Process + +1. Update version in `src/webdrop_bridge/config.py` (APP_VERSION) +2. Update CHANGELOG.md with new features/fixes +3. Commit: `git commit -m "chore: Bump version to X.Y.Z"` +4. Tag: `git tag -a vX.Y.Z -m "Release version X.Y.Z"` +5. Push: `git push upstream vX.Y.Z` +6. Forgejo Actions automatically builds and creates release + +--- + +**Current Version**: 1.0.0 (Released 2026-01-28) +**Next Version**: 1.1.0 (Planned with auto-update system) diff --git a/DEVELOPMENT_PLAN.md b/DEVELOPMENT_PLAN.md index a93f390..36594fc 100644 --- a/DEVELOPMENT_PLAN.md +++ b/DEVELOPMENT_PLAN.md @@ -634,6 +634,71 @@ export APPLE_TEAM_ID="XXXXXXXXXX" --- +### 3.3 Forgejo CI/CD Pipeline + +**Workflow File** (`.forgejo/workflows/build.yml`): +- Automated builds on tag push (v1.0.0, v1.0.1, etc.) +- Windows executable build (windows-latest runner) +- macOS DMG build (macos-latest runner) +- SHA256 checksum generation +- Release creation with artifacts +- Artifact upload to Forgejo releases + +**Features:** +- ✅ Trigger on version tags +- ✅ Manual workflow dispatch option +- ✅ Multi-platform parallel builds +- ✅ Automatic release generation +- ✅ Checksum verification support +- ✅ Integration with auto-update system (Phase 4.1) + +**Usage:** +```bash +# Create a release +git tag -a v1.0.0 -m "Release version 1.0.0" +git push upstream v1.0.0 + +# Forgejo Actions automatically: +# 1. Builds Windows executable +# 2. Builds macOS DMG +# 3. Generates checksums +# 4. Creates release with artifacts +``` + +**Requirements:** +- Forgejo instance with Actions enabled +- Windows runner (for Windows builds) +- macOS runner (for macOS builds) +- `GITEA_TOKEN` secret configured in repository + +**Release Location:** +``` +https://git.him-tools.de/HIM-public/webdrop-bridge/releases/vX.Y.Z +├── WebDropBridge.exe +├── WebDropBridge.exe.sha256 +├── WebDropBridge.dmg +└── WebDropBridge.dmg.sha256 +``` + +**Setup Guide:** +See [FORGEJO_CI_CD_SETUP.md](FORGEJO_CI_CD_SETUP.md) for: +- Runner installation and configuration +- Secret setup (GITEA_TOKEN) +- Troubleshooting +- Integration with UpdateManager (Phase 4.1) + +**Acceptance Criteria:** +- [x] Workflow file created and committed +- [ ] Forgejo runners configured (Windows + macOS) +- [ ] GITEA_TOKEN secret added +- [ ] Test run: Tag v0.0.1 triggers builds +- [ ] Release appears on Forgejo with artifacts +- [ ] Checksums verify successfully + +**Status**: ✅ Workflow created | ⏳ Runners needed + +--- + ## Phase 4: Professional Features & Auto-Update (Weeks 9-12) ### 4.1 Auto-Update System with Forgejo Integration diff --git a/FORGEJO_CI_CD_SETUP.md b/FORGEJO_CI_CD_SETUP.md new file mode 100644 index 0000000..2ce906f --- /dev/null +++ b/FORGEJO_CI_CD_SETUP.md @@ -0,0 +1,233 @@ +# Forgejo CI/CD Setup Guide + +This project uses **Forgejo Actions** to automatically build and release WebDrop Bridge for Windows and macOS. + +## Architecture + +``` +┌─────────────────┐ +│ Forgejo Repo │ +│ (Main Hub) │ +└────────┬────────┘ + │ + ├─→ Tag pushed (v1.0.0) + │ + ├─→ Forgejo Actions triggers + │ ├─ Build Windows (Windows runner) + │ ├─ Build macOS (macOS runner) + │ └─ Create Release + │ + └─→ Release created with: + ├─ WebDropBridge.exe + SHA256 + └─ WebDropBridge.dmg + SHA256 +``` + +## Setup Requirements + +### 1. Forgejo Instance Configuration + +Your Forgejo instance needs: +- **Forgejo Actions enabled** (Check: Settings → Actions) +- **Runners configured** for: + - Windows (to build Windows executables) + - macOS (to build DMG packages) + +### 2. Required Secrets + +Add these secrets to your Forgejo repository (Settings → Secrets): + +#### `GITEA_TOKEN` +Personal access token with permissions: +- `api` - API access +- `write:repository` - Write to repository (for creating releases) + +**How to create:** +1. Go to `https://git.him-tools.de/user/settings/applications` +2. Click "Generate New Token" +3. Name: `CI_CD_TOKEN` +4. Scopes: Select `api` and `write:repository` +5. Copy token +6. In repo settings: Add secret `GITEA_TOKEN` = `` + +### 3. Runner Setup + +#### Windows Runner +```powershell +# Install Forgejo runner on Windows machine +cd C:\forgejo-runner +.\forgejo-runner.exe register --no-interactive \ + --forgejo-instance-url https://git.him-tools.de \ + --registration-token \ + --runner-name windows-runner \ + --runner-group default \ + --labels windows,powershell + +# Start runner +.\forgejo-runner.exe daemon +``` + +#### macOS Runner +```bash +# Install Forgejo runner on macOS +mkdir -p ~/forgejo-runner && cd ~/forgejo-runner +curl -L https://github.com/go-gitea/act_runner/releases/download/v0.5.5/act_runner-0.5.5-darwin-x86_64.tar.gz | tar xz + +./act_runner register --no-interactive \ + --forgejo-instance-url https://git.him-tools.de \ + --registration-token \ + --runner-name macos-runner \ + --runner-group default \ + --labels macos + +# Start runner +./act_runner daemon +``` + +## Workflow Details + +### `.forgejo/workflows/build.yml` + +**Triggered on:** +- Tag push matching `v*` (e.g., `v1.0.0`, `v1.0.1`) +- Manual trigger via "Run workflow" button + +**Jobs:** + +1. **build-windows** + - Runs on: `windows-latest` (requires Windows runner) + - Steps: + - Checkout code + - Set up Python 3.13 + - Install dependencies from `requirements-dev.txt` + - Run tests + - Build Windows executable + - Generate SHA256 checksum + - Upload artifacts + +2. **build-macos** + - Runs on: `macos-latest` (requires macOS runner) + - Steps: + - Checkout code + - Set up Python 3.13 + - Install dependencies + `create-dmg` tool + - Run tests + - Build macOS DMG + - Generate SHA256 checksum + - Upload artifacts + +3. **release** + - Runs on: `ubuntu-latest` (built-in) + - Waits for: Windows and macOS builds + - Only triggers on: Tag push + - Steps: + - Download artifacts from both builds + - Create GitHub-compatible release + - Upload executables and checksums + - Generate release notes + +## Usage + +### Automatic Release + +1. **Create a tag** from main branch: + ```bash + git tag -a v1.0.0 -m "Release version 1.0.0" + git push upstream v1.0.0 + ``` + +2. **Forgejo Actions automatically**: + - Builds Windows executable + - Builds macOS DMG + - Creates release with all artifacts + - Generates checksums for verification + +3. **Download from**: + - `https://git.him-tools.de/HIM-public/webdrop-bridge/releases/tag/v1.0.0` + +### Manual Trigger (for debugging) + +1. Go to your Forgejo repo +2. Click "Actions" tab +3. Select "Build WebDrop Bridge" workflow +4. Click "Run workflow" +5. Select branch and click "Run" + +## Environment Variables + +The workflow uses these from your repository: + +| Variable | Source | Purpose | +|----------|--------|---------| +| `GITEA_TOKEN` | Repository Secret | Authentication for creating releases | +| Python version | Hardcoded: `3.13` | Build environment | +| PyInstaller | `requirements-dev.txt` | Build tool | + +## Artifacts & Downloads + +Once released, users can download from: + +``` +https://git.him-tools.de/HIM-public/webdrop-bridge/releases/v1.0.0 +├── WebDropBridge.exe (Windows executable) +├── WebDropBridge.exe.sha256 (Windows checksum) +├── WebDropBridge.dmg (macOS package) +└── WebDropBridge.dmg.sha256 (macOS checksum) +``` + +## Verification + +### On Windows +```powershell +$file = "WebDropBridge.exe" +$expected = Get-Content "WebDropBridge.exe.sha256" +$actual = (Get-FileHash -Path $file -Algorithm SHA256).Hash +if ($actual -eq $expected) { + Write-Host "Checksum OK" -ForegroundColor Green +} else { + Write-Host "Checksum FAILED" -ForegroundColor Red +} +``` + +### On macOS/Linux +```bash +shasum -c WebDropBridge.dmg.sha256 +``` + +## Troubleshooting + +### Workflow not triggering + +- Verify tag format: must start with `v` (e.g., `v1.0.0`) +- Check Forgejo Actions is enabled in repo settings +- Verify `GITEA_TOKEN` secret exists and is valid + +### Build fails on runner + +- Check runner is online: Admin → Runners +- Verify Python 3.13 is installed on runner +- Check logs in Actions tab → Workflow run details + +### Release creation fails + +- Verify `GITEA_TOKEN` has `write:repository` scope +- Check token hasn't expired +- Verify runners completed successfully before release job + +## Next Steps + +1. Set up Forgejo runners on Windows and macOS machines +2. Add `GITEA_TOKEN` secret to repository +3. Test with `git tag v0.0.1 && git push upstream v0.0.1` +4. Verify release appears at `releases/v0.0.1` + +## Integration with Auto-Update System + +The Forgejo releases created by this workflow will be used by: +- **Phase 4.1 UpdateManager**: Queries `https://git.him-tools.de/api/v1/repos/HIM-public/webdrop-bridge/releases/latest` +- **Menu Option**: "Check for Updates" downloads installer from release assets +- **Auto-Install**: Extracts and installs new version + +--- + +**Status**: Ready to deploy (pending runner setup) +**Last Updated**: January 2026