gotify-tray-customized/WORKFLOW.md

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

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

# 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.