Files

dolgolyov.alexei 01c8f71fee fix: add f-string prefix to release body template

2026-03-24 14:26:17 +03:00

19 KiB

Raw Blame History

CI/CD for Python Apps on Gitea

A reusable reference for building CI pipelines, release automation, and installer packaging for Python-based applications hosted on Gitea. Extracted from a production project using Gitea Actions (GitHub Actions-compatible).

Prerequisites

Gitea instance with Actions enabled
Runner(s) tagged ubuntu-latest (e.g., TrueNAS-hosted Gitea runners)
GITEA_TOKEN secret configured in the repository (Settings > Secrets)

Pipeline Architecture

Two workflows, triggered by different events:

push/PR to master  ──►  test.yml   (lint + test)
push tag v*        ──►  release.yml (build + release + Docker)

1. Lint & Test Workflow

Trigger: Push to master or pull request.

# .gitea/workflows/test.yml
name: Lint & Test

on:
  push:
    branches: [master]
  pull_request:
    branches: [master]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'

      - name: Install system dependencies
        run: |
          sudo apt-get update
          sudo apt-get install -y --no-install-recommends <your-system-deps>

      - name: Install dependencies
        working-directory: server
        run: |
          pip install --upgrade pip
          pip install -e ".[dev]"

      - name: Lint
        working-directory: server
        run: ruff check src/ tests/

      - name: Test
        working-directory: server
        run: pytest --tb=short -q

Key points:

Keep the test job fast — lint first, then test
Use ruff for linting (fast, replaces flake8 + isort + pyupgrade)
Configure pytest in pyproject.toml with coverage:

[tool.pytest.ini_options]
testpaths = ["tests"]
asyncio_mode = "auto"
addopts = "-v --cov=your_package --cov-report=html --cov-report=term"

2. Release Workflow

Trigger: Push a tag matching v* (e.g., v0.2.0, v0.2.0-alpha.1).

2.1. Create Release Job

Creates a Gitea release via REST API with a formatted description.

create-release:
  runs-on: ubuntu-latest
  outputs:
    release_id: ${{ steps.create.outputs.release_id }}
  steps:
    - name: Create Gitea release
      id: create
      env:
        GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
      run: |
        TAG="${{ gitea.ref_name }}"
        BASE_URL="${{ gitea.server_url }}/api/v1/repos/${{ gitea.repository }}"

        # Detect pre-release
        IS_PRE="false"
        if echo "$TAG" | grep -qE '(alpha|beta|rc)'; then
          IS_PRE="true"
        fi

        # Build release body (use Python to avoid YAML escaping issues)
        BODY_JSON=$(python3 -c "
        import json, textwrap
        tag = '$TAG'
        body = f'''## Downloads
        | Platform | File |
        |----------|------|
        | Windows (installer) | \`App-{tag}-setup.exe\` |
        | Windows (portable) | \`App-{tag}-win-x64.zip\` |
        | Linux | \`App-{tag}-linux-x64.tar.gz\` |
        '''
        print(json.dumps(textwrap.dedent(body).strip()))
        ")

        RELEASE=$(curl -s -X POST "\$BASE_URL/releases" \
          -H "Authorization: token \$GITEA_TOKEN" \
          -H "Content-Type: application/json" \
          -d "{
            \"tag_name\": \"\$TAG\",
            \"name\": \"App \$TAG\",
            \"body\": \$BODY_JSON,
            \"draft\": false,
            \"prerelease\": \$IS_PRE
          }")

        # Fallback: if release already exists for this tag, fetch it instead
        RELEASE_ID=$(echo "\$RELEASE" | python3 -c "import sys,json; print(json.load(sys.stdin)['id'])" 2>/dev/null)
        if [ -z "\$RELEASE_ID" ]; then
          echo "::warning::Release already exists for tag \$TAG — reusing existing release"
          RELEASE=$(curl -s "\$BASE_URL/releases/tags/\$TAG" \
            -H "Authorization: token \$GITEA_TOKEN")
          RELEASE_ID=$(echo "\$RELEASE" | python3 -c "import sys,json; print(json.load(sys.stdin)['id'])")
        fi
        echo "release_id=\$RELEASE_ID" >> "\$GITHUB_OUTPUT"

Key points:

Gitea uses ${{ gitea.ref_name }} instead of GitHub's ${{ github.ref_name }}
Use ${{ gitea.server_url }} and ${{ gitea.repository }} for API URLs
Output vars use $GITHUB_OUTPUT (Gitea Actions is compatible with GitHub Actions syntax)
Use Python for body templating to avoid shell/YAML escaping hell

2.2. Build Jobs (Parallel)

All build jobs run in parallel, gated on create-release:

build-windows:
  needs: create-release
  runs-on: ubuntu-latest
  # ...

build-linux:
  needs: create-release
  runs-on: ubuntu-latest
  # ...

build-docker:
  needs: create-release
  runs-on: ubuntu-latest
  # ...

2.3. Upload Assets to Gitea Release

- name: Attach assets to release
  env:
    GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
  run: |
    RELEASE_ID="${{ needs.create-release.outputs.release_id }}"
    BASE_URL="${{ gitea.server_url }}/api/v1/repos/${{ gitea.repository }}"

    FILE=$(ls build/App-*.zip | head -1)
    curl -s -X POST \
      "$BASE_URL/releases/$RELEASE_ID/assets?name=$(basename "$FILE")" \
      -H "Authorization: token $GITEA_TOKEN" \
      -H "Content-Type: application/octet-stream" \
      --data-binary "@$FILE"

3. Version Detection Pattern

A robust fallback chain for detecting the version in build scripts:

# 1. CLI argument
VERSION="${1:-}"

# 2. Exact git tag
if [ -z "$VERSION" ]; then
    VERSION=$(git describe --tags --exact-match 2>/dev/null || true)
fi

# 3. CI environment variable (Gitea or GitHub)
if [ -z "$VERSION" ]; then
    VERSION="${GITEA_REF_NAME:-${GITHUB_REF_NAME:-}}"
fi

# 4. Hardcoded in source
if [ -z "$VERSION" ]; then
    VERSION=$(grep -oP '__version__\s*=\s*"\K[^"]+' \
      src/your_package/__init__.py 2>/dev/null || echo "0.0.0")
fi

VERSION_CLEAN="${VERSION#v}"  # Strip leading 'v'

4. Cross-Building Windows from Linux

No Windows runner needed. Download Windows embedded Python and win_amd64 wheels on Linux.

4.1. Embedded Python Setup

# Download Windows embedded Python
PYTHON_VERSION="3.11.9"
curl -sL "https://www.python.org/ftp/python/${PYTHON_VERSION}/python-${PYTHON_VERSION}-embed-amd64.zip" \
  -o python-embed.zip
unzip -qo python-embed.zip -d dist/python

# Patch ._pth to enable site-packages
PTH_FILE=$(ls dist/python/python*._pth | head -1)
sed -i 's/^#\s*import site/import site/' "$PTH_FILE"
echo 'Lib\site-packages' >> "$PTH_FILE"
echo '../app/src' >> "$PTH_FILE"       # App source on PYTHONPATH

Why embedded Python? It's a minimal, standalone Python distribution (~15 MB) without an installer. Perfect for bundling into portable apps.

4.2. Cross-Platform Wheel Download

WHEEL_DIR="build/win-wheels"
SITE_PACKAGES="dist/python/Lib/site-packages"
mkdir -p "$WHEEL_DIR" "$SITE_PACKAGES"

# Download win_amd64 wheels (fallback to source for pure Python)
for dep in "fastapi>=0.115.0" "uvicorn>=0.32.0" "numpy>=2.1.3"; do
    pip download --quiet --dest "$WHEEL_DIR" \
        --platform win_amd64 --python-version "3.11" \
        --implementation cp --only-binary :all: \
        "$dep" 2>/dev/null || \
    pip download --quiet --dest "$WHEEL_DIR" "$dep"
done

# Install wheels into site-packages (just unzip — .whl is a zip)
for whl in "$WHEEL_DIR"/*.whl; do
    unzip -qo "$whl" -d "$SITE_PACKAGES"
done

4.3. Size Optimization

Strip unnecessary files from site-packages to reduce archive size:

find "$SITE_PACKAGES" -type d -name __pycache__ -exec rm -rf {} +
find "$SITE_PACKAGES" -type d -name tests -exec rm -rf {} +
find "$SITE_PACKAGES" -type d -name "*.dist-info" -exec rm -rf {} +
find "$SITE_PACKAGES" -name "*.pyi" -delete

# Remove build-time-only packages
rm -rf "$SITE_PACKAGES"/{pip,setuptools,pkg_resources}*

# Remove heavy unused parts of specific libraries
rm -f "$SITE_PACKAGES"/cv2/opencv_videoio_ffmpeg*.dll  # -28 MB
rm -rf "$SITE_PACKAGES"/numpy/{tests,f2py,typing}

4.4. Bundling tkinter (Optional)

Embedded Python doesn't include tkinter. Extract it from the official MSI packages:

# Requires: apt install msitools
MSI_BASE="https://www.python.org/ftp/python/${PYTHON_VERSION}/amd64"
curl -sL "$MSI_BASE/tcltk.msi" -o tcltk.msi
curl -sL "$MSI_BASE/lib.msi" -o lib.msi

msiextract tcltk.msi   # → _tkinter.pyd, tcl86t.dll, tk86t.dll, tcl8.6/, tk8.6/
msiextract lib.msi      # → tkinter/ Python package

# Copy to embedded Python directory
cp _tkinter.pyd tcl86t.dll tk86t.dll dist/python/
cp -r tkinter dist/python/Lib/
cp -r tcl8.6 tk8.6 dist/python/

5. Linux Build (venv-based)

# Create self-contained virtualenv
python3 -m venv dist/venv
source dist/venv/bin/activate
pip install ".[camera,notifications]"

# Remove the installed package (PYTHONPATH handles app code at runtime)
rm -rf dist/venv/lib/python*/site-packages/your_package*

# Launcher script
cat > dist/run.sh << 'EOF'
#!/usr/bin/env bash
set -euo pipefail
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
export PYTHONPATH="$SCRIPT_DIR/app/src"
source "$SCRIPT_DIR/venv/bin/activate"
exec python -m your_package.main
EOF
chmod +x dist/run.sh

# Package
tar -czf "App-v${VERSION}-linux-x64.tar.gz" dist/

5.1. Systemd Service Script

Include install/uninstall scripts for running as a service:

# install-service.sh creates:
# /etc/systemd/system/your-app.service
#   Type=simple, Restart=on-failure, RestartSec=5
#   ExecStart=/path/to/run.sh
# Then: systemctl daemon-reload && systemctl enable && systemctl start

6. NSIS Installer (Windows)

Cross-compilable on Linux: apt install nsis && makensis installer.nsi

Key design decisions:

; User-scoped install (no admin required)
InstallDir "$LOCALAPPDATA\${APPNAME}"
RequestExecutionLevel user

; Optional: launch app after install (checkbox on finish page)
; IMPORTANT: Do NOT use MUI_FINISHPAGE_RUN with MUI_FINISHPAGE_RUN_PARAMETERS —
; NSIS Exec command chokes on the quoting. Use MUI_FINISHPAGE_RUN_FUNCTION instead:
!define MUI_FINISHPAGE_RUN ""
!define MUI_FINISHPAGE_RUN_TEXT "Launch ${APPNAME}"
!define MUI_FINISHPAGE_RUN_FUNCTION LaunchApp

Function LaunchApp
    ExecShell "open" "wscript.exe" '"$INSTDIR\scripts\start-hidden.vbs"'
    Sleep 2000
    ExecShell "open" "http://localhost:8765/"  ; Open Web UI after server starts
FunctionEnd

; Detect running instance before install (file lock check)
Function .onInit
    IfFileExists "$INSTDIR\python\python.exe" 0 done
    ClearErrors
    FileOpen $0 "$INSTDIR\python\python.exe" a
    IfErrors locked
    FileClose $0
    Goto done
    locked:
        MessageBox MB_YESNOCANCEL|MB_ICONEXCLAMATION \
            "${APPNAME} is currently running.$\n$\nYes = Stop and continue$\nNo = Continue anyway (may cause errors)$\nCancel = Abort" \
            IDYES kill IDNO done
        Abort
        kill:
            nsExec::ExecToLog 'wmic process where "ExecutablePath like $\'%AppName%python%$\'" call terminate'
            Sleep 2000
    done:
FunctionEnd

; Sections
Section "!Core (required)" SecCore        ; App files + uninstaller
Section "Desktop shortcut" SecDesktop     ; Optional
Section "Start with Windows" SecAutostart ; Optional — Startup folder shortcut

; Uninstall preserves user data
; RMDir /r $INSTDIR\python, $INSTDIR\app, $INSTDIR\logs
; But NOT $INSTDIR\data (user config)

Hidden Launcher (VBS)

Bat files briefly flash a console window even with @echo off. To avoid this, use a VBS wrapper that all shortcuts and the finish page point to:

Set fso = CreateObject("Scripting.FileSystemObject")
Set WshShell = CreateObject("WScript.Shell")
scriptDir = fso.GetParentFolderName(WScript.ScriptFullName)
appRoot = fso.GetParentFolderName(scriptDir)
WshShell.CurrentDirectory = appRoot
' Use embedded Python if present (installed dist), otherwise system Python
embeddedPython = appRoot & "\python\python.exe"
If fso.FileExists(embeddedPython) Then
    WshShell.Run """" & embeddedPython & """ -m your_package.main", 0, False
Else
    WshShell.Run "python -m your_package.main", 0, False
End If

Place in scripts/start-hidden.vbs and bundle it in the build script. All NSIS shortcuts use: "wscript.exe" '"$INSTDIR\scripts\start-hidden.vbs"'

Important: The embedded Python fallback is critical — the installed distribution doesn't have Python on PATH, so python alone won't work. The dev environment uses system Python, so the fallback handles both cases.

CI dependencies: sudo apt-get install -y nsis msitools zip

Build: makensis -DVERSION="${VERSION}" installer.nsi

7. Docker Build

Multi-stage Dockerfile

# Stage 1: Build frontend
FROM node:20-slim AS frontend
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
RUN npm run build

# Stage 2: Runtime
FROM python:3.11-slim
RUN apt-get update && apt-get install -y --no-install-recommends <system-deps> \
    && rm -rf /var/lib/apt/lists/*

WORKDIR /app
COPY pyproject.toml .
RUN pip install --no-cache-dir ".[notifications]"
COPY src/ src/
COPY --from=frontend /app/src/your_package/static/ src/your_package/static/

RUN useradd -r -u 1000 appuser
USER appuser

HEALTHCHECK --interval=30s --timeout=5s CMD curl -f http://localhost:8080/health || exit 1
EXPOSE 8080
CMD ["uvicorn", "your_package.main:app", "--host", "0.0.0.0", "--port", "8080"]

Docker in CI (Gitea Registry)

- name: Login to Gitea Container Registry
  id: docker-login
  continue-on-error: true  # Graceful degradation if registry unavailable
  run: |
    echo "${{ secrets.GITEA_TOKEN }}" | docker login \
      "$SERVER_HOST" -u "${{ gitea.actor }}" --password-stdin

- name: Build and tag
  if: steps.docker-login.outcome == 'success'
  run: |
    docker build -t "$REGISTRY:$TAG" -t "$REGISTRY:$VERSION" ./server
    # Tag as 'latest' only for stable releases
    if ! echo "$TAG" | grep -qE '(alpha|beta|rc)'; then
      docker tag "$REGISTRY:$TAG" "$REGISTRY:latest"
    fi

- name: Push
  if: steps.docker-login.outcome == 'success'
  run: docker push "$REGISTRY" --all-tags

Registry URL pattern: {gitea-host}/{owner}/{repo}:{tag}

8. Release Versioning

Tag format	Example	Pre-release?	Docker `:latest`?
`v{major}.{minor}.{patch}`	`v0.2.0`	No	Yes
`v{major}.{minor}.{patch}-alpha.{n}`	`v0.2.0-alpha.1`	Yes	No
`v{major}.{minor}.{patch}-beta.{n}`	`v0.2.0-beta.2`	Yes	No
`v{major}.{minor}.{patch}-rc.{n}`	`v0.2.0-rc.1`	Yes	No

Release process:

# Stable release
git tag v0.2.0
git push origin v0.2.0

# Pre-release
git tag v0.2.0-alpha.1
git push origin v0.2.0-alpha.1

9. Gitea vs GitHub Actions Differences

Feature	GitHub Actions	Gitea Actions
Context prefix	`github.*`	`gitea.*`
Ref name	`${{ github.ref_name }}`	`${{ gitea.ref_name }}`
Server URL	`${{ github.server_url }}`	`${{ gitea.server_url }}`
Repository	`${{ github.repository }}`	`${{ gitea.repository }}`
Actor	`${{ github.actor }}`	`${{ gitea.actor }}`
SHA	`${{ github.sha }}`	`${{ gitea.sha }}`
Output vars	`$GITHUB_OUTPUT`	`$GITHUB_OUTPUT` (same)
Secrets	`${{ secrets.NAME }}`	`${{ secrets.NAME }}` (same)
Docker Buildx	Available	May not work (runner networking)

10. Checklist for New Projects

Create .gitea/workflows/test.yml — lint + test on push/PR
Create .gitea/workflows/release.yml — build + release on v* tag
Add GITEA_TOKEN secret to repository
Set up version detection in build scripts (tag → env → source)
Create build-dist.sh for Linux (venv + tarball)
Create build-dist-windows.sh for Windows (embedded Python + ZIP)
Create installer.nsi for Windows installer (optional)
Create Dockerfile for Docker builds (optional)
Configure pyproject.toml with [tool.ruff] and [tool.pytest]
Set up .pre-commit-config.yaml with ruff + black

11. Local Build Testing (Windows)

The CI builds on Linux, but you can build locally on Windows for faster iteration.

11.1. Prerequisites

Install NSIS (for installer builds):

# If winget is not on PATH, use the full path:
& "$env:LOCALAPPDATA\Microsoft\WindowsApps\winget.exe" install NSIS.NSIS
# Installs to: C:\Program Files (x86)\NSIS\makensis.exe

11.2. Build Steps

# 1. Build frontend
npm ci && npm run build

# 2. Build Windows distribution (from Git Bash)
bash build-dist-windows.sh v1.0.0

# 3. Build NSIS installer
"/c/Program Files (x86)/NSIS/makensis.exe" -DVERSION="1.0.0" installer.nsi
# Output: build/MediaServer-v1.0.0-setup.exe

11.3. Common Issues

Issue	Cause	Fix
`zip: command not found`	Git Bash doesn't include `zip`	Harmless — only affects the portable ZIP, not the installer. Install `zip` via MSYS2 if needed
`Exec expects 1 parameters, got 2`	`MUI_FINISHPAGE_RUN_PARAMETERS` quoting breaks NSIS `Exec`	Use `MUI_FINISHPAGE_RUN_FUNCTION` instead (see section 6)
`Error opening file for writing: ...python\\_asyncio.pyd`	Server is running and has DLLs locked	Stop the server before installing. Add `.onInit` file-lock check (see section 6)
App doesn't start after install (Launch checkbox)	VBS uses `python` but embedded Python isn't on PATH	Use embedded Python fallback in VBS (see Hidden Launcher section)
`winget` not recognized	`winget.exe` exists but isn't on shell PATH	Use full path: `$env:LOCALAPPDATA\Microsoft\WindowsApps\winget.exe`
NSIS warning: `install function not referenced`	`MUI_FINISHPAGE_RUN` define is missing	`MUI_FINISHPAGE_RUN_FUNCTION` still requires `MUI_FINISHPAGE_RUN` to be defined (controls checkbox visibility). Set it to `""`
`dist/` has stale files after code changes	`build-dist-windows.sh` copies from source at build time	Re-run the full build script, or manually copy changed files into `dist/`

11.4. Iterating on Installer Only

If you only changed installer.nsi (not app code), skip the full rebuild:

# Just rebuild the installer using existing dist/
"/c/Program Files (x86)/NSIS/makensis.exe" -DVERSION="1.0.0" installer.nsi

If you changed app code or dependencies, you must re-run build-dist-windows.sh first — the dist/ directory is a snapshot and won't pick up source changes automatically.

12. Troubleshooting

Running server blocks installation

See section 11.3. The .onInit function in section 6 shows how to detect a locked python.exe and prompt the user before proceeding.

Release already exists for tag

If the create-release job fails with KeyError: 'id', the Gitea API returned an error because a release already exists for that tag (e.g., from a previous failed run).

Prevention: The fallback logic in section 2.1 handles this automatically — if creation fails, it fetches the existing release by tag and reuses its ID. A ::warning:: annotation is emitted in the workflow log.

Re-triggering a failed release workflow:

# Option A: Delete and re-push the same tag
git push origin :refs/tags/v0.1.0-alpha.2   # delete remote tag
# Delete the release in Gitea UI or via API
git tag -f v0.1.0-alpha.2                    # recreate local tag
git push origin v0.1.0-alpha.2               # push again

# Option B: Just bump the version (simpler)
git tag v0.1.0-alpha.3
git push origin v0.1.0-alpha.3

19 KiB Raw Blame History