# Package Publishing to Gitea

This document explains how to publish MarkiTect packages to the Gitea package registry.

## Prerequisites

1. **Gitea API Token**: Set the `GITEA_API_TOKEN` environment variable with your Gitea API token
2. **Repository Access**: The token must have write access to the repository's package registry

## Quick Setup

```bash
# Set your Gitea API token
export GITEA_API_TOKEN="your_gitea_api_token_here"

# Or add it to your shell profile
echo "export GITEA_API_TOKEN=your_token" >> ~/.bashrc
```

## Usage

### Check Registry Status

```bash
# Check registry configuration and authentication
make release-registry
# or
python release.py registry
```

### Build and Upload Packages

```bash
# Complete release workflow with Gitea upload
make release-publish-gitea VERSION=0.8.0
# or
python release.py publish --version 0.8.0 --to-gitea

# Upload existing packages
make release-upload-gitea
# or
python release.py upload

# Dry run (test without uploading)
python release.py upload --dry-run
```

### Traditional Release (without Gitea)

```bash
# Standard release without Gitea upload
make release-publish VERSION=0.8.0
python release.py publish --version 0.8.0
```

## Available Commands

### Makefile Targets

- `make release-registry` - Show Gitea package registry information
- `make release-upload-gitea` - Upload existing packages to Gitea
- `make release-publish-gitea VERSION=x.y.z` - Complete release + Gitea upload

### Python Script Commands

- `python release.py registry` - Show registry information
- `python release.py upload` - Upload packages to Gitea
- `python release.py upload --dry-run` - Test upload without uploading
- `python release.py publish --version x.y.z --to-gitea` - Release with Gitea upload

## Registry Information

- **Gitea URL**: http://92.205.130.254:32166
- **Repository**: coulomb/markitect_project
- **PyPI Registry URL**: http://92.205.130.254:32166/api/packages/coulomb/pypi
- **Package List URL**: http://92.205.130.254:32166/api/v1/packages/coulomb

## Installing from Gitea Registry

Once packages are published, users can install them using:

```bash
# Install from Gitea registry
pip install markitect --extra-index-url http://92.205.130.254:32166/api/packages/coulomb/pypi/simple/

# Or configure pip permanently
mkdir -p ~/.pip
cat >> ~/.pip/pip.conf << EOF
[global]
extra-index-url = http://92.205.130.254:32166/api/packages/coulomb/pypi/simple/
EOF
```

## Features

### Automatic Package Detection

The system automatically detects and uploads:
- **Wheel files** (`.whl`) - Binary distributions
- **Source distributions** (`.tar.gz`) - Source code packages

### Version Management with setuptools-scm

Versions are automatically determined by git tags:
- `v0.8.0` tag → `0.8.0` package version
- Development commits → `0.8.1.dev3+gcommithash` versions

### Error Handling

The system provides detailed error messages for:
- Missing authentication tokens
- Network connectivity issues
- Package upload failures
- Invalid package formats

## Troubleshooting

### Authentication Issues

```bash
# Check if token is set
echo $GITEA_API_TOKEN

# Test authentication
python release.py registry
```

### Upload Failures

```bash
# Test with dry run first
python release.py upload --dry-run

# Check package files exist
ls -la dist/

# Rebuild packages if needed
make release-build
```

### Network Issues

- Ensure Gitea server is accessible: `ping 92.205.130.254`
- Check firewall and proxy settings
- Verify Gitea is running on port 32166

## Development

The package registry functionality is implemented in:
- `gitea/package_registry.py` - Main package registry client
- `release.py` - Release script with Gitea integration
- `Makefile` - Convenient targets for package management

## Security Notes

- Never commit API tokens to version control
- Use environment variables or secure credential storage
- Tokens should have minimal required permissions
- Rotate tokens regularly for security