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