hitoshura25-pypi-workflow-generator 0.6.0

Dual-mode tool (MCP server + CLI) for generating GitHub Actions workflows

hitoshura25-pypi-workflow-generator

A dual-mode tool (MCP server + CLI) for generating GitHub Actions workflows for Python package publishing to PyPI.

Features

• ✅ Dual-Mode Operation: Works as MCP server for AI agents OR traditional CLI for developers
• ✅ PyPI Trusted Publishers: Secure publishing without API tokens
• ✅ No PAT Required: Uses default GitHub token - zero additional setup
• ✅ Safe Tag Creation: Tags only pushed AFTER successful PyPI publish (fail-safe design)
• ✅ Automated Versioning: Uses setuptools_scm for git-based versioning
• ✅ DRY Version Logic: Shared script eliminates duplicate version calculation code
• ✅ setuptools_scm Compatible: Proper version detection in reusable workflows via SETUPTOOLS_SCM_PRETEND_VERSION
• ✅ Pre-release Testing: Automatic TestPyPI publishing on pull requests with PEP 440 development versions
• ✅ Production Publishing: Manual releases via GitHub Actions UI
• ✅ Complete Project Initialization: Generates pyproject.toml and setup.py
• ✅ DRY Architecture: Reusable workflows for shared logic
• ✅ Code Quality Linting: Automatic Ruff linting in all generated workflows (always enabled)

Installation

pip install hitoshura25-pypi-workflow-generator

Package Naming Best Practices

Automatic Prefix Detection

By default, the generator adds your git username as a prefix to avoid PyPI naming conflicts. This follows PyPI best practices where package names should be unique and clearly identify the maintainer or organization.

Example:

# Your git config shows: github.com/jsmith/my-repo
$ hitoshura25-pypi-workflow-generator-init --package-name coolapp ...

# Auto-detects and creates:
# - PyPI Package: jsmith-coolapp
# - Import name: jsmith_coolapp

Detection Priority:

1. git config --get github.user (most specific)
2. GitHub username from remote URL (e.g., [e-mail]:username/repo.git)
3. git config --get user.name (sanitized)

Prefix Options

Auto-detect (default) - For personal projects:

hitoshura25-pypi-workflow-generator-init --package-name coolapp ...
# Creates: your-username-coolapp

Custom Prefix - For organization packages:

hitoshura25-pypi-workflow-generator-init --package-name coolapp --prefix acme ...
# Creates: acme-coolapp

No Prefix - For unique standalone tools:

hitoshura25-pypi-workflow-generator-init --package-name unique-name --no-prefix ...
# Creates: unique-name (check PyPI availability first!)

Why Prefixes?

PyPI has a flat namespace - only ONE package globally can have a given name. Prefixes help:

• ✅ Avoid naming conflicts with existing packages
• ✅ Group related packages by maintainer/organization
• ✅ Make ownership clear (e.g., acme-* packages belong to Acme Corp)
• ✅ Enable unique names without creative spelling

Configure Git (If Not Set)

# Set GitHub username (recommended)
git config --global github.user YOUR_GITHUB_USERNAME

# Or set git user.name (will be sanitized: "John Smith" → "john-smith")
git config --global user.name "Your Name"

Usage

This package can be used in three ways:

1. MCP Mode (For AI Agents)

For AI agents with MCP support (Claude Code, Continue.dev, Cline):

Add to claude_desktop_config.json or claude_config.json:

{
  "mcpServers": {
    "hitoshura25-pypi-workflow-generator": {
      "command": "mcp-hitoshura25-pypi-workflow-generator"
    }
  }
}

The agent can now use these tools:

• generate_workflows - Generate all 3 GitHub Actions workflows (no PAT required!)
• initialize_project - Create pyproject.toml and setup.py
• create_release - Create and push git release tags

Example conversation:

You: "Please set up a PyPI publishing workflow for my Python project"

Claude: I'll help you set up a complete PyPI publishing workflow.

[Calls initialize_project and generate_workflows tools]

✅ Created:
  - pyproject.toml
  - setup.py
  - .github/workflows/_reusable-test-build.yml
  - .github/workflows/release.yml
  - .github/workflows/test-pr.yml
  - scripts/calculate_version.sh

