webdrop-bridge/FORGEJO_PACKAGES_SETUP.md

Forgejo Releases Distribution Guide

This guide explains how to distribute WebDrop Bridge builds using Forgejo Releases with binary assets.

Overview

Forgejo Releases is the standard way to distribute binaries. Attach exe/dmg and checksum files to releases.

1. Build locally (Windows & macOS)
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

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 Release

After setting your environment variables (see Setup Requirements above), creating a release is simple:

Windows Upload:

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

macOS Upload:

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

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

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:

git push upstream v1.0.0

Forgejo Releases API

Get Latest Release

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

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

Direct Release Page

https://git.him-tools.de/HIM-public/webdrop-bridge/releases

UpdateManager Integration (Phase 4.1)

The auto-update system will query the Releases API:

async def check_for_updates(self) -> Optional[UpdateInfo]:
    """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)
    release = response.json()
    
    # Get version from tag
    tag_version = release['tag_name'].lstrip('v')
    
    # Compare versions
    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

Troubleshooting

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:

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

# Create release
.\build\scripts\create_release.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
• -ClearCredentials - Clear saved credentials from this session

Script flow:

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 (create_release.sh)

Basic Usage:

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

# 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 → 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

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

[ ] 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
[ ] 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

✅ Integrated: UpdateManager ready
✅ Free: Built-in to Forgejo

---

Status: Ready to use
Last Updated: January 2026