Skip to content

PyPI Publishing Setup Guide

This guide covers setting up the repository for automated publishing to PyPI via GitHub Actions.

Prerequisites

  1. PyPI Account: Create accounts on PyPI and Test PyPI
  2. GitHub Repository: Push the code to a GitHub repository
  3. API Tokens: Generate API tokens for both PyPI and Test PyPI

Step 1: Generate PyPI API Tokens

PyPI (Production)

  1. Go to PyPI Account Settings
  2. Click "Add API token"
  3. Set scope to "Entire account" (for initial setup)
  4. Copy the generated token (starts with pypi-)

Test PyPI (Testing)

  1. Go to Test PyPI Account Settings
  2. Click "Add API token"
  3. Set scope to "Entire account"
  4. Copy the generated token (starts with pypi-)

Step 2: Configure GitHub Secrets

In your GitHub repository settings:

  1. Go to Settings → Secrets and variables → Actions

  2. Add the following repository secrets:

PYPI_API_TOKEN=pypi-your-production-token-here
TEST_PYPI_API_TOKEN=pypi-your-test-token-here

Step 3: Set Up GitHub Environments

For additional security, create GitHub environments:

  1. Go to Settings → Environments
  2. Create two environments:
  3. pypi (for production releases)
  4. test-pypi (for test releases)
  5. Configure environment protection rules as needed

Step 4: Publishing Workflow

Test Release (Manual)

To test the publishing workflow:

  1. Go to Actions tab in GitHub
  2. Select Release workflow
  3. Click Run workflow
  4. Enter a test version (e.g., 1.0.0-test.1)
  5. This will publish to Test PyPI for verification

Production Release (Automatic)

For production releases:

  1. Update version in pyproject.toml

  2. Update CHANGELOG.md with release notes

  3. Commit changes to main branch

  4. Create and push a git tag:

git tag v1.0.0
git push origin v1.0.0

  1. GitHub Actions will automatically:

  2. Run tests

  3. Build the package
  4. Publish to PyPI
  5. Create a GitHub Release

Step 5: Verify Installation

After publishing, test the package installation:

# Install from PyPI
pip install katana-openapi-client

# Test import
python -c "from katana_public_api_client import KatanaClient; print('✅ Package installed successfully')"

Version Management

This project uses Semantic Versioning:

  • MAJOR version when you make incompatible API changes
  • MINOR version when you add functionality in a backwards compatible manner
  • PATCH version when you make backwards compatible bug fixes

Example version progression:

  • 1.0.0 → 1.0.1 (bug fix)
  • 1.0.1 → 1.1.0 (new feature)
  • 1.1.0 → 2.0.0 (breaking change)

Troubleshooting

Common Issues

  1. Token permissions: Ensure API tokens have correct scopes
  2. Package name conflicts: PyPI package names must be unique
  3. Version conflicts: Cannot upload same version twice to PyPI

Testing Locally

Test package building locally:

# Build package
uv build

# Check package
uv run twine check dist/*

# Test upload to Test PyPI (optional)
uv run twine upload --repository-url https://test.pypi.org/legacy/ dist/*

Security Best Practices

  1. Never commit API tokens to the repository
  2. Use environment protection rules for production releases
  3. Regularly rotate API tokens
  4. Review dependencies for security vulnerabilities
  5. Enable 2FA on PyPI accounts

Monitoring

After setup, monitor:

  • Package downloads on PyPI stats
  • Security alerts from GitHub
  • Dependency updates from Dependabot
  • CI/CD pipeline health

Support

For issues with: