webdrop-bridge/FORGEJO_PACKAGES_SETUP.md

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:

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:

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:

$token = "your_token_from_settings"
.\build\scripts\upload_to_packages.ps1 -Version 1.0.0 -ForgejoToken $token

macOS Upload:

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:

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

curl https://git.him-tools.de/api/v1/repos/HIM-public/webdrop-bridge/packages

Response:

[
  {
    "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:

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)

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)

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:

  # Windows
  $file = "build\dist\windows\WebDropBridge.exe"
  $hash = (Get-FileHash -Path $file -Algorithm SHA256).Hash
  $hash | Out-File -FilePath "${file}.sha256" -NoNewline
  

  # 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