webdrop-bridge/FORGEJO_CI_CD_SETUP.md

Forgejo CI/CD Setup Guide

This project uses Forgejo Actions to automatically build and release WebDrop Bridge for Windows and macOS.

Architecture

┌─────────────────┐
│   Forgejo Repo  │
│ (Main Hub)      │
└────────┬────────┘
         │
         ├─→ Tag pushed (v1.0.0)
         │
         ├─→ Forgejo Actions triggers
         │   ├─ Build Windows (Windows runner)
         │   ├─ Build macOS (macOS runner)
         │   └─ Create Release
         │
         └─→ Release created with:
             ├─ WebDropBridge.exe + SHA256
             └─ WebDropBridge.dmg + SHA256

Setup Requirements

1. Forgejo Instance Configuration

Your Forgejo instance needs:

• Forgejo Actions enabled (Check: Settings → Actions)
• Runners configured for:
  • Windows (to build Windows executables)
  • macOS (to build DMG packages)

2. Required Secrets

Add these secrets to your Forgejo repository (Settings → Secrets):

GITEA_TOKEN

Personal access token with permissions:

• api - API access
• write:repository - Write to repository (for creating releases)

How to create:

1. Go to https://git.him-tools.de/user/settings/applications
2. Click "Generate New Token"
3. Name: CI_CD_TOKEN
4. Scopes: Select api and write:repository
5. Copy token
6. In repo settings: Add secret GITEA_TOKEN = <token>

3. Runner Setup

Windows Runner

# Install Forgejo runner on Windows machine
cd C:\forgejo-runner
.\forgejo-runner.exe register --no-interactive \
  --forgejo-instance-url https://git.him-tools.de \
  --registration-token <TOKEN_FROM_FORGEJO> \
  --runner-name windows-runner \
  --runner-group default \
  --labels windows,powershell

# Start runner
.\forgejo-runner.exe daemon

macOS Runner

# Install Forgejo runner on macOS
mkdir -p ~/forgejo-runner && cd ~/forgejo-runner
curl -L https://github.com/go-gitea/act_runner/releases/download/v0.5.5/act_runner-0.5.5-darwin-x86_64.tar.gz | tar xz

./act_runner register --no-interactive \
  --forgejo-instance-url https://git.him-tools.de \
  --registration-token <TOKEN_FROM_FORGEJO> \
  --runner-name macos-runner \
  --runner-group default \
  --labels macos

# Start runner
./act_runner daemon

Workflow Details

.forgejo/workflows/build.yml

Triggered on:

• Tag push matching v* (e.g., v1.0.0, v1.0.1)
• Manual trigger via "Run workflow" button

Jobs:

1. build-windows

   • Runs on: windows-latest (requires Windows runner)
   • Steps:
     • Checkout code
     • Set up Python 3.13
     • Install dependencies from requirements-dev.txt
     • Run tests
     • Build Windows executable
     • Generate SHA256 checksum
     • Upload artifacts

2. build-macos

   • Runs on: macos-latest (requires macOS runner)
   • Steps:
     • Checkout code
     • Set up Python 3.13
     • Install dependencies + create-dmg tool
     • Run tests
     • Build macOS DMG
     • Generate SHA256 checksum
     • Upload artifacts

3. release

   • Runs on: ubuntu-latest (built-in)
   • Waits for: Windows and macOS builds
   • Only triggers on: Tag push
   • Steps:
     • Download artifacts from both builds
     • Create GitHub-compatible release
     • Upload executables and checksums
     • Generate release notes

Usage

Automatic Release

1. Create a tag from main branch:

   git tag -a v1.0.0 -m "Release version 1.0.0"
   git push upstream v1.0.0
   

2. Forgejo Actions automatically:

   • Builds Windows executable
   • Builds macOS DMG
   • Creates release with all artifacts
   • Generates checksums for verification

3. Download from:

   • https://git.him-tools.de/HIM-public/webdrop-bridge/releases/tag/v1.0.0

Manual Trigger (for debugging)

1. Go to your Forgejo repo
2. Click "Actions" tab
3. Select "Build WebDrop Bridge" workflow
4. Click "Run workflow"
5. Select branch and click "Run"

Environment Variables

The workflow uses these from your repository:

Variable	Source	Purpose
GITEA_TOKEN	Repository Secret	Authentication for creating releases
Python version	Hardcoded: 3.13	Build environment
PyInstaller	requirements-dev.txt	Build tool

Artifacts & Downloads

Once released, users can download from:

https://git.him-tools.de/HIM-public/webdrop-bridge/releases/v1.0.0
├── WebDropBridge.exe (Windows executable)
├── WebDropBridge.exe.sha256 (Windows checksum)
├── WebDropBridge.dmg (macOS package)
└── WebDropBridge.dmg.sha256 (macOS checksum)

Verification

On Windows

$file = "WebDropBridge.exe"
$expected = Get-Content "WebDropBridge.exe.sha256"
$actual = (Get-FileHash -Path $file -Algorithm SHA256).Hash
if ($actual -eq $expected) { 
    Write-Host "Checksum OK" -ForegroundColor Green 
} else { 
    Write-Host "Checksum FAILED" -ForegroundColor Red 
}

On macOS/Linux

shasum -c WebDropBridge.dmg.sha256

Troubleshooting

Workflow not triggering

• Verify tag format: must start with v (e.g., v1.0.0)
• Check Forgejo Actions is enabled in repo settings
• Verify GITEA_TOKEN secret exists and is valid

Build fails on runner

• Check runner is online: Admin → Runners
• Verify Python 3.13 is installed on runner
• Check logs in Actions tab → Workflow run details

Release creation fails

• Verify GITEA_TOKEN has write:repository scope
• Check token hasn't expired
• Verify runners completed successfully before release job

Next Steps

1. Set up Forgejo runners on Windows and macOS machines
2. Add GITEA_TOKEN secret to repository
3. Test with git tag v0.0.1 && git push upstream v0.0.1
4. Verify release appears at releases/v0.0.1

Integration with Auto-Update System

The Forgejo releases created by this workflow will be used by:

• Phase 4.1 UpdateManager: Queries https://git.him-tools.de/api/v1/repos/HIM-public/webdrop-bridge/releases/latest
• Menu Option: "Check for Updates" downloads installer from release assets
• Auto-Install: Extracts and installs new version

---

Status: Ready to deploy (pending runner setup)
Last Updated: January 2026