Next steps:
1. Configure Trusted Publishers on PyPI and TestPyPI
2. Create release via GitHub UI: Actions → "Release to PyPI"

2. CLI Mode (For Developers)

Initialize a new project:

hitoshura25-pypi-workflow-generator-init \
  --package-name my-awesome-package \
  --author "Your Name" \
  --author-email "[e-mail]" \
  --description "My awesome Python package" \
  --url "https://github.com/username/my-awesome-package" \
  --command-name my-command

Generate workflows:

hitoshura25-pypi-workflow-generator

This creates 3 workflow files and 1 script:

• .github/workflows/_reusable-test-build.yml - Shared test/build logic
• .github/workflows/release.yml - Manual releases via GitHub UI
• .github/workflows/test-pr.yml - PR testing to TestPyPI
• scripts/calculate_version.sh - Shared version calculation logic

Create a release:

# Via GitHub UI (recommended):
# 1. Go to Actions → "Release to PyPI"
# 2. Click "Run workflow"
# 3. Select version bump type (patch/minor/major)
# 4. Click "Run workflow"

3. Programmatic Use

from pypi_workflow_generator.generator import generate_workflows, initialize_project

# Initialize project
initialize_project(
    package_name="my-package",
    author="Your Name",
    author_email="[e-mail]",
    description="My package",
    url="https://github.com/user/repo",
    command_name="my-cmd"
)

# Generate workflows
generate_workflows(
    python_version="3.11",
    test_path="tests/",
    verbose_publish=True
)

Generated Files

This tool generates THREE GitHub Actions workflows and ONE shared script:

1. Release Workflow (release.yml)

Manual release workflow triggered via GitHub UI:

• Version Calculation: Automatically calculates next version (patch/minor/major)
• Safe Tag Creation: Creates tag locally first, tests/builds, then pushes only if successful
• Automated Testing: Runs pytest before publishing
• Package Building: Builds distribution packages
• PyPI Publishing: Publishes to production PyPI via Trusted Publishers
• GitHub Release: Creates GitHub Release with auto-generated notes
• No PAT Required: Uses default GITHUB_TOKEN
• setuptools_scm: Automatic versioning from git tags

2. PR Testing Workflow (test-pr.yml)

Automatically tests pull requests:

• Triggered on PRs: Runs automatically when PRs are opened/updated
• Automated Testing: Runs pytest on PR code
• Package Building: Builds distribution to verify it's buildable
• TestPyPI Publishing: Publishes pre-release to TestPyPI for testing
• Uses Reusable Workflow: Calls _reusable-test-build.yml for DRY

3. Reusable Test and Build Workflow (_reusable-test-build.yml)

Shared logic called by other workflows:

• Parameterized: Accepts Python version, test path, and artifact_version
• Test Pipeline: Checkout → setup → lint → test → build
• Code Quality: Runs Ruff linting (check + format) before tests (fail-fast)
• Artifact Export: Uploads built packages for use by caller workflows
• Version Override: Uses SETUPTOOLS_SCM_PRETEND_VERSION when artifact_version is provided
• Reusable: Single source of truth for test/build logic
• Note: Does NOT publish (publishing done by caller workflows for PyPI Trusted Publishing compatibility)

4. Version Calculation Script (scripts/calculate_version.sh)

Shared version calculation logic used by all workflows:

• Release Versions: Generates semantic versions with 'v' prefix (e.g., v1.2.3)
• RC Versions: Generates pre-release versions for PRs (e.g., 1.2.3rc12345)
• Parameterized: Accepts version type, bump type, PR number, and run number
• Testable: Can be run locally for testing version logic
• DRY: Eliminates ~80 lines of duplicate code across workflows

Creating Releases

Via GitHub Actions UI (only method):

1. Go to Actions tab in your repository
2. Select Release to PyPI workflow
3. Click Run workflow
4. Choose release type:
   • patch: Bug fixes (0.1.0 → 0.1.1)
   • minor: New features (0.1.1 → 0.2.0)
   • major: Breaking changes (0.2.0 → 1.0.0)
5. Click Run workflow

The workflow will:

1. ✅ Calculate the next version number
2. ✅ Check if tag already exists remotely
3. ✅ Run tests with calculated version
4. ✅ Build package with calculated version
5. ✅ Publish to PyPI (critical operation first)
6. ✅ Create and push tag to repository (only after successful publish)
7. ✅ Create GitHub Release with auto-generated notes

