diff --git a/FORGEJO_PACKAGES_SETUP.md b/FORGEJO_PACKAGES_SETUP.md index 8f3040d..ab362bb 100644 --- a/FORGEJO_PACKAGES_SETUP.md +++ b/FORGEJO_PACKAGES_SETUP.md @@ -1,16 +1,17 @@ -# Forgejo Packages Distribution Guide +# Forgejo Releases Distribution Guide -This guide explains how to distribute WebDrop Bridge builds using **Forgejo Packages** instead of runners. +This guide explains how to distribute WebDrop Bridge builds using **Forgejo Releases** with binary assets. ## 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. +**Forgejo Releases** is the standard way to distribute binaries. Attach exe/dmg and checksum files to releases. ``` 1. Build locally (Windows & macOS) -2. Upload exe + dmg to Forgejo Packages -3. UpdateManager downloads from Packages -4. Users verify with SHA256 checksums +2. Create Release (v1.0.0) +3. Upload exe + dmg as release assets +4. UpdateManager downloads from release +5. Users verify with SHA256 checksums ``` ## Setup Requirements @@ -59,115 +60,150 @@ bash build/scripts/build_macos.sh # build/dist/macos/WebDropBridge.dmg.sha256 ``` -### Step 2: Upload to Packages +### Step 2: Upload to Release -After setting your environment variables (see Setup Requirements above), uploading is simple: +After setting your environment variables (see Setup Requirements above), creating a release is simple: **Windows Upload:** ```powershell $env:FORGEJO_USER = "your_username" $env:FORGEJO_PASS = "your_password" -.\build\scripts\upload_to_packages.ps1 -Version 1.0.0 +.\build\scripts\create_release.ps1 -Version 1.0.0 ``` **macOS Upload:** ```bash export FORGEJO_USER="your_username" export FORGEJO_PASS="your_password" -bash build/scripts/upload_to_packages.sh -v 1.0.0 +bash build/scripts/create_release.sh -v 1.0.0 ``` -Or set the environment variables once and they persist for all future uploads in that terminal session. +Or set the environment variables once and they persist for all future releases in that terminal session. -### Step 3: Tag and Commit +The script will: +1. Create a release with tag `v1.0.0` +2. Upload the executable as an asset +3. Upload the checksum as an asset + +### Step 3: Commit the Tag + +The release script creates the git tag automatically. Push it: -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 +## Forgejo Releases API -### Package Structure - -``` -https://git.him-tools.de/api/v1/repos/HIM-public/webdrop-bridge/packages -``` - -### Get Latest Version +### Get Latest Release ```bash -curl https://git.him-tools.de/api/v1/repos/HIM-public/webdrop-bridge/packages +curl https://git.him-tools.de/api/v1/repos/HIM-public/webdrop-bridge/releases/latest ``` -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 - } - ] - } -] +Response includes assets array with download URLs for exe, dmg, and checksums. + +### Download URLs + +After creating a release, assets are available at: +``` +https://git.him-tools.de/HIM-public/webdrop-bridge/releases/download/v1.0.0/WebDropBridge.exe +https://git.him-tools.de/HIM-public/webdrop-bridge/releases/download/v1.0.0/WebDropBridge.exe.sha256 ``` -### Download URL +### Direct Release Page ``` -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 +https://git.him-tools.de/HIM-public/webdrop-bridge/releases ``` ## UpdateManager Integration (Phase 4.1) -The auto-update system will query the Packages API: +The auto-update system will query the Releases 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" + """Query Forgejo Releases for new version.""" + url = "https://git.him-tools.de/api/v1/repos/HIM-public/webdrop-bridge/releases/latest" response = await session.get(url) - packages = response.json() + release = response.json() - # Get latest package - latest = packages[0] # Sorted by date - latest_version = latest['version'] + # Get version from tag + tag_version = release['tag_name'].lstrip('v') # 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" - ) + if parse_version(tag_version) > parse_version(self.current_version): + # Find exe and checksum assets + assets = release.get('assets', []) + exe_asset = next((a for a in assets if a['name'].endswith('.exe')), None) + checksum_asset = next((a for a in assets if a['name'].endswith('.sha256')), None) + + if exe_asset and checksum_asset: + return UpdateInfo( + version=tag_version, + download_url=exe_asset['browser_download_url'], + checksum_url=checksum_asset['browser_download_url'] + ) return None ``` -## Upload Script Details +## Troubleshooting -### Windows Script (`upload_to_packages.ps1`) +### Release creation fails with "409 Conflict" + +- Tag already exists +- Use a different version number + +### Release creation fails with "401 Unauthorized" + +- Verify credentials are correct +- Check you have write access to repo + +### Asset upload fails + +- Check file exists and is readable +- Verify file isn't too large (Forgejo may have limits) +- Try again, transient network issues can occur + +### Where are my releases? + +View all releases at: +``` +https://git.him-tools.de/HIM-public/webdrop-bridge/releases +``` + +Each release shows: +- Version/tag name +- Release date +- Release notes +- Attached assets with download links + +## Manual Download + +Users can download directly from releases: +``` +https://git.him-tools.de/HIM-public/webdrop-bridge/releases/download/v1.0.0/WebDropBridge.exe +https://git.him-tools.de/HIM-public/webdrop-bridge/releases/download/v1.0.0/WebDropBridge.dmg +``` + +Or via Releases page UI: +``` +https://git.him-tools.de/HIM-public/webdrop-bridge/releases +``` + +## Benefits of Releases Distribution + +✅ **Simple**: No special setup needed +✅ **Flexible**: Build when you want +✅ **Standard**: Same as most open-source projects +✅ **Auto-Update Ready**: UpdateManager queries easily +✅ **User Friendly**: Download from releases page + + +## Release Script Details + +### Windows Script (`create_release.ps1`) **Basic Usage:** ```powershell @@ -175,8 +211,8 @@ async def check_for_updates(self) -> Optional[UpdateInfo]: $env:FORGEJO_USER = "your_username" $env:FORGEJO_PASS = "your_password" -# Upload -.\build\scripts\upload_to_packages.ps1 -Version 1.0.0 +# Create release +.\build\scripts\create_release.ps1 -Version 1.0.0 ``` **Parameters:** @@ -187,15 +223,17 @@ $env:FORGEJO_PASS = "your_password" - `-Repo` - Repository (default: HIM-public/webdrop-bridge) - `-ExePath` - Path to exe file (default: build\dist\windows\WebDropBridge.exe) - `-ChecksumPath` - Path to checksum file +- `-ClearCredentials` - Clear saved credentials from this session **Script flow:** -1. Check for credentials in: parameter → environment variables -2. Verify exe and checksum files exist -3. Upload exe to Packages API with HTTP Basic Auth -4. Upload checksum to Packages API -5. Show success message with package URL +1. Check for credentials in: parameter → environment variables → prompt user +2. Save credentials to environment for future use +3. Create release with tag `v{Version}` +4. Upload exe as asset +5. Upload checksum as asset +6. Show success message with release URL -### macOS Script (`upload_to_packages.sh`) +### macOS Script (`create_release.sh`) **Basic Usage:** ```bash @@ -203,20 +241,22 @@ $env:FORGEJO_PASS = "your_password" export FORGEJO_USER="your_username" export FORGEJO_PASS="your_password" -# Upload -bash build/scripts/upload_to_packages.sh -v 1.0.0 +# Create release +bash build/scripts/create_release.sh -v 1.0.0 ``` **Options:** - `-v, --version` - Version number (required, e.g., "1.0.0") - `-u, --url` - Forgejo server URL (default: https://git.him-tools.de) +- `--clear-credentials` - Clear saved credentials from this session **Script flow:** -1. Check for credentials in: environment variables (`$FORGEJO_USER`, `$FORGEJO_PASS`) -2. Verify dmg and checksum files exist -3. Upload dmg to Packages API with HTTP Basic Auth -4. Upload checksum to Packages API -5. Show success message with package URL +1. Check for credentials in: environment variables → prompt user +2. Export credentials for future use +3. Create release with tag `v{Version}` +4. Upload dmg as asset +5. Upload checksum as asset +6. Show success message with release URL ### Credential Resolution @@ -224,6 +264,7 @@ Both scripts use HTTP Basic Authentication with your Forgejo username/password: - Same credentials you use to log into Forgejo - Same credentials git uses when cloning over HTTPS - No special token creation needed +- First run prompts for credentials, saves to session ## Complete Release Checklist @@ -236,75 +277,11 @@ Both scripts use HTTP Basic Authentication with your Forgejo username/password: [ ] 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 +[ ] Create Windows release: .\build\scripts\create_release.ps1 -Version 1.0.0 +[ ] Create macOS release: bash build/scripts/create_release.sh -v 1.0.0 +[ ] Verify both on Releases page +[ ] Push tags: git push upstream v1.0.0 ``` - -## 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 diff --git a/build/scripts/upload_to_packages.ps1 b/build/scripts/create_release.ps1 similarity index 57% rename from build/scripts/upload_to_packages.ps1 rename to build/scripts/create_release.ps1 index 413b937..64bc8cc 100644 --- a/build/scripts/upload_to_packages.ps1 +++ b/build/scripts/create_release.ps1 @@ -1,5 +1,5 @@ -# Upload Windows Build to Forgejo Packages -# Usage: .\upload_to_packages.ps1 -Version 1.0.0 +# Create Forgejo Release with Binary Assets +# Usage: .\create_release.ps1 -Version 1.0.0 # Uses your Forgejo credentials (same as git) # First run will prompt for credentials and save them to this session @@ -57,13 +57,13 @@ if (-not $ForgejoUser -or -not $ForgejoPW) { $env:FORGEJO_USER = $ForgejoUser $env:FORGEJO_PASS = $ForgejoPW Write-Host "[OK] Credentials saved to this PowerShell session" -ForegroundColor Green - Write-Host "Tip: Credentials will persist until you close PowerShell or run: .\upload_to_packages.ps1 -ClearCredentials" -ForegroundColor Gray + Write-Host "Tip: Credentials will persist until you close PowerShell or run: .\create_release.ps1 -ClearCredentials" -ForegroundColor Gray } # Verify Version parameter if (-not $Version) { Write-Host "ERROR: Version parameter required" -ForegroundColor Red - Write-Host "Usage: .\upload_to_packages.ps1 -Version 1.0.0" -ForegroundColor Yellow + Write-Host "Usage: .\create_release.ps1 -Version 1.0.0" -ForegroundColor Yellow exit 1 } @@ -78,7 +78,7 @@ if (-not (Test-Path $ChecksumPath)) { exit 1 } -Write-Host "Uploading WebDropBridge $Version to Forgejo Packages..." -ForegroundColor Cyan +Write-Host "Creating WebDropBridge $Version release on Forgejo..." -ForegroundColor Cyan # Get file info $exeSize = (Get-Item $ExePath).Length / 1MB @@ -90,47 +90,88 @@ Write-Host "Checksum: $($checksum.Substring(0, 16))..." # Create basic auth header $auth = [System.Convert]::ToBase64String([System.Text.Encoding]::ASCII.GetBytes("${ForgejoUser}:${ForgejoPW}")) -# Upload executable -Write-Host "`nUploading executable..." -ForegroundColor Yellow -$exeUrl = "$ForgejoUrl/api/v1/repos/$Repo/packages/generic/webdrop-bridge/$Version/WebDropBridge.exe" - $headers = @{ "Authorization" = "Basic $auth" + "Content-Type" = "application/json" } +# Step 1: Create release +Write-Host "`nCreating release v$Version..." -ForegroundColor Yellow +$releaseUrl = "$ForgejoUrl/api/v1/repos/$Repo/releases" + +$releaseData = @{ + tag_name = "v$Version" + name = "WebDropBridge v$Version" + body = "WebDropBridge v$Version`n`nChecksum: $checksum" + draft = $false + prerelease = $false +} | ConvertTo-Json + try { - $response = Invoke-WebRequest -Uri $exeUrl ` - -Method PUT ` + $response = Invoke-WebRequest -Uri $releaseUrl ` + -Method POST ` -Headers $headers ` - -InFile $ExePath ` - -ContentType "application/octet-stream" ` + -Body $releaseData ` + -TimeoutSec 30 ` + -ErrorAction Stop + + $releaseInfo = $response.Content | ConvertFrom-Json + $releaseId = $releaseInfo.id + Write-Host "[OK] Release created (ID: $releaseId)" -ForegroundColor Green +} +catch { + Write-Host "ERROR creating release: $_" -ForegroundColor Red + exit 1 +} + +# Step 2: Upload executable as asset +Write-Host "Uploading executable asset..." -ForegroundColor Yellow +$uploadUrl = "$ForgejoUrl/api/v1/repos/$Repo/releases/$releaseId/assets" + +try { + $exeItem = Get-Item $ExePath + + $form = @{ + attachment = $exeItem + } + + $response = Invoke-WebRequest -Uri $uploadUrl ` + -Method POST ` + -Headers @{ "Authorization" = "Basic $auth" } ` + -Form $form ` -TimeoutSec 600 ` -ErrorAction Stop - Write-Host "[OK] Executable uploaded successfully" -ForegroundColor Green + Write-Host "[OK] Executable uploaded" -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" +# Step 3: Upload checksum as asset +Write-Host "Uploading checksum asset..." -ForegroundColor Yellow try { - $response = Invoke-WebRequest -Uri $checksumUrl ` - -Method PUT ` - -Headers $headers ` - -Body $checksum ` - -ContentType "text/plain" + $checksumItem = Get-Item $ChecksumPath - Write-Host "[OK] Checksum uploaded successfully" -ForegroundColor Green + $form = @{ + attachment = $checksumItem + } + + $response = Invoke-WebRequest -Uri $uploadUrl ` + -Method POST ` + -Headers @{ "Authorization" = "Basic $auth" } ` + -Form $form ` + -TimeoutSec 30 ` + -ErrorAction Stop + + Write-Host "[OK] Checksum uploaded" -ForegroundColor Green } catch { Write-Host "ERROR uploading checksum: $_" -ForegroundColor Red exit 1 } -Write-Host "`n[OK] Upload complete!" -ForegroundColor Green -Write-Host "View at: $ForgejoUrl/$Repo/packages" -ForegroundColor Cyan +Write-Host "`n[OK] Release complete!" -ForegroundColor Green +Write-Host "View at: $ForgejoUrl/$Repo/releases/tag/v$Version" -ForegroundColor Cyan diff --git a/build/scripts/upload_to_packages.sh b/build/scripts/create_release.sh similarity index 59% rename from build/scripts/upload_to_packages.sh rename to build/scripts/create_release.sh index 64be0ef..1c1838f 100644 --- a/build/scripts/upload_to_packages.sh +++ b/build/scripts/create_release.sh @@ -1,6 +1,6 @@ #!/bin/bash -# Upload macOS Build to Forgejo Packages -# Usage: ./upload_to_packages.sh -v 1.0.0 +# Create Forgejo Release with Binary Assets +# Usage: ./create_release.sh -v 1.0.0 # Uses your Forgejo credentials (same as git) # First run will prompt for credentials and save them to this session @@ -65,7 +65,18 @@ if [ -z "$FORGEJO_USER" ] || [ -z "$FORGEJO_PASS" ]; then echo "Tip: Credentials will persist until you close the terminal or run: $0 --clear-credentials" fi -echo "Uploading WebDropBridge $VERSION to Forgejo Packages..." +# 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 "Creating WebDropBridge $VERSION release on Forgejo..." # Get file info DMG_SIZE=$(du -m "$DMG_PATH" | cut -f1) @@ -74,42 +85,70 @@ CHECKSUM=$(cat "$CHECKSUM_PATH") echo "File: WebDropBridge.dmg ($DMG_SIZE MB)" echo "Checksum: ${CHECKSUM:0:16}..." -# Create basic auth header +# Create basic auth BASIC_AUTH=$(echo -n "${FORGEJO_USER}:${FORGEJO_PASS}" | base64) -# Upload DMG +# Step 1: Create release echo "" -echo "Uploading DMG..." -DMG_URL="$FORGEJO_URL/api/v1/repos/$REPO/packages/generic/webdrop-bridge/$VERSION/WebDropBridge.dmg" +echo "Creating release v$VERSION..." +RELEASE_URL="$FORGEJO_URL/api/v1/repos/$REPO/releases" -HTTP_CODE=$(curl -s -w "%{http_code}" -X PUT \ +RELEASE_DATA=$(cat <