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):**
```powershell
$env:FORGEJO_USER = "your_forgejo_username"
$env:FORGEJO_PASS = "your_forgejo_password"
```

**macOS/Linux:**
```bash
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:**
```powershell
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:**
```bash
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:**
```powershell
$env:FORGEJO_USER = "your_username"
$env:FORGEJO_PASS = "your_password"
.\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/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:

```bash
git push upstream v1.0.0
```

## Forgejo Releases API

### Get Latest Release

```bash
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:

```python
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:**
```powershell
# 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:**
```bash
# 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