Key Benefit: Tags are only created/pushed AFTER successful PyPI publish. This fail-safe design ensures:

• If publish fails, no tag is created (easy retry with same version)
• If tag push fails, package is already on PyPI (users can install), easy manual fix
• No orphaned tags for failed releases

Version Calculation

The generator creates a shared scripts/calculate_version.sh script that handles version calculation for both PR and release workflows, eliminating duplicate code and ensuring consistency.

Version Formats

• Release versions: v1.2.3 (semantic versioning with 'v' prefix for git tags)
• Development versions: 1.2.3.dev123045 (PEP 440 dev releases for TestPyPI)
  • Format: {version}.dev{PR_NUMBER}{RUN_NUMBER_PADDED}
  • Example: PR #123, run #45 → 1.2.3.dev123045
  • Run number padded to 3 digits to prevent ambiguity

Script Usage

The script can be run locally for testing or is automatically called by workflows:

# Calculate release version (patch bump)
./scripts/calculate_version.sh --type release --bump patch
# Output: new_version=v1.2.4

# Calculate release version (minor bump)
./scripts/calculate_version.sh --type release --bump minor
# Output: new_version=v1.3.0

# Calculate development version for PR #123, run #45
./scripts/calculate_version.sh --type rc --bump patch --pr-number 123 --run-number 45
# Output: new_version=1.2.4.dev123045

# Show help
./scripts/calculate_version.sh --help

How It Works

1. Gets latest tag from git history (defaults to v0.0.0 if none exist)
2. Parses version components (major, minor, patch)
3. Applies bump according to --bump parameter:
   • major: 1.0.0 → 2.0.0 (breaking changes)
   • minor: 1.2.0 → 1.3.0 (new features)
   • patch: 1.2.3 → 1.2.4 (bug fixes)
4. Formats output based on --type:
   • release: Adds 'v' prefix for git tags → v1.2.4
   • rc: No prefix, adds '.dev' + PR# + padded run# → 1.2.4.dev123045
5. Outputs to GitHub Actions via $GITHUB_OUTPUT

setuptools_scm Integration

The workflows use SETUPTOOLS_SCM_PRETEND_VERSION to ensure correct version detection:

The Challenge:

• Reusable workflows run in fresh GitHub Actions runners
• Tags created in one job don't exist in other jobs/runners
• setuptools_scm normally detects version from git tags
• Without tags, version detection fails

The Solution:

1. Calculate version in dedicated job using calculate_version.sh
2. Pass version to reusable workflow via artifact_version input parameter
3. Build with override using SETUPTOOLS_SCM_PRETEND_VERSION environment variable:

   - name: Build package
     env:
       SETUPTOOLS_SCM_PRETEND_VERSION: ${{ inputs.artifact_version }}
     run: python -m build
   

4. setuptools_scm respects the override and uses provided version instead of git detection

This approach works perfectly because:

• ✅ Version calculation happens once in a job with git history
• ✅ Calculated version passes between jobs via artifacts/outputs
• ✅ Build uses explicit version, no git detection needed
• ✅ Works with PyPI Trusted Publishing (reusable workflows supported)

Why .dev Instead of rc?

Semantic Correctness:

• .dev versions = development/pre-alpha (perfect for PR testing)
• rc versions = release candidates (implies near-final release ready for production)
• PR testing is exploratory development work, not release preparation

PEP 440 Compliance:

• .dev versions are the Python standard for pre-release development work
• Properly sort before official releases: 1.2.3.dev1 < 1.2.3.dev100 < 1.2.3
• Compatible with all Python packaging tools (pip, setuptools, etc.)

No Ambiguity:

