From 51b36884100815e0a248c265505af5ebab0afb0b Mon Sep 17 00:00:00 2001
From: kdusek <karel.dusek@dhl.com>
Date: Mon, 8 Dec 2025 00:40:56 +0100
Subject: [PATCH] Add workflow documentation for reusability

---
 WORKFLOW.md | 107 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 107 insertions(+)
 create mode 100644 WORKFLOW.md

diff --git a/WORKFLOW.md b/WORKFLOW.md
new file mode 100644
index 0000000..639f65d
--- /dev/null
+++ b/WORKFLOW.md
@@ -0,0 +1,107 @@
+# 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.
\ No newline at end of file