add comprehensive CI/CD package registry setup documentation

dev_notes/ci_cd_package_registry_setup.md

@@ -0,0 +1,186 @@
+# CI/CD Package Registry Setup
+
+This document summarizes the implementation of Forgejo Package Registry integration for Deb-Mock, based on the successful implementation in bootc-deb.
+
+## Overview
+
+We've successfully implemented a comprehensive CI/CD pipeline that builds Debian packages and uploads them to Forgejo's built-in Debian Package Registry, following the pattern established by the bootc-deb project.
+
+## Implementation Details
+
+### 1. Enhanced Build Workflow
+
+The `.forgejo/workflows/build-deb.yml` workflow now includes:
+
+#### **Package Building**
+- ✅ **Debian package creation** using `dpkg-buildpackage`
+- ✅ **Version extraction** from `setup.py` (avoiding module imports)
+- ✅ **Binary-only package** support (no .dsc file required)
+- ✅ **Proper dependency handling** with `dh-python`
+
+#### **Release Assets Creation**
+```yaml
+- name: Create release assets
+  run: |
+    mkdir -p release-assets
+    cp ../deb-mock_*.deb release-assets/
+    cp ../deb-mock_*.changes release-assets/
+    
+    # Create build summary
+    echo "Deb-Mock Package Build Summary" > release-assets/BUILD_SUMMARY.txt
+    echo "Build Date: $(date)" >> release-assets/BUILD_SUMMARY.txt
+    echo "Version: $VERSION" >> release-assets/BUILD_SUMMARY.txt
+```
+
+#### **Forgejo Package Registry Upload**
+```yaml
+- name: Upload to Forgejo Debian Package Registry
+  if: startsWith(github.ref, 'refs/tags/')
+  run: |
+    for deb_file in ../deb-mock_*.deb; do
+      if [ -f "$deb_file" ]; then
+        http_code=$(curl -s -o /dev/null -w "%{http_code}" \
+          --user "robojerk:${{ secrets.ACCESS_TOKEN }}" \
+          --upload-file "$deb_file" \
+          "https://git.raines.xyz/api/packages/robojerk/debian/pool/unstable/main/upload")
+        
+        if [ "$http_code" = "201" ]; then
+          echo "✅ Upload SUCCESS for $deb_file"
+        fi
+      fi
+    done
+```
+
+### 2. Comparison with bootc-deb
+
+| Feature | bootc-deb | deb-mock | Status |
+|---------|-----------|----------|--------|
+| **Package Building** | ✅ Rust/Cargo | ✅ Python/setuptools | ✅ Implemented |
+| **Version Extraction** | ✅ From Cargo.toml | ✅ From setup.py | ✅ Implemented |
+| **Release Assets** | ✅ BUILD_SUMMARY.txt | ✅ BUILD_SUMMARY.txt | ✅ Implemented |
+| **Registry Upload** | ✅ Forgejo API | ✅ Forgejo API | ✅ Implemented |
+| **ACCESS_TOKEN** | ✅ Required | ✅ Required | ✅ Implemented |
+| **Distribution** | noble | unstable | ✅ Implemented |
+| **Error Handling** | ✅ HTTP codes | ✅ HTTP codes | ✅ Implemented |
+| **Success Summary** | ✅ Next steps | ✅ Next steps | ✅ Implemented |
+
+### 3. Key Differences
+
+#### **Distribution Choice**
+- **bootc-deb**: Uses `noble` (Ubuntu 24.04)
+- **deb-mock**: Uses `unstable` (Debian unstable)
+
+#### **Package Type**
+- **bootc-deb**: Rust binary packages
+- **deb-mock**: Python packages with dh-python
+
+#### **Build Process**
+- **bootc-deb**: `cargo build` + `dpkg-buildpackage`
+- **deb-mock**: `pip install` + `dpkg-buildpackage`
+
+## Setup Requirements
+
+### 1. Repository Secrets
+
+To enable package uploads, add the following secret to your repository:
+
+**Name**: `ACCESS_TOKEN`  
+**Value**: Your Personal Access Token with:
+- `repo` (Full control of private repositories)
+- `write:packages` (Write packages)
+- `read:packages` (Read packages)
+
+### 2. Token Setup Instructions
+
+1. Go to repository settings: `https://git.raines.xyz/robojerk/deb-mock/settings`
+2. Find "Secrets" or "Repository secrets" section
+3. Add new secret:
+   - **Name**: `ACCESS_TOKEN`
+   - **Value**: Your Personal Access Token
+
+## Usage
+
+### 1. Automatic Uploads
+
+Packages are automatically uploaded when:
+- A tag is pushed (e.g., `v1.0.0`)
+- The `ACCESS_TOKEN` secret is configured
+
+### 2. Manual Installation
+
+Users can install packages from the registry:
+
+```bash
+# Add the repository
+wget -O - https://git.raines.xyz/api/packages/robojerk/debian/gpg.key | sudo apt-key add -
+echo 'deb [signed-by=/usr/share/keyrings/forgejo-robojerk.gpg] https://git.raines.xyz/api/packages/robojerk/debian unstable main' | sudo tee /etc/apt/sources.list.d/deb-mock.list
+sudo apt update
+
+# Install deb-mock
+sudo apt install -y deb-mock
+```
+
+### 3. Package Location
+
+Uploaded packages are available at:
+- **Registry**: `https://git.raines.xyz/api/packages/robojerk/debian`
+- **Repository Page**: `https://git.raines.xyz/robojerk/deb-mock/packages`
+
+## Benefits
+
+### 1. **Automated Distribution**
+- No manual package uploads required
+- Consistent package versions
+- Automatic dependency resolution
+
+### 2. **User Experience**
+- Simple `apt install` commands
+- Automatic updates via `apt upgrade`
+- GPG-signed packages for security
+
+### 3. **CI/CD Integration**
+- Seamless integration with Forgejo Actions
+- Build artifacts automatically available
+- Release management through tags
+
+## Troubleshooting
+
+### Common Issues
+
+1. **"ACCESS_TOKEN is not set"**
+   - Add the `ACCESS_TOKEN` secret to repository settings
+   - Ensure token has correct permissions
+
+2. **"HTTP 409 Conflict"**
+   - Package already exists in registry
+   - Normal behavior for duplicate uploads
+
+3. **"HTTP 401 Unauthorized"**
+   - Check token permissions
+   - Verify token is valid and not expired
+
+### Debug Commands
+
+```bash
+# Test API access
+curl -u "robojerk:$ACCESS_TOKEN" \
+  "https://git.raines.xyz/api/packages/robojerk/debian"
+
+# List packages
+curl -u "robojerk:$ACCESS_TOKEN" \
+  "https://git.raines.xyz/api/packages/robojerk/debian/packages"
+```
+
+## Next Steps
+
+1. **Set up ACCESS_TOKEN secret** in repository settings
+2. **Create and push a tag** to trigger the first upload
+3. **Verify package appears** in the registry
+4. **Test installation** on a clean system
+5. **Update documentation** with installation instructions
+
+## References
+
+- [bootc-deb build-packages.yml](https://git.raines.xyz/robojerk/bootc-deb/src/branch/main/.forgejo/workflows/build-packages.yml)
+- [Forgejo Package Registry Documentation](https://docs.gitea.com/usage/packages/overview)
+- [Debian Package Registry Guide](https://docs.gitea.com/usage/packages/debian)