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. Use Your Existing Forgejo Credentials

You already have HTTP access to Forgejo. Just use the same username and password you use to log in.

Set environment variables with your Forgejo credentials:

Windows (PowerShell):

$env:FORGEJO_USER = "your_forgejo_username"
$env:FORGEJO_PASS = "your_forgejo_password"

macOS/Linux:

export FORGEJO_USER="your_forgejo_username"
export FORGEJO_PASS="your_forgejo_password"

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

After setting your environment variables (see Setup Requirements above), uploading is simple:

Windows Upload:

$env:FORGEJO_USER = "your_username"
$env:FORGEJO_PASS = "your_password"
.\build\scripts\upload_to_packages.ps1 -Version 1.0.0

macOS Upload:

export FORGEJO_USER="your_username"
export FORGEJO_PASS="your_password"
bash build/scripts/upload_to_packages.sh -v 1.0.0

Or set the environment variables once and they persist for all future uploads in that terminal session.

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)

Basic Usage:

# Set your Forgejo credentials
$env:FORGEJO_USER = "your_username"
$env:FORGEJO_PASS = "your_password"

# Upload
.\build\scripts\upload_to_packages.ps1 -Version 1.0.0

Parameters:

• -Version - Version number (required, e.g., "1.0.0")
• -ForgejoUser - Forgejo username (optional if $env:FORGEJO_USER set)
• -ForgejoPW - Forgejo password (optional if $env:FORGEJO_PASS set)
• -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

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

macOS Script (upload_to_packages.sh)

Basic Usage:

# Set your Forgejo credentials
export FORGEJO_USER="your_username"
export FORGEJO_PASS="your_password"

# Upload
bash build/scripts/upload_to_packages.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)

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

Credential Resolution

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

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