markitect-main/PACKAGE_PUBLISHING.md

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

# 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

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

Build and Upload Packages

# 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)

# 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:

# 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

# Check if token is set
echo $GITEA_API_TOKEN

# Test authentication
python release.py registry

Upload Failures

# 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