• Old format: 1.2.3rc12345 - impossible to determine where PR# ends and run# begins
• New format: 1.2.3.dev123045 - unambiguous (PR #123, run #45 padded to 3 digits)
• Padding to 3 digits prevents collisions between different PRs

Examples:

PR #5,    run #2   → 1.2.4.dev005002
PR #123,  run #45  → 1.2.4.dev123045
PR #1234, run #678 → 1.2.4.dev1234678

Why Padding Matters:

Without padding (old):
  PR #123, run #4   → 1.2.3rc1234
  PR #12,  run #34  → 1.2.3rc1234  ❌ COLLISION!
  PR #1,   run #234 → 1.2.3rc1234  ❌ COLLISION!

With padding (new):
  PR #123, run #4   → 1.2.3.dev123004  ✓
  PR #12,  run #34  → 1.2.3.dev012034  ✓
  PR #1,   run #234 → 1.2.3.dev001234  ✓

Why a Shared Script?

Before using a shared script, version calculation logic was duplicated between test-pr.yml and release.yml (~80 lines of duplicate bash code). The shared script provides:

• ✅ Single source of truth for all version logic
• ✅ Easier to maintain - changes in one place affect all workflows
• ✅ Testable - can run locally without GitHub Actions
• ✅ Consistent - same logic guarantees same results
• ✅ Extensible - easy to add new version formats or validation rules
• ✅ Self-documenting - includes --help flag with usage examples

Setting Up Trusted Publishers

The generated GitHub Actions workflows utilize PyPI Trusted Publishers for secure package publishing. This method enhances security by allowing your GitHub Actions workflow to authenticate with PyPI using OpenID Connect (OIDC) instead of requiring you to store sensitive API tokens as GitHub secrets.

Why Trusted Publishers?

• Enhanced Security: Eliminates the need to store PyPI API tokens, reducing the risk of token compromise.
• Best Practice: Recommended by PyPI for publishing from automated environments like GitHub Actions.

How to Set Up Trusted Publishers for Your Project:

Before your workflow can successfully publish to PyPI or TestPyPI, you must configure Trusted Publishers for your project on the respective PyPI instance.

1. Log in to PyPI/TestPyPI:

   • For TestPyPI: Go to https://test.pypi.org/ and log in.
   • For official PyPI: Go to https://pypi.org/ and log in.

2. Navigate to Your Project's Publishing Settings:

   • Go to your project's management page. The URL will typically look like: https://[test.]pypi.org/manage/project/<your-package-name>/settings/publishing/
   • Replace <your-package-name> with the actual name of your Python package (e.g., pypi-workflow-generator).

3. Add Trusted Publishers:

   • You need to add two publishers (one for production, one for testing)
   • Click on the "Add a new publisher" button.
   • Select "GitHub Actions" as the publisher type.
   • For PyPI (production releases):
     • Owner: Your GitHub username or organization (e.g., your-username)
     • Repository: Your repository name (e.g., my-awesome-package)
     • Workflow Name: release.yml
     • Environment (Optional): Leave blank
   • For TestPyPI (PR testing):
     • Owner: Same as above
     • Repository: Same as above
     • Workflow Name: test-pr.yml
     • Environment (Optional): Leave blank

   Important: Do NOT use _reusable-test-build.yml as the workflow name. PyPI Trusted Publishing does not support reusable workflows. The workflow name must be the file that contains the publish step (test-pr.yml or release.yml).

4. Save the Publishers: Confirm and save both publishers.

Once configured, your GitHub Actions workflows will be able to publish packages without needing any API tokens. No PAT or GitHub App setup required!

That's It!

With Trusted Publishers configured, you're ready to go. The workflows use GitHub's default GITHUB_TOKEN for all operations - no additional authentication setup needed.

CLI Options

hitoshura25-pypi-workflow-generator

Generate all 3 GitHub Actions workflows for PyPI publishing.

Usage:
  hitoshura25-pypi-workflow-generator [options]

Options:
  --python-version VERSION    Python version (default: 3.11)
  --test-path PATH            Path to tests (default: .)
  --verbose-publish           Enable verbose publishing

Generates:
  .github/workflows/_reusable-test-build.yml
  .github/workflows/release.yml
  .github/workflows/test-pr.yml

hitoshura25-pypi-workflow-generator-init

Initialize a new Python project with PyPI configuration.

Options:
  --package-name NAME         Package name (required)
  --author NAME               Author name (required)
  --author-email EMAIL        Author email (required)
  --description TEXT          Package description (required)
  --url URL                   Project URL (required)
  --command-name NAME         CLI command name (required)

MCP Server Details

The MCP server runs via stdio transport and provides three tools:

Tool: generate_workflows

• Generates all 3 GitHub Actions workflow files at once
• Creates: _reusable-test-build.yml, release.yml, and test-pr.yml
• Parameters: python_version, test_path, verbose_publish

Tool: initialize_project

• Creates pyproject.toml and setup.py
• Parameters: package_name, author, author_email, description, url, command_name

Tool: create_release

• Creates and pushes git tag
• Parameters: version

See MCP-USAGE.md for detailed MCP configuration and usage.

Interface Differences

The package provides two interfaces with slightly different APIs for different use cases:

CLI vs MCP: Release Creation

CLI Mode (pypi-release):

• Uses semantic versioning keywords: major, minor, patch
• Automatically increments version from latest git tag
• Convenience for developers who want simple versioning

pypi-release patch      # Creates v1.0.1 (if current is v1.0.0)
pypi-release minor      # Creates v1.1.0
pypi-release major      # Creates v2.0.0

MCP Mode (create_release tool):

• Accepts explicit version strings: v1.0.0, v2.5.3, etc.
• Direct control over version numbers
• Flexibility for AI agents to determine versions programmatically

{
  "version": "v1.0.0"
}

Why the difference? The CLI optimizes for human convenience (automatic incrementing), while MCP optimizes for programmatic control (explicit versions).

Entry Point Naming Convention

The MCP server uses the mcp- prefix (industry standard for MCP tools):

• mcp-hitoshura25-pypi-workflow-generator - Follows MCP ecosystem naming
• Makes it discoverable when searching for MCP servers
• Clearly distinguishes server mode from CLI mode

All other commands use the package prefix for CLI operations:

• hitoshura25-pypi-workflow-generator
• hitoshura25-pypi-workflow-generator-init
• vmenon25-pypi-release

Architecture

User/AI Agent
      │
      ├─── MCP Mode ────────> server.py (MCP protocol)
      │                           │
      ├─── CLI Mode ────────> main.py / init.py / create_release.py
      │                           │
      └─── Programmatic ────> __init__.py
                                  │
                    All modes use shared core:
                                  ▼
                            generator.py
                      (Business logic)

Dogfooding

This project uses itself to generate its own GitHub Actions workflows! The workflow files at:

• .github/workflows/_reusable-test-build.yml
• .github/workflows/release.yml
• .github/workflows/test-pr.yml

Were all created by running:

hitoshura25-pypi-workflow-generator \
  --python-version 3.11 \
  --test-path hitoshura25_pypi_workflow_generator/

All workflows include Ruff linting by default! Every PR and release is automatically checked for code quality before tests run.

This ensures:

• ✅ The tool actually works (we use it ourselves)
• ✅ All features including linting are tested in production
• ✅ The templates stay consistent with real-world usage
• ✅ We practice what we preach
• ✅ Users can see real examples of the generated output
• ✅ Our codebase maintains high code quality standards

Check the workflow file headers to see the exact command used. Try creating a release using the GitHub Actions UI!

Code Quality with Ruff

All generated workflows include automatic code linting using Ruff, a fast, modern Python linter written in Rust.

What's Included

When you generate workflows, your project gets:

1. Automatic Linting in CI/CD: Every PR and release runs ruff check and ruff format --check
2. Fail-Fast Approach: Linting runs before tests to catch issues early
3. Comprehensive Rules: Sensible defaults covering code style, bugs, and best practices
4. Ruff Configuration: Complete [tool.ruff] section added to generated pyproject.toml

Linting is Always Enabled

Important: Linting is always included in generated workflows. This opinionated approach:

• ✅ Promotes best practices from day one
• ✅ Keeps code quality consistent across all generated projects
• ✅ Reduces bugs and improves code readability
• ✅ Simplifies the tool (no configuration flags needed)

If you don't want linting, you can manually delete the "Lint with Ruff" step from .github/workflows/_reusable-test-build.yml after generation.

Customizing Ruff Configuration

The generated pyproject.toml includes a comprehensive Ruff configuration that you can customize:

[tool.ruff]
# Line length to match Black default
line-length = 88

# Target Python version
target-version = "py38"

[tool.ruff.lint]
# Enabled rule categories
select = ["E", "F", "W", "I", "N", "UP", "B", "A", "C4", "DTZ", "T10", "EM", "ISC", "ICN", "PIE", "PT", "Q", "RET", "SIM", "TID", "ARG", "PTH", "PD", "PL", "NPY", "PERF", "RUF"]
ignore = []

# Allow fix for all enabled rules (when `--fix` is used)
fixable = ["ALL"]
unfixable = []

[tool.ruff.format]
# Use Black-compatible formatting
quote-style = "double"
indent-style = "space"

Note: The default configuration enables comprehensive linting without ignores. For new projects, this encourages best practices from the start (including using pathlib instead of os.path).

Common Customizations:

Ignore specific rules:

[tool.ruff.lint]
ignore = [
    "E501",  # Line too long (let formatter handle)
    "D",     # Disable all docstring rules
]

Per-file ignores (useful for tests):

[tool.ruff.lint.per-file-ignores]
"tests/**/*.py" = ["S101"]  # Allow assert in tests
"__init__.py" = ["F401"]    # Allow unused imports in __init__

Minimal configuration (only errors):

[tool.ruff.lint]
select = ["E", "F"]  # Only pycodestyle errors and Pyflakes
ignore = []  # No ignores needed for minimal rules

Strict configuration (all rules):

[tool.ruff.lint]
select = ["ALL"]  # Enable all available rules
ignore = ["D"]    # Except docstrings

See the Ruff Rules Reference for all available rules.

Running Ruff Locally

To run linting locally before pushing:

# Install Ruff (usually in dev dependencies)
pip install ruff

# Check for linting issues
ruff check .

# Check formatting
ruff format --check .

# Auto-fix issues (when possible)
ruff check --fix .

# Auto-format code
ruff format .

Pro tip: Add a pre-commit hook to run linting automatically:

# Install pre-commit
pip install pre-commit

# Create .pre-commit-config.yaml
cat > .pre-commit-config.yaml <<EOF
repos:
  - repo: https://github.com/astral-sh/ruff-pre-commit
    # Check for latest: https://github.com/astral-sh/ruff-pre-commit/releases
    rev: v0.8.6  # Replace with latest version
    hooks:
      - id: ruff
        args: [--fix]
      - id: ruff-format
EOF

# Install the hooks
pre-commit install

Troubleshooting Common Linting Issues

Issue: "Line too long" errors

# Solution 1: Let Ruff format handle it
ruff format .

# Solution 2: Ignore E501 in pyproject.toml
[tool.ruff.lint]
ignore = ["E501"]

Issue: "Imported but unused" in __init__.py

# Solution: Add per-file ignore
[tool.ruff.lint.per-file-ignores]
"__init__.py" = ["F401"]

Issue: "Use of assert detected" in tests

# Solution: Allow assert in test files
[tool.ruff.lint.per-file-ignores]
"tests/**/*.py" = ["S101"]

Issue: Linting too strict for legacy code

# Solution: Start with minimal rules, add incrementally
[tool.ruff.lint]
select = ["E", "F"]  # Start with just errors
# Later add: ["E", "F", "W", "I"]  # Add warnings and imports
# Eventually: Full rule set

Issue: CI fails but local linting passes

# Ensure same Ruff version
pip install ruff --upgrade

# Check exact commands CI uses (from _reusable-test-build.yml):
ruff check .
ruff format --check .

Why Ruff?

• Fast: 10-100x faster than traditional Python linters (written in Rust)
• All-in-one: Replaces Flake8, Black, isort, pyupgrade, and more
• Modern: Active development, excellent editor integration
• Industry Standard: Widely adopted by major Python projects
• Simple: Minimal configuration required

Development

# Clone repository
git clone https://github.com/hitoshura25/pypi-workflow-generator.git
cd pypi-workflow-generator

# Install dependencies
pip install .[test,dev]

# Run linting (required before committing)
ruff check .
ruff format --check .

# Auto-fix linting issues
ruff check --fix .
ruff format .

# Run tests
pytest

# Build package
python -m build

Important: All code must pass linting before being committed. The CI/CD pipeline will reject PRs that don't pass ruff check and ruff format --check.

Contributing

Contributions welcome! Please open an issue or PR.

License

Apache-2.0

Links

• Repository: https://github.com/hitoshura25/pypi-workflow-generator
• Issues: https://github.com/hitoshura25/pypi-workflow-generator/issues
• PyPI: https://pypi.org/project/hitoshura25-pypi-workflow-generator/