deb-mock/dev_notes/ci_cd_package_registry_setup.md

# CI/CD Package Registry Setup

This document summarizes the implementation of Forgejo Package Registry integration for 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 ../mock_*.deb release-assets/
    cp ../mock_*.changes release-assets/
    
    # Create build summary
    echo "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 ../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 | 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)
- **mock**: Uses `unstable` (Debian unstable)

#### **Package Type**
- **bootc-deb**: Rust binary packages
- **mock**: Python packages with dh-python

#### **Build Process**
- **bootc-deb**: `cargo build` + `dpkg-buildpackage`
- **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/mock.list
sudo apt update

# Install mock
sudo apt install -y 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)