# CI/CD Workflow for Gitea with Automated Debian Builds and Releases

This document describes the GitHub Actions workflow setup adapted for Gitea, enabling automated building, testing, and releasing of Debian packages for Linux applications.

## Overview

The workflow automates:
- **Development builds**: Pip package builds on every push to `develop`.
- **Release builds**: Debian package creation and automated release on tags.

Key features:
- Cross-platform compatibility (Linux-focused).
- Dynamic Python version detection.
- Automated Debian packaging using PyInstaller and fpm.
- Direct Gitea API integration for releases (bypasses artifact issues).

## Prerequisites

### Gitea Setup
1. **Actions Enabled**: Ensure Actions are enabled in Gitea Site Administration.
2. **Runner**: Use `act_runner` or compatible runner.
3. **Secrets**: Set `GITEA_TOKEN` in repository secrets (generate a token with `repo` and `write:packages` permissions).

### Dependencies
- **Python**: 3.13 (or compatible version).
- **Tools**: PyInstaller, fpm (Ruby gem), curl, jq.
- **Libraries**: PyQt6, requests, etc. (as per `requirements.txt`).

## Workflow Files

### `.github/workflows/develop.yml`
- **Trigger**: Push to `develop` branch (ignores `release` and tags).
- **Job**: `build-linux`
  - Builds Python wheel.
  - Uploads artifact (for testing).

### `.github/workflows/release.yml`
- **Trigger**: Push to tags (e.g., `v1.0.0`).
- **Job**: `build-deb`
  - Builds PyInstaller binary.
  - Creates Debian package using fpm.
  - Calls Gitea API to create release and upload `.deb`.

## Key Components

### Dynamic Python Detection
```python
py_version = platform.python_version_tuple()[1]
binaries=[(f'/lib/x86_64-linux-gnu/libpython3.{py_version}.so', '.'), ...]
```
Ensures compatibility with different Python versions.

### Debian Packaging
- Uses PyInstaller to create standalone binary.
- fpm packages into `.deb` with proper file structure:
  - Binary: `/opt/<app>/<app>`
  - Desktop file: `/usr/share/applications/`
  - Icon: `/usr/share/pixmaps/`
- Version extracted from tag: `${{github.ref_name#v}}`

### Gitea API Integration
```bash
# Create release
curl -X POST -H "Authorization: token $GITEA_TOKEN" \
  -d '{"tag_name": "'$GITHUB_REF_NAME'", "name": "Release '$GITHUB_REF_NAME'", "body": "Automated release"}' \
  $GITEA_URL/api/v1/repos/$OWNER/$REPO/releases

# Upload asset
curl -X POST -H "Authorization: token $GITEA_TOKEN" \
  --data-binary @dist/app.deb \
  $GITEA_URL/api/v1/repos/$OWNER/$REPO/releases/$ID/assets?name=app.deb
```
Bypasses Gitea's artifact limitations.

## Usage

### Releasing
1. Update version in code/files as needed.
2. Run `./release.sh v1.0.0 "Release notes"`
3. Workflow builds and releases automatically.

### Customization
- **App Name**: Update `gotify-tray` references.
- **Files**: Modify PyInstaller spec, fpm commands.
- **Gitea URL**: Change API endpoints for different instances.
- **Dependencies**: Adjust `requirements.txt` and build steps.

## Troubleshooting

### Build Failures
- **PyInstaller**: Check Python version and lib paths.
- **fpm**: Ensure Ruby and gem are installed.
- **API Errors**: Verify `GITEA_TOKEN` and permissions.

### Icon Issues
- Use PNG icons in `/usr/share/pixmaps/`.
- Update desktop file with correct `Icon=` path.

### Artifact Alternatives
If Gitea artifacts work in your setup, replace API calls with upload/download actions.

## Benefits
- **Automation**: Zero manual intervention for releases.
- **Reusability**: Adapt for other Python/Qt apps.
- **Reliability**: Handles version detection and packaging.

For questions or adaptations, refer to the workflow YAML files.