HIM-public/webdrop-bridge
1
0
Fork 0
Code Issues Pull requests Projects Releases 3 Packages Wiki Activity Actions 1

refactor: Switch from Packages API to Releases API for distribution
Some checks are pending
Tests & Quality Checks / Test on Python 3.11 (push) Waiting to run
Details
Tests & Quality Checks / Test on Python 3.12 (push) Waiting to run
Details
Tests & Quality Checks / Test on Python 3.11-1 (push) Waiting to run
Details
Tests & Quality Checks / Test on Python 3.12-1 (push) Waiting to run
Details
Tests & Quality Checks / Test on Python 3.10 (push) Waiting to run
Details
Tests & Quality Checks / Test on Python 3.11-2 (push) Waiting to run
Details
Tests & Quality Checks / Test on Python 3.12-2 (push) Waiting to run
Details
Tests & Quality Checks / Build Artifacts (push) Blocked by required conditions
Details
Tests & Quality Checks / Build Artifacts-1 (push) Blocked by required conditions
Details

Browse source 
- Replace upload_to_packages scripts with create_release scripts
- Use Forgejo Releases API instead (standard for binaries)
- Windows: create_release.ps1 creates release and uploads exe + checksum
- macOS: create_release.sh creates release and uploads dmg + checksum
- Interactive credential prompts on first run
- UpdateManager queries releases/latest for updates
- Much simpler and matches standard open-source distribution
- Rename FORGEJO_PACKAGES_SETUP.md to reflect Releases approach
- Update documentation with Releases API examples
This commit is contained in:
claudi 2026-01-28 15:11:46 +01:00
parent 9c8a8d269c
commit 72b0cfb496
3 changed files with 257 additions and 200 deletions
Download patch file Download diff file Expand all files Collapse all files

283
FORGEJO_PACKAGES_SETUP.md
View file

@ -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