feat: Add Forgejo CI/CD pipeline for automated builds and releases
- Create .forgejo/workflows/build.yml for automated Windows and macOS builds - Trigger on version tags (v1.0.0, v1.0.1, etc.) or manual dispatch - Windows job builds executable with PyInstaller - macOS job builds DMG package - Automatically generate SHA256 checksums for verification - Create release on Forgejo with all artifacts - Add FORGEJO_CI_CD_SETUP.md with complete setup guide - Add CHANGELOG.md for version tracking - Update DEVELOPMENT_PLAN.md with Phase 3.3 details This enables: - Centralized release hub on Forgejo - Automatic distribution of builds - Foundation for Phase 4.1 auto-update system - Checksum-based integrity verification
This commit is contained in:
parent
db0cef4797
commit
00b4c55612
4 changed files with 622 additions and 0 deletions
233
FORGEJO_CI_CD_SETUP.md
Normal file
233
FORGEJO_CI_CD_SETUP.md
Normal file
|
|
@ -0,0 +1,233 @@
|
|||
# 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
|
||||
Loading…
Add table
Add a link
Reference in a new issue