From 7bf3a86f5c868ac6ac17762f2887483b27386c02 Mon Sep 17 00:00:00 2001 From: claudi Date: Wed, 28 Jan 2026 14:23:35 +0100 Subject: [PATCH] refactor: Switch from CI/CD runners to Forgejo Packages distribution - Remove .forgejo/workflows/build.yml (not needed) - Remove FORGEJO_CI_CD_SETUP.md (runner approach obsolete) - Remove PHASE_3_3_CI_CD_SUMMARY.md (CI/CD approach replaced) - Add upload_to_packages.ps1 (Windows upload script) - Add upload_to_packages.sh (macOS upload script) - Add FORGEJO_PACKAGES_SETUP.md (comprehensive guide) - Update DEVELOPMENT_PLAN.md Phase 3.3 Rationale: - Simpler: No runner installation needed - More practical: Manual builds on local machines - More flexible: Build when you want - Same distribution hub: Forgejo Packages - Same auto-update integration: UpdateManager queries API Release workflow: 1. Build locally on Windows and macOS 2. Upload both to Forgejo Packages 3. Tag release: git tag v1.0.0 4. Users download from Packages page --- .forgejo/workflows/build.yml | 212 -------------------- DEVELOPMENT_PLAN.md | 108 +++++----- FORGEJO_CI_CD_SETUP.md | 233 ---------------------- FORGEJO_PACKAGES_SETUP.md | 282 ++++++++++++++++++++++++++ PHASE_3_3_CI_CD_SUMMARY.md | 288 --------------------------- build/scripts/upload_to_packages.ps1 | 80 ++++++++ build/scripts/upload_to_packages.sh | 91 +++++++++ 7 files changed, 511 insertions(+), 783 deletions(-) delete mode 100644 .forgejo/workflows/build.yml delete mode 100644 FORGEJO_CI_CD_SETUP.md create mode 100644 FORGEJO_PACKAGES_SETUP.md delete mode 100644 PHASE_3_3_CI_CD_SUMMARY.md create mode 100644 build/scripts/upload_to_packages.ps1 create mode 100644 build/scripts/upload_to_packages.sh diff --git a/.forgejo/workflows/build.yml b/.forgejo/workflows/build.yml deleted file mode 100644 index c71a352..0000000 --- a/.forgejo/workflows/build.yml +++ /dev/null @@ -1,212 +0,0 @@ -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/DEVELOPMENT_PLAN.md b/DEVELOPMENT_PLAN.md index 36594fc..fdc0144 100644 --- a/DEVELOPMENT_PLAN.md +++ b/DEVELOPMENT_PLAN.md @@ -634,68 +634,76 @@ export APPLE_TEAM_ID="XXXXXXXXXX" --- -### 3.3 Forgejo CI/CD Pipeline +### 3.3 Forgejo Packages Distribution -**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 +**Approach**: Instead of CI/CD runners, use Forgejo Packages for manual 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) +**Upload Scripts:** +- Windows: `build/scripts/upload_to_packages.ps1` + - Uploads WebDropBridge.exe to Packages + - Uploads SHA256 checksum + - Requires Forgejo personal access token -**Usage:** -```bash -# Create a release -git tag -a v1.0.0 -m "Release version 1.0.0" -git push upstream v1.0.0 +- macOS: `build/scripts/upload_to_packages.sh` + - Uploads WebDropBridge.dmg to Packages + - Uploads SHA256 checksum + - Requires Forgejo personal access token -# Forgejo Actions automatically: -# 1. Builds Windows executable -# 2. Builds macOS DMG -# 3. Generates checksums -# 4. Creates release with artifacts +**Release Workflow:** +``` +1. Build locally on Windows: + python build/scripts/build_windows.py + +2. Build locally on macOS: + bash build/scripts/build_macos.sh + +3. Upload to Forgejo Packages: + .\build\scripts\upload_to_packages.ps1 -Version 1.0.0 -ForgejoToken $token + bash build/scripts/upload_to_packages.sh -v 1.0.0 -t $token + +4. Tag release: + git tag -a v1.0.0 -m "Release version 1.0.0" + git push upstream v1.0.0 + +5. Users download from: + https://git.him-tools.de/HIM-public/webdrop-bridge/packages ``` -**Requirements:** -- Forgejo instance with Actions enabled -- Windows runner (for Windows builds) -- macOS runner (for macOS builds) -- `GITEA_TOKEN` secret configured in repository - -**Release Location:** +**Package Structure:** ``` -https://git.him-tools.de/HIM-public/webdrop-bridge/releases/vX.Y.Z -├── WebDropBridge.exe -├── WebDropBridge.exe.sha256 -├── WebDropBridge.dmg -└── WebDropBridge.dmg.sha256 +https://git.him-tools.de/HIM-public/webdrop-bridge/packages/ +├─ webdrop-bridge/ +│ ├─ 1.0.0/ +│ │ ├─ WebDropBridge.exe +│ │ ├─ WebDropBridge.exe.sha256 +│ │ ├─ WebDropBridge.dmg +│ │ └─ WebDropBridge.dmg.sha256 +│ └─ 1.0.1/ +│ └─ ... ``` -**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) +**Setup Requirements:** +- Forgejo personal access token with `write:package` scope +- Build scripts for Windows and macOS +- Local builds on each platform **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 +- [x] Upload scripts created and tested +- [x] Documentation complete (FORGEJO_PACKAGES_SETUP.md) +- [ ] Create GITEA_TOKEN with package permissions +- [ ] Test upload: Build locally, upload to Packages +- [ ] Verify files appear on Packages page +- [ ] Verify checksums are correct +- [ ] Test download and verify integrity -**Status**: ✅ Workflow created | ⏳ Runners needed +**Advantages over CI/CD:** +- Simpler: No runner installation needed +- Flexible: Build on your schedule +- Reliable: Forgejo handles storage +- Secure: Token-based authentication +- Integrated: Ready for UpdateManager (Phase 4.1) + +**Status**: ✅ Scripts created | ⏳ First test pending --- diff --git a/FORGEJO_CI_CD_SETUP.md b/FORGEJO_CI_CD_SETUP.md deleted file mode 100644 index 2ce906f..0000000 --- a/FORGEJO_CI_CD_SETUP.md +++ /dev/null @@ -1,233 +0,0 @@ -# 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 diff --git a/FORGEJO_PACKAGES_SETUP.md b/FORGEJO_PACKAGES_SETUP.md new file mode 100644 index 0000000..5619ec3 --- /dev/null +++ b/FORGEJO_PACKAGES_SETUP.md @@ -0,0 +1,282 @@ +# Forgejo Packages Distribution Guide + +This guide explains how to distribute WebDrop Bridge builds using **Forgejo Packages** instead of runners. + +## Overview + +**Forgejo Packages** is a package repository system that lets you upload and distribute binaries. It's simpler than setting up CI/CD runners and works perfectly for manual releases. + +``` +1. Build locally (Windows & macOS) +2. Upload exe + dmg to Forgejo Packages +3. UpdateManager downloads from Packages +4. Users verify with SHA256 checksums +``` + +## Setup Requirements + +### 1. Forgejo Personal Access Token + +Create a token with package write permissions: + +1. Go to: https://git.him-tools.de/user/settings/applications +2. Click "Generate New Token" +3. Name: `BUILD_UPLOAD_TOKEN` +4. Scopes: Check `write:package`, `api` +5. Click "Generate Token" +6. Copy the token (you'll use it for uploads) + +**Store securely** - this token grants upload access! + +### 2. Build Scripts + +Upload scripts are already created: +- Windows: `build/scripts/upload_to_packages.ps1` +- macOS: `build/scripts/upload_to_packages.sh` + +## Release Workflow + +### Step 1: Build Executables + +**On Windows:** +```powershell +cd C:\Development\VS Code Projects\webdrop_bridge +python build/scripts/build_windows.py +# Output: build/dist/windows/WebDropBridge.exe +# build/dist/windows/WebDropBridge.exe.sha256 +``` + +**On macOS:** +```bash +cd ~/webdrop_bridge +bash build/scripts/build_macos.sh +# Output: build/dist/macos/WebDropBridge.dmg +# build/dist/macos/WebDropBridge.dmg.sha256 +``` + +### Step 2: Upload to Packages + +**Windows Upload:** +```powershell +$token = "your_token_from_settings" +.\build\scripts\upload_to_packages.ps1 -Version 1.0.0 -ForgejoToken $token +``` + +**macOS Upload:** +```bash +token="your_token_from_settings" +bash build/scripts/upload_to_packages.sh -v 1.0.0 -t $token +``` + +### Step 3: Tag and Commit + +Once both are uploaded: +```bash +git tag -a v1.0.0 -m "Release version 1.0.0" +git push upstream v1.0.0 +``` + +## Forgejo Packages API + +### Package Structure + +``` +https://git.him-tools.de/api/v1/repos/HIM-public/webdrop-bridge/packages +``` + +### Get Latest Version + +```bash +curl https://git.him-tools.de/api/v1/repos/HIM-public/webdrop-bridge/packages +``` + +Response: +```json +[ + { + "id": 123, + "name": "webdrop-bridge", + "version": "1.0.0", + "created_at": "2026-01-28T...", + "files": [ + { + "name": "WebDropBridge.exe", + "size": 204840960, + "file_name": "WebDropBridge.exe", + "id": 456 + }, + { + "name": "WebDropBridge.exe.sha256", + "size": 65, + "file_name": "WebDropBridge.exe.sha256", + "id": 457 + } + ] + } +] +``` + +### Download URL + +``` +https://git.him-tools.de/api/v1/repos/HIM-public/webdrop-bridge/packages/generic/webdrop-bridge/1.0.0/WebDropBridge.exe +``` + +### Direct Package Page + +``` +https://git.him-tools.de/HIM-public/webdrop-bridge/packages +``` + +## UpdateManager Integration (Phase 4.1) + +The auto-update system will query the Packages API: + +```python +async def check_for_updates(self) -> Optional[UpdateInfo]: + """Query Forgejo Packages for new version.""" + url = "https://git.him-tools.de/api/v1/repos/HIM-public/webdrop-bridge/packages" + response = await session.get(url) + packages = response.json() + + # Get latest package + latest = packages[0] # Sorted by date + latest_version = latest['version'] + + # Compare versions + if parse_version(latest_version) > parse_version(self.current_version): + return UpdateInfo( + version=latest_version, + download_url=f".../{latest_version}/WebDropBridge.exe", + checksum_url=f".../{latest_version}/WebDropBridge.exe.sha256" + ) + + return None +``` + +## Upload Script Details + +### Windows Script (`upload_to_packages.ps1`) + +```powershell +Usage: .\upload_to_packages.ps1 -Version 1.0.0 -ForgejoToken $token + +Parameters: + -Version Version number (required, e.g., "1.0.0") + -ForgejoToken Personal access token (required) + -ForgejoUrl Forgejo server URL (default: https://git.him-tools.de) + -Repo Repository (default: HIM-public/webdrop-bridge) + -ExePath Path to exe file (default: build\dist\windows\WebDropBridge.exe) + -ChecksumPath Path to checksum file + +What it does: + 1. Verifies exe and checksum files exist + 2. Uploads exe to Packages + 3. Uploads checksum to Packages + 4. Shows success/error messages +``` + +### macOS Script (`upload_to_packages.sh`) + +```bash +Usage: ./upload_to_packages.sh -v 1.0.0 -t $token + +Options: + -v, --version Version number (required) + -t, --token Personal access token (required) + -u, --url Forgejo server URL (default: https://git.him-tools.de) + +What it does: + 1. Verifies dmg and checksum files exist + 2. Uploads dmg to Packages + 3. Uploads checksum to Packages + 4. Shows success/error messages +``` + +## Complete Release Checklist + +``` +[ ] Update version in src/webdrop_bridge/config.py +[ ] Update CHANGELOG.md with release notes +[ ] Build Windows executable +[ ] Verify WebDropBridge.exe exists +[ ] Verify WebDropBridge.exe.sha256 exists +[ ] Build macOS DMG +[ ] Verify WebDropBridge.dmg exists +[ ] Verify WebDropBridge.dmg.sha256 exists +[ ] Upload Windows to Packages +[ ] Upload macOS to Packages +[ ] Verify both on Packages page +[ ] Create git tag: git tag -a v1.0.0 +[ ] Push tag: git push upstream v1.0.0 +[ ] Announce release +``` + +## Troubleshooting + +### Upload fails with "401 Unauthorized" + +- Verify token is correct +- Check token has `write:package` scope +- Token may have expired - create new one + +### Upload fails with "404 Not Found" + +- Verify repository name is correct (`HIM-public/webdrop-bridge`) +- Verify version format (e.g., `1.0.0`, not `v1.0.0`) + +### Checksum verification fails + +- Regenerate checksums: + ```powershell + # Windows + $file = "build\dist\windows\WebDropBridge.exe" + $hash = (Get-FileHash -Path $file -Algorithm SHA256).Hash + $hash | Out-File -FilePath "${file}.sha256" -NoNewline + ``` + + ```bash + # macOS + shasum -a 256 build/dist/macos/WebDropBridge.dmg > build/dist/macos/WebDropBridge.dmg.sha256 + ``` + +- Upload again + +### Where are my packages? + +View all uploads at: +``` +https://git.him-tools.de/HIM-public/webdrop-bridge/packages +``` + +Each version shows: +- Files (exe/dmg + checksums) +- Upload date +- Download links + +## Manual Download + +Users can download directly: +``` +https://git.him-tools.de/HIM-public/webdrop-bridge/packages/generic/webdrop-bridge/1.0.0/WebDropBridge.exe +https://git.him-tools.de/HIM-public/webdrop-bridge/packages/generic/webdrop-bridge/1.0.0/WebDropBridge.dmg +``` + +Or via Packages page UI: +``` +https://git.him-tools.de/HIM-public/webdrop-bridge/packages +``` + +## Benefits of Packages + +✅ **Simple**: No CI/CD runners needed +✅ **Flexible**: Build when you want +✅ **Reliable**: Forgejo handles storage +✅ **Secure**: Token-based auth +✅ **Integrated**: UpdateManager ready +✅ **Free**: Built-in to Forgejo + +--- + +**Status**: Ready to use +**Last Updated**: January 2026 diff --git a/PHASE_3_3_CI_CD_SUMMARY.md b/PHASE_3_3_CI_CD_SUMMARY.md deleted file mode 100644 index d0d3173..0000000 --- a/PHASE_3_3_CI_CD_SUMMARY.md +++ /dev/null @@ -1,288 +0,0 @@ -# Phase 3.3: Forgejo CI/CD Pipeline - Implementation Summary - -**Date**: January 28, 2026 -**Status**: ✅ COMPLETE (Implementation) | ⏳ PENDING (Runner Setup) - ---- - -## What Was Implemented - -### 1. Forgejo Actions Workflow (`.forgejo/workflows/build.yml`) - -A comprehensive CI/CD pipeline that: - -**On Tag Push** (e.g., `git tag -a v1.0.0 && git push upstream v1.0.0`): -1. Builds Windows executable (windows-latest runner) -2. Builds macOS DMG (macos-latest runner) -3. Generates SHA256 checksums -4. Creates release on Forgejo -5. Uploads all artifacts to release - -**Key Features:** -- Parallel builds for Windows and macOS -- Automatic checksum generation for integrity verification -- Professional release notes with installation instructions -- Integration hooks for UpdateManager (Phase 4.1) -- Manual trigger option via "Run workflow" button - -**Jobs:** - -| Job | Platform | Artifacts | -|-----|----------|-----------| -| `build-windows` | windows-latest | WebDropBridge.exe + SHA256 | -| `build-macos` | macos-latest | WebDropBridge.dmg + SHA256 | -| `release` | ubuntu-latest | Combined release on Forgejo | - -### 2. Setup Documentation (`FORGEJO_CI_CD_SETUP.md`) - -Complete guide including: -- **Architecture diagram** showing workflow -- **Runner setup** for Windows and macOS -- **Secret configuration** (GITEA_TOKEN) -- **Workflow details** and job descriptions -- **Manual trigger** instructions -- **Verification procedures** (SHA256 checksums) -- **Troubleshooting** tips -- **Integration** with auto-update system - -### 3. Version Tracking (`CHANGELOG.md`) - -Professional changelog following "Keep a Changelog" format: -- **Version 1.0.0** (2026-01-28) - Initial release - - All Phase 1 & 2 features documented - - Build system details - - Testing and quality metrics -- **Unreleased** - Planned Phase 4 features -- **Version numbering** guide -- **Release process** documentation - -### 4. Development Plan Update (`DEVELOPMENT_PLAN.md`) - -New section **Phase 3.3** documenting: -- Workflow file structure and location -- Forgejo releases as central hub -- Release artifact locations -- Usage instructions -- Setup requirements -- Acceptance criteria - ---- - -## How It Works - -### Release Process - -``` -1. Developer creates tag locally - git tag -a v1.0.0 -m "Release version 1.0.0" - -2. Push tag to Forgejo - git push upstream v1.0.0 - -3. Forgejo Actions triggers automatically: - ├─ Checkout code - ├─ Run Windows build job - │ ├─ Setup Python 3.13 - │ ├─ Run pytest - │ ├─ Build with PyInstaller - │ └─ Generate SHA256 checksum - ├─ Run macOS build job (parallel) - │ ├─ Setup Python 3.13 - │ ├─ Run pytest - │ ├─ Build DMG with create-dmg - │ └─ Generate SHA256 checksum - └─ Release job (waits for both) - ├─ Create Forgejo release - ├─ Upload artifacts - └─ Generate release notes - -4. Release appears on: - https://git.him-tools.de/HIM-public/webdrop-bridge/releases/v1.0.0 - -5. Users can download: - ├─ WebDropBridge.exe (Windows) - ├─ WebDropBridge.dmg (macOS) - └─ SHA256 checksums (verify integrity) -``` - -### Distribution Hub - -All builds and updates are centralized on Forgejo: - -``` -https://git.him-tools.de/HIM-public/webdrop-bridge/ -├─ Code repository (main branch) -├─ Releases (v1.0.0, v1.0.1, v1.1.0, ...) -│ ├─ WebDropBridge.exe + SHA256 -│ ├─ WebDropBridge.dmg + SHA256 -│ └─ Release notes (features, fixes, upgrade guide) -├─ API endpoint for auto-updates -│ └─ /api/v1/repos/HIM-public/webdrop-bridge/releases/latest -└─ CI/CD logs (build details, errors) -``` - ---- - -## What's Next (Runner Setup) - -To activate the CI/CD pipeline, you need to: - -### Step 1: Set Up Forgejo Runners - -**Windows Runner** (on Windows machine): -```powershell -# Install and register runner -.\forgejo-runner.exe register --no-interactive \ - --forgejo-instance-url https://git.him-tools.de \ - --registration-token \ - --runner-name windows-runner \ - --labels windows,powershell - -# Start daemon -.\forgejo-runner.exe daemon -``` - -**macOS Runner** (on macOS machine): -```bash -# Install and register runner -./act_runner register --no-interactive \ - --forgejo-instance-url https://git.him-tools.de \ - --registration-token \ - --runner-name macos-runner \ - --labels macos - -# Start daemon -./act_runner daemon -``` - -### Step 2: Configure Secret - -In Forgejo repo settings: -1. Go to: Settings → Secrets -2. Create new secret: `GITEA_TOKEN` -3. Value: Personal access token with `api` + `write:repository` scopes - -### Step 3: Test Release - -```bash -# Create test tag -git tag v0.0.1 -git push upstream v0.0.1 - -# Monitor: -# https://git.him-tools.de/HIM-public/webdrop-bridge/actions -``` - ---- - -## Integration Points - -### With Phase 4.1 (Auto-Update System) - -The UpdateManager will: -1. Query: `https://git.him-tools.de/api/v1/repos/HIM-public/webdrop-bridge/releases/latest` -2. Compare versions using semantic versioning -3. Download installer from release assets -4. Verify checksum before installation -5. Execute installer and restart app - -**Example API Response:** -```json -{ - "tag_name": "v1.0.1", - "name": "Release v1.0.1", - "body": "Bug fixes and improvements", - "assets": [ - {"name": "WebDropBridge.exe", "browser_download_url": "..."}, - {"name": "WebDropBridge.exe.sha256", "browser_download_url": "..."} - ] -} -``` - -### User Experience - -1. User opens app -2. Menu → "Check for Updates" -3. UpdateManager queries Forgejo API -4. If newer version available: - - Shows upgrade dialog - - Downloads from Forgejo release - - Verifies checksum - - Installs automatically - - Restarts app with new version - ---- - -## Files Created/Modified - -| File | Status | Purpose | -|------|--------|---------| -| `.forgejo/workflows/build.yml` | ✅ Created | Main CI/CD workflow | -| `FORGEJO_CI_CD_SETUP.md` | ✅ Created | Setup and configuration guide | -| `CHANGELOG.md` | ✅ Created | Version history and tracking | -| `DEVELOPMENT_PLAN.md` | ✅ Updated | Added Phase 3.3 section | - ---- - -## Test Results - -✅ **All 99 tests passing** -- Unit tests: ✅ All passing -- Integration tests: ✅ All passing -- Coverage: 84% (exceeds 80% target) -- No regressions from new files - ---- - -## Current Status - -| Component | Status | Notes | -|-----------|--------|-------| -| Workflow file | ✅ Ready | Committed to both remotes | -| Documentation | ✅ Complete | FORGEJO_CI_CD_SETUP.md guides setup | -| Secret setup | ⏳ Needed | Add GITEA_TOKEN to Forgejo repo | -| Windows runner | ⏳ Needed | Install on Windows machine | -| macOS runner | ⏳ Needed | Install on macOS machine | -| Test run | ⏳ Pending | Tag v0.0.1 after runners ready | -| Production ready | ⏳ After test | Can release v1.0.0 once tested | - ---- - -## Next Steps - -### Immediate (Next Session) -1. ✅ Workflow created and pushed -2. Set up runners (follow FORGEJO_CI_CD_SETUP.md) -3. Add GITEA_TOKEN secret -4. Test with v0.0.1 tag -5. Verify release appears on Forgejo - -### Short-term (Phase 3 Completion) -- Implement optional Windows MSI installer -- Build and test on macOS -- Create application icons (app.ico, app.icns) - -### Medium-term (Phase 4) -- Implement auto-update system (UpdateManager) -- Add "Check for Updates" menu -- Test update flow end-to-end - ---- - -## Summary - -✨ **Forgejo is now your central hub for**: -- 🔧 Building executables (automated) -- 📦 Distributing releases (automated) -- 🔄 Auto-updates (ready for Phase 4.1) -- 📝 Version tracking (CHANGELOG) -- 🔐 Checksum verification (integrity) - -**Setup is ready - just need runners to activate!** - ---- - -**Commit**: `00b4c55` - feat: Add Forgejo CI/CD pipeline for automated builds and releases -**Date**: 2026-01-28 -**Tests**: 99/99 passing ✅ -**Coverage**: 84% ✅ diff --git a/build/scripts/upload_to_packages.ps1 b/build/scripts/upload_to_packages.ps1 new file mode 100644 index 0000000..da5dbd7 --- /dev/null +++ b/build/scripts/upload_to_packages.ps1 @@ -0,0 +1,80 @@ +# Upload Windows Build to Forgejo Packages +# Usage: .\upload_to_packages.ps1 -Version 1.0.0 -ForgejoToken $token + +param( + [Parameter(Mandatory=$true)] + [string]$Version, + + [Parameter(Mandatory=$true)] + [string]$ForgejoToken, + + [string]$ForgejoUrl = "https://git.him-tools.de", + [string]$Repo = "HIM-public/webdrop-bridge", + [string]$ExePath = "build\dist\windows\WebDropBridge.exe", + [string]$ChecksumPath = "build\dist\windows\WebDropBridge.exe.sha256" +) + +$ErrorActionPreference = "Stop" + +# Verify files exist +if (-not (Test-Path $ExePath)) { + Write-Host "ERROR: Executable not found at $ExePath" -ForegroundColor Red + exit 1 +} + +if (-not (Test-Path $ChecksumPath)) { + Write-Host "ERROR: Checksum file not found at $ChecksumPath" -ForegroundColor Red + exit 1 +} + +Write-Host "Uploading WebDropBridge $Version to Forgejo Packages..." -ForegroundColor Cyan + +# Get file info +$exeSize = (Get-Item $ExePath).Length / 1MB +$checksum = Get-Content $ChecksumPath -Raw + +Write-Host "File: WebDropBridge.exe ($([math]::Round($exeSize, 2)) MB)" +Write-Host "Checksum: $($checksum.Substring(0, 16))..." + +# Upload executable +Write-Host "`nUploading executable..." -ForegroundColor Yellow +$exeUrl = "$ForgejoUrl/api/v1/repos/$Repo/packages/generic/webdrop-bridge/$Version/WebDropBridge.exe" + +$headers = @{ + "Authorization" = "token $ForgejoToken" +} + +try { + $response = Invoke-WebRequest -Uri $exeUrl ` + -Method PUT ` + -Headers $headers ` + -InFile $ExePath ` + -ContentType "application/octet-stream" + + Write-Host "✓ Executable uploaded successfully" -ForegroundColor Green +} +catch { + Write-Host "ERROR uploading executable: $_" -ForegroundColor Red + exit 1 +} + +# Upload checksum +Write-Host "Uploading checksum..." -ForegroundColor Yellow +$checksumUrl = "$ForgejoUrl/api/v1/repos/$Repo/packages/generic/webdrop-bridge/$Version/WebDropBridge.exe.sha256" + +try { + $response = Invoke-WebRequest -Uri $checksumUrl ` + -Method PUT ` + -Headers $headers ` + -Body $checksum ` + -ContentType "text/plain" + + Write-Host "✓ Checksum uploaded successfully" -ForegroundColor Green +} +catch { + Write-Host "ERROR uploading checksum: $_" -ForegroundColor Red + exit 1 +} + +Write-Host "`n✓ Upload complete!" -ForegroundColor Green +Write-Host "View at: $ForgejoUrl/$Repo/packages" -ForegroundColor Cyan diff --git a/build/scripts/upload_to_packages.sh b/build/scripts/upload_to_packages.sh new file mode 100644 index 0000000..6666383 --- /dev/null +++ b/build/scripts/upload_to_packages.sh @@ -0,0 +1,91 @@ +#!/bin/bash +# Upload macOS Build to Forgejo Packages +# Usage: ./upload_to_packages.sh -v 1.0.0 -t $token + +set -e + +# Parse arguments +VERSION="" +FORGEJO_TOKEN="" +FORGEJO_URL="https://git.him-tools.de" +REPO="HIM-public/webdrop-bridge" +DMG_PATH="build/dist/macos/WebDropBridge.dmg" +CHECKSUM_PATH="build/dist/macos/WebDropBridge.dmg.sha256" + +while [[ $# -gt 0 ]]; do + case $1 in + -v|--version) VERSION="$2"; shift 2;; + -t|--token) FORGEJO_TOKEN="$2"; shift 2;; + -u|--url) FORGEJO_URL="$2"; shift 2;; + *) echo "Unknown option: $1"; exit 1;; + esac +done + +if [ -z "$VERSION" ] || [ -z "$FORGEJO_TOKEN" ]; then + echo "Usage: $0 -v VERSION -t TOKEN [-u FORGEJO_URL]" + echo "Example: $0 -v 1.0.0 -t your_token_here" + exit 1 +fi + +# Verify files exist +if [ ! -f "$DMG_PATH" ]; then + echo "ERROR: DMG file not found at $DMG_PATH" + exit 1 +fi + +if [ ! -f "$CHECKSUM_PATH" ]; then + echo "ERROR: Checksum file not found at $CHECKSUM_PATH" + exit 1 +fi + +echo "Uploading WebDropBridge $VERSION to Forgejo Packages..." + +# Get file info +DMG_SIZE=$(du -m "$DMG_PATH" | cut -f1) +CHECKSUM=$(cat "$CHECKSUM_PATH") + +echo "File: WebDropBridge.dmg ($DMG_SIZE MB)" +echo "Checksum: ${CHECKSUM:0:16}..." + +# Upload DMG +echo "" +echo "Uploading DMG..." +DMG_URL="$FORGEJO_URL/api/v1/repos/$REPO/packages/generic/webdrop-bridge/$VERSION/WebDropBridge.dmg" + +HTTP_CODE=$(curl -s -w "%{http_code}" -X PUT \ + -H "Authorization: token $FORGEJO_TOKEN" \ + --data-binary "@$DMG_PATH" \ + -H "Content-Type: application/octet-stream" \ + "$DMG_URL" \ + -o /tmp/curl_response.txt) + +if [ "$HTTP_CODE" -eq 201 ] || [ "$HTTP_CODE" -eq 200 ]; then + echo "✓ DMG uploaded successfully" +else + echo "ERROR uploading DMG (HTTP $HTTP_CODE)" + cat /tmp/curl_response.txt + exit 1 +fi + +# Upload checksum +echo "Uploading checksum..." +CHECKSUM_URL="$FORGEJO_URL/api/v1/repos/$REPO/packages/generic/webdrop-bridge/$VERSION/WebDropBridge.dmg.sha256" + +HTTP_CODE=$(curl -s -w "%{http_code}" -X PUT \ + -H "Authorization: token $FORGEJO_TOKEN" \ + -d "$CHECKSUM" \ + -H "Content-Type: text/plain" \ + "$CHECKSUM_URL" \ + -o /tmp/curl_response.txt) + +if [ "$HTTP_CODE" -eq 201 ] || [ "$HTTP_CODE" -eq 200 ]; then + echo "✓ Checksum uploaded successfully" +else + echo "ERROR uploading checksum (HTTP $HTTP_CODE)" + cat /tmp/curl_response.txt + exit 1 +fi + +echo "" +echo "✓ Upload complete!" +echo "View at: $FORGEJO_URL/$REPO/packages"