From 0222bdbcbaa781c9a2a4cdb1daa22cd89cf5e35d Mon Sep 17 00:00:00 2001
From: Jason Woltje <jason@diversecanvas.com>
Date: Sat, 14 Feb 2026 22:43:39 -0600
Subject: [PATCH] chore(#1): Add PyPI publish step and Gitea registry install
 instructions

- Add publish step to .woodpecker.yml that builds wheel/sdist and uploads
  to git.mosaicstack.dev PyPI registry via twine (gated on all quality
  checks, only on main/develop/tags)
- Add link-package step to associate PyPI package with the repository
- Update README and integration guide with Gitea registry install
  instructions (pip --index-url, uv --index-url, pyproject.toml config)
- Version check prevents re-publishing existing versions

Refs #1

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 .woodpecker.yml           | 72 +++++++++++++++++++++++++++++++++++++++
 README.md                 | 27 +++++++++++++--
 docs/integration-guide.md | 21 ++++++++++--
 3 files changed, 115 insertions(+), 5 deletions(-)

diff --git a/.woodpecker.yml b/.woodpecker.yml
index 11ee104..33c5b64 100644
--- a/.woodpecker.yml
+++ b/.woodpecker.yml
@@ -55,3 +55,75 @@ steps:
         uv run pytest --cov=src/mosaicstack_telemetry --cov-report=term-missing --cov-fail-under=85
     depends_on:
       - install
+
+  publish:
+    image: *uv_image
+    environment:
+      GITEA_USER:
+        from_secret: gitea_username
+      GITEA_TOKEN:
+        from_secret: gitea_token
+    commands:
+      - |
+        uv sync --all-extras --frozen
+        CURRENT=$(python3 -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+        echo "Building version $$CURRENT..."
+        uv build
+        uv pip install twine
+        PUBLISHED=$(pip index versions mosaicstack-telemetry \
+          --index-url "https://$$GITEA_USER:$$GITEA_TOKEN@git.mosaicstack.dev/api/packages/mosaic/pypi/simple/" \
+          2>/dev/null | grep -oP '\(\K[^)]+' || echo "0.0.0")
+        if [ "$$CURRENT" = "$$PUBLISHED" ]; then
+          echo "Version $$CURRENT already published, skipping"
+        else
+          echo "Publishing $$CURRENT (was $$PUBLISHED)..."
+          twine upload \
+            --repository-url "https://git.mosaicstack.dev/api/packages/mosaic/pypi" \
+            --username "$$GITEA_USER" \
+            --password "$$GITEA_TOKEN" \
+            dist/*
+          echo "Published mosaicstack-telemetry $$CURRENT"
+        fi
+    when:
+      - branch: [main, develop]
+        event: [push, manual, tag]
+    depends_on:
+      - lint
+      - typecheck
+      - security-bandit
+      - security-audit
+      - test
+
+  link-package:
+    image: alpine:3
+    environment:
+      GITEA_TOKEN:
+        from_secret: gitea_token
+    commands:
+      - apk add --no-cache curl
+      - sleep 5
+      - |
+        set -e
+        for attempt in 1 2 3; do
+          STATUS=$$(curl -s -o /dev/null -w "%{http_code}" -X POST \
+            -H "Authorization: token $$GITEA_TOKEN" \
+            "https://git.mosaicstack.dev/api/v1/packages/mosaic/pypi/mosaicstack-telemetry/-/link/telemetry-client-py")
+          if [ "$$STATUS" = "201" ] || [ "$$STATUS" = "204" ]; then
+            echo "Package linked to repository"
+            exit 0
+          elif [ "$$STATUS" = "400" ]; then
+            echo "Package already linked (OK)"
+            exit 0
+          elif [ $$attempt -lt 3 ]; then
+            echo "Package not found yet, retrying in 5s (attempt $$attempt/3)..."
+            sleep 5
+          else
+            echo "Failed to link package (status $$STATUS)"
+            exit 1
+          fi
+        done
+    when:
+      - branch: [main, develop]
+        event: [push, manual, tag]
+    depends_on:
+      - publish
diff --git a/README.md b/README.md
index de3f42a..54196bc 100644
--- a/README.md
+++ b/README.md
@@ -6,10 +6,31 @@ Python client SDK for [Mosaic Stack Telemetry](https://github.com/mosaicstack/te
 
 ## Installation
 
+Install from the Mosaic Stack package registry:
+
 ```bash
-pip install mosaicstack-telemetry
-# or
-uv add mosaicstack-telemetry
+pip install mosaicstack-telemetry --index-url https://git.mosaicstack.dev/api/packages/mosaic/pypi/simple/
+```
+
+Or with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv add mosaicstack-telemetry --index-url https://git.mosaicstack.dev/api/packages/mosaic/pypi/simple/
+```
+
+To avoid passing `--index-url` every time, add the registry to your project's `pyproject.toml`:
+
+```toml
+[[tool.uv.index]]
+name = "mosaic"
+url = "https://git.mosaicstack.dev/api/packages/mosaic/pypi/simple/"
+```
+
+Or to `pip.conf` / `~/.config/pip/pip.conf`:
+
+```ini
+[global]
+extra-index-url = https://git.mosaicstack.dev/api/packages/mosaic/pypi/simple/
 ```
 
 Runtime dependencies: `httpx` and `pydantic`.
diff --git a/docs/integration-guide.md b/docs/integration-guide.md
index 90d8503..cd8eb4e 100644
--- a/docs/integration-guide.md
+++ b/docs/integration-guide.md
@@ -6,14 +6,31 @@ This guide covers installing and integrating `mosaicstack-telemetry` into Python
 
 ## Installation
 
+Install from the Mosaic Stack package registry:
+
 ```bash
-pip install mosaicstack-telemetry
+pip install mosaicstack-telemetry --index-url https://git.mosaicstack.dev/api/packages/mosaic/pypi/simple/
 ```
 
 Or with [uv](https://docs.astral.sh/uv/):
 
 ```bash
-uv add mosaicstack-telemetry
+uv add mosaicstack-telemetry --index-url https://git.mosaicstack.dev/api/packages/mosaic/pypi/simple/
+```
+
+To avoid repeating the index URL, configure it in your project's `pyproject.toml`:
+
+```toml
+[[tool.uv.index]]
+name = "mosaic"
+url = "https://git.mosaicstack.dev/api/packages/mosaic/pypi/simple/"
+```
+
+Or in `pip.conf` (`~/.config/pip/pip.conf` on Linux):
+
+```ini
+[global]
+extra-index-url = https://git.mosaicstack.dev/api/packages/mosaic/pypi/simple/
 ```
 
 **Requirements:** Python 3.10+. Runtime dependencies: `httpx` and `pydantic`.