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

2. Store Token Securely

Choose one of these methods:

Option A: Environment Variable (Simplest)

# Windows PowerShell
$env:FORGEJO_TOKEN = "your_token_here"

Option B: Credential Manager (Windows - Most Secure)

.\build\scripts\upload_to_packages.ps1 -SaveToken -ForgejoToken "your_token_here"
# Token is encrypted and stored for future use

Option C: Config File

# macOS/Linux - Save to home directory
bash build/scripts/upload_to_packages.sh --save-token -t "your_token_here"
# Saved to ~/.config/webdrop-bridge/.env (chmod 600)

Option D: Project .env (Development Only) Create .env in project root and add to .gitignore:

FORGEJO_TOKEN=your_token_here

3. 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 storing your token (see Setup Requirements above), uploading is simple:

Windows Upload:

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

macOS Upload:

bash build/scripts/upload_to_packages.sh -v 1.0.0

The scripts will automatically find your token from:

1. -ForgejoToken / -t parameter (if provided)
2. $env:FORGEJO_TOKEN / $FORGEJO_TOKEN environment variable
3. Windows Credential Manager / ~/.config/webdrop-bridge/.env
4. Project .env file

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:

# After storing token (see Setup Requirements)
.\build\scripts\upload_to_packages.ps1 -Version 1.0.0

First time setup - Save token to Credential Manager:

.\build\scripts\upload_to_packages.ps1 -SaveToken -ForgejoToken "your_token"
# Then future uploads just need version
.\build\scripts\upload_to_packages.ps1 -Version 1.0.0

Parameters:

• -Version - Version number (required, e.g., "1.0.0")
• -ForgejoToken - Personal access token (optional if stored)
• -SaveToken - Save token to Credential Manager
• -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 token in: parameter → environment → Credential Manager
2. Verify exe and checksum files exist
3. Upload exe to Packages API
4. Upload checksum to Packages API
5. Show success message with package URL

macOS Script (upload_to_packages.sh)

Basic Usage:

# After storing token (see Setup Requirements)
bash build/scripts/upload_to_packages.sh -v 1.0.0

First time setup - Save token to config:

bash build/scripts/upload_to_packages.sh --save-token -t "your_token"
# Then future uploads just need version
bash build/scripts/upload_to_packages.sh -v 1.0.0

Options:

• -v, --version - Version number (required, e.g., "1.0.0")
• -t, --token - Personal access token (optional if stored)
• --save-token - Save token to ~/.config/webdrop-bridge/.env
• -u, --url - Forgejo server URL (default: https://git.him-tools.de)

Script flow:

1. Check for token in: parameter → environment → ~/.config/webdrop-bridge/.env → project .env
2. Verify dmg and checksum files exist
3. Upload dmg to Packages API
4. Upload checksum to Packages API
5. Show success message with package URL

Token Resolution Order

Both scripts check for tokens in this priority:

1. Parameter: -ForgejoToken "token" (PowerShell) or -t "token" (Bash)
2. Environment: $env:FORGEJO_TOKEN (PowerShell) or $FORGEJO_TOKEN (Bash)
3. Stored Config:
   • Windows: Credential Manager (via -SaveToken flag)
   • macOS/Linux: ~/.config/webdrop-bridge/.env
4. Project File: .env in project root (if exists)

This design matches how git handles credentials!

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