# 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
- ✅ **Automated Versioning**: Uses setuptools_scm for git-based versioning
- ✅ **Pre-release Testing**: Automatic TestPyPI publishing on pull requests
- ✅ **Production Publishing**: Automatic PyPI publishing on version tags
- ✅ **Complete Project Initialization**: Generates pyproject.toml and setup.py
- ✅ **Release Management**: Simple git tag creation for triggering releases
## Installation
```bash
pip install pypi-workflow-generator
```
## 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`**:
```json
{
"mcpServers": {
"pypi-workflow-generator": {
"command": "mcp-pypi-workflow-generator"
}
}
}
```
The agent can now use these tools:
- `generate_workflow` - Generate GitHub Actions workflows (both publishing and release)
- `generate_release_workflow` - Generate only the release creation workflow **NEW!**
- `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_workflow tools]
✅ Created:
- pyproject.toml
- setup.py
- .github/workflows/pypi-publish.yml
Next steps:
1. Configure Trusted Publishers on PyPI
2. Create a release: pypi-release patch
```
### 2. CLI Mode (For Developers)
**Initialize a new project**:
```bash
pypi-workflow-generator-init \
--package-name my-awesome-package \
--author "Your Name" \
--author-email "your.email@example.com" \
--description "My awesome Python package" \
--url "https://github.com/username/my-awesome-package" \
--command-name my-command
```
**Generate workflow**:
```bash
pypi-workflow-generator --python-version 3.11
```
**Create a release**:
```bash
pypi-release patch # or 'minor' or 'major'
```
### 3. Programmatic Use
```python
from pypi_workflow_generator import generate_workflow, initialize_project
# Initialize project
initialize_project(
package_name="my-package",
author="Your Name",
author_email="your@email.com",
description="My package",
url="https://github.com/user/repo",
command_name="my-cmd"
)
# Generate workflow
generate_workflow(
python_version="3.11",
release_on_main_push=False
)
```
## Generated Workflows
This tool now generates **TWO** GitHub Actions workflows by default:
### 1. PyPI Publishing Workflow (`pypi-publish.yml`)
Handles automated package publishing:
- **Automated Testing**: Runs pytest on every PR and release
- **Pre-release Publishing**: TestPyPI publishing on PRs with version like `1.0.0.dev123`
- **Production Publishing**: PyPI publishing on version tags
- **Trusted Publishers**: No API tokens needed (OIDC authentication)
- **setuptools_scm**: Automatic versioning from git tags
### 2. Release Creation Workflow (`create-release.yml`) **NEW!**
Enables manual release creation via GitHub UI:
- **Manual Trigger**: Click a button in GitHub Actions to create releases
- **Automatic Version Calculation**: Choose major/minor/patch, version is calculated automatically
- **Git Tag Creation**: Creates and pushes version tags
- **GitHub Releases**: Auto-generates release notes from commits
- **Triggers Publishing**: Tag push automatically triggers the PyPI publish workflow
## Creating Releases
You have **two ways** to create releases:
### Option 1: GitHub Actions UI (Recommended) **NEW!**
**Prerequisites**: Create a `RELEASE_PAT` secret (see [Setting Up Automated Release Publishing](#setting-up-automated-release-publishing))
1. Go to **Actions** tab in your repository
2. Select **Create Release** 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. (Optional) Specify custom token secret name if not using `RELEASE_PAT`
6. Click **Run workflow**
The workflow will:
- Calculate the next version number
- Create and push a git tag
- Create a GitHub Release with auto-generated notes
- **Automatically trigger the PyPI publish workflow** (requires RELEASE_PAT)
- Publish your package to PyPI
**Benefits**: Works from anywhere, full automation, easy for AI agents to use.
### Option 2: CLI (Local)
```bash
pypi-release patch # or minor, major
```
This creates and pushes the tag locally, which triggers the publish workflow.
## Workflow Generation Options
```bash
# Generate both workflows (default)
pypi-workflow-generator --python-version 3.11
# Generate only PyPI publishing workflow
pypi-workflow-generator --skip-release-workflow
# Generate only release creation workflow
pypi-workflow-generator-release
```
## Setting Up Trusted Publishers
The generated GitHub Actions workflow (`pypi-publish.yml`) utilizes [PyPI Trusted Publishers](https://docs.pypi.org/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 a New Trusted Publisher:**
- Click on the "Add a new publisher" button.
- Select "GitHub Actions" as the publisher type.
- Provide the following details:
- **Owner:** The GitHub username or organization that owns your repository (e.g., `hitoshura25`).
- **Repository:** The name of your GitHub repository (e.g., `pypi-workflow-generator`).
- **Workflow Name:** The name of your workflow file (e.g., `pypi-publish.yml`).
- **Environment (Optional):** If your GitHub Actions workflow uses a specific environment, specify its name here. Otherwise, leave it blank.
4. **Save the Publisher:** Confirm and save the new publisher.
Once configured, your GitHub Actions workflow will be able to publish packages without needing `PYPI_API_TOKEN` or `TEST_PYPI_API_TOKEN` secrets.
## Setting Up Automated Release Publishing
### Why You Need a Personal Access Token
GitHub Actions workflows triggered by the default `GITHUB_TOKEN` cannot trigger other workflows (security feature to prevent infinite loops). To enable the `create-release.yml` workflow to automatically trigger `pypi-publish.yml` after creating a release tag, you need to provide a Personal Access Token (PAT) with appropriate permissions.
**Without a PAT:** The create-release workflow will successfully create tags and GitHub Releases, but the PyPI publish workflow won't trigger automatically. You would need to manually trigger it.
**With a PAT:** Full automation - create a release via GitHub UI, and your package automatically publishes to PyPI.
### Creating the Required PAT
1. **Generate a Personal Access Token**:
- Go to GitHub Settings → Developer settings → [Personal access tokens → Tokens (classic)](https://github.com/settings/tokens/new)
- Click "Generate new token (classic)"
- Give it a descriptive name: `Release Automation Token for <repo-name>`
- Set expiration (recommended: 1 year, with calendar reminder to rotate)
- Select scope: **repo** (full control of private repositories)
- Click "Generate token"
- **Copy the token immediately** (you won't see it again)
2. **Add Token to Repository Secrets**:
- Go to your repository → Settings → Secrets and variables → Actions
- Click "New repository secret"
- Name: `RELEASE_PAT`
- Value: Paste the token you copied
- Click "Add secret"
3. **Verify Setup**:
- Go to Actions tab → Create Release workflow → Run workflow
- Select release type (patch/minor/major)
- Leave token secret name as default (`RELEASE_PAT`)
- The workflow should complete successfully
- The PyPI publish workflow should trigger automatically
- Your package should be published to PyPI
### Using a Custom Token Name (Optional)
If your organization uses a different secret name (e.g., `GITHUB_ORG_TOKEN`), you can specify it when running the workflow:
1. Go to Actions → Create Release
2. Click "Run workflow"
3. Fill in:
- **Release type**: patch/minor/major
- **Token secret name**: `GITHUB_ORG_TOKEN` (or your custom name)
### Security Considerations
- **Token Scope**: The PAT needs `repo` scope to push tags and trigger workflows
- **Token Rotation**: Set expiration dates and rotate tokens regularly (recommended: annually)
- **Access Control**: Only repository admins can add/view secrets
- **Audit Trail**: GitHub logs all token usage in the repository audit log
### Troubleshooting
**Workflow fails with "Secret 'RELEASE_PAT' not found"**
- You haven't created the PAT or added it to repository secrets
- Follow the steps above to create and add the token
**PyPI publish workflow still doesn't trigger**
- Verify the PAT has `repo` scope (not just `public_repo`)
- Check that the token hasn't expired
- Ensure the token is added to repository secrets (not environment secrets)
**Alternative: Use CLI Method**
If you prefer not to set up a PAT, you can create releases locally using the CLI:
```bash
pypi-release patch # This runs on your machine, no PAT needed
```
The CLI method pushes tags from your local machine, which doesn't have the GitHub Actions token limitation.
## CLI Options
### `pypi-workflow-generator`
Generate GitHub Actions workflows for PyPI publishing (generates both workflows by default).
```
Options:
--python-version VERSION Python version (default: 3.11)
--output-filename NAME Workflow filename (default: pypi-publish.yml)
--release-on-main-push Trigger release on main branch push
--test-path PATH Path to tests (default: .)
--verbose-publish Enable verbose publishing
--skip-release-workflow Only generate pypi-publish.yml (skip create-release.yml)
```
### `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)
```
### `pypi-release`
Create and push a git release tag (local CLI method).
```
Usage:
pypi-release {major,minor,patch} [--overwrite]
Arguments:
{major,minor,patch} The type of release (major, minor, or patch)
Options:
--overwrite Overwrite an existing tag
```
**Note**: The CLI uses semantic versioning (major/minor/patch) for convenience. The MCP tool `create_release` accepts explicit version strings (e.g., "v1.0.0") for flexibility. See [Interface Differences](#interface-differences) below.
### `pypi-workflow-generator-release` **NEW!**
Generate only the release creation workflow.
```
Options:
--output-filename NAME Workflow filename (default: create-release.yml)
```
Use this if you already have a PyPI publishing workflow and only want to add the release creation workflow.
## MCP Server Details
The MCP server runs via stdio transport and provides four tools:
**Tool: `generate_workflow`**
- Generates GitHub Actions workflow files (both publishing and release by default)
- Parameters: python_version, output_filename, release_on_main_push, test_path, verbose_publish, include_release_workflow
**Tool: `generate_release_workflow`** **NEW!**
- Generates only the release creation workflow
- Parameters: output_filename
**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](./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
```bash
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
```json
{
"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-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 `pypi-` prefix for CLI operations:
- `pypi-workflow-generator`
- `pypi-workflow-generator-init`
- `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/pypi-publish.yml`
- `.github/workflows/create-release.yml`
Were both created by running:
```bash
pypi-workflow-generator \
--python-version 3.11 \
--test-path pypi_workflow_generator/ \
--verbose-publish
```
This ensures:
- ✅ The tool actually works (we use it ourselves)
- ✅ Both workflows 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
Check the workflow file headers to see the exact command used. Try creating a release using the GitHub Actions UI!
## Development
```bash
# Clone repository
git clone https://github.com/hitoshura25/pypi-workflow-generator.git
cd pypi-workflow-generator
# Install dependencies
pip install -r requirements.txt
# Run tests
pytest
# Build package
python -m build
```
## 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/pypi-workflow-generator/
Raw data
{
"_id": null,
"home_page": "https://github.com/hitoshura25/pypi-workflow-generator",
"name": "pypi-workflow-generator",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "mcp, github-actions, pypi, workflow, ci-cd, code-generator",
"author": "Vinayak Menon",
"author_email": "Vinayak Menon <vinayakmenon+pypi@users.noreply.github.com>",
"download_url": "https://files.pythonhosted.org/packages/bc/83/dadac5f7c6d92b5e8fcaa3c0617147b3c1f9208ec3157e2377e65e275b21/pypi_workflow_generator-0.2.10.tar.gz",
"platform": null,
"description": "# pypi-workflow-generator\n\nA dual-mode tool (MCP server + CLI) for generating GitHub Actions workflows for Python package publishing to PyPI.\n\n## Features\n\n- \u2705 **Dual-Mode Operation**: Works as MCP server for AI agents OR traditional CLI for developers\n- \u2705 **PyPI Trusted Publishers**: Secure publishing without API tokens\n- \u2705 **Automated Versioning**: Uses setuptools_scm for git-based versioning\n- \u2705 **Pre-release Testing**: Automatic TestPyPI publishing on pull requests\n- \u2705 **Production Publishing**: Automatic PyPI publishing on version tags\n- \u2705 **Complete Project Initialization**: Generates pyproject.toml and setup.py\n- \u2705 **Release Management**: Simple git tag creation for triggering releases\n\n## Installation\n\n```bash\npip install pypi-workflow-generator\n```\n\n## Usage\n\nThis package can be used in three ways:\n\n### 1. MCP Mode (For AI Agents)\n\nFor AI agents with MCP support (Claude Code, Continue.dev, Cline):\n\n**Add to `claude_desktop_config.json` or `claude_config.json`**:\n```json\n{\n \"mcpServers\": {\n \"pypi-workflow-generator\": {\n \"command\": \"mcp-pypi-workflow-generator\"\n }\n }\n}\n```\n\nThe agent can now use these tools:\n- `generate_workflow` - Generate GitHub Actions workflows (both publishing and release)\n- `generate_release_workflow` - Generate only the release creation workflow **NEW!**\n- `initialize_project` - Create pyproject.toml and setup.py\n- `create_release` - Create and push git release tags\n\n**Example conversation**:\n```\nYou: \"Please set up a PyPI publishing workflow for my Python project\"\n\nClaude: I'll help you set up a complete PyPI publishing workflow.\n\n[Calls initialize_project and generate_workflow tools]\n\n\u2705 Created:\n - pyproject.toml\n - setup.py\n - .github/workflows/pypi-publish.yml\n\nNext steps:\n1. Configure Trusted Publishers on PyPI\n2. Create a release: pypi-release patch\n```\n\n### 2. CLI Mode (For Developers)\n\n**Initialize a new project**:\n```bash\npypi-workflow-generator-init \\\n --package-name my-awesome-package \\\n --author \"Your Name\" \\\n --author-email \"your.email@example.com\" \\\n --description \"My awesome Python package\" \\\n --url \"https://github.com/username/my-awesome-package\" \\\n --command-name my-command\n```\n\n**Generate workflow**:\n```bash\npypi-workflow-generator --python-version 3.11\n```\n\n**Create a release**:\n```bash\npypi-release patch # or 'minor' or 'major'\n```\n\n### 3. Programmatic Use\n\n```python\nfrom pypi_workflow_generator import generate_workflow, initialize_project\n\n# Initialize project\ninitialize_project(\n package_name=\"my-package\",\n author=\"Your Name\",\n author_email=\"your@email.com\",\n description=\"My package\",\n url=\"https://github.com/user/repo\",\n command_name=\"my-cmd\"\n)\n\n# Generate workflow\ngenerate_workflow(\n python_version=\"3.11\",\n release_on_main_push=False\n)\n```\n\n## Generated Workflows\n\nThis tool now generates **TWO** GitHub Actions workflows by default:\n\n### 1. PyPI Publishing Workflow (`pypi-publish.yml`)\n\nHandles automated package publishing:\n\n- **Automated Testing**: Runs pytest on every PR and release\n- **Pre-release Publishing**: TestPyPI publishing on PRs with version like `1.0.0.dev123`\n- **Production Publishing**: PyPI publishing on version tags\n- **Trusted Publishers**: No API tokens needed (OIDC authentication)\n- **setuptools_scm**: Automatic versioning from git tags\n\n### 2. Release Creation Workflow (`create-release.yml`) **NEW!**\n\nEnables manual release creation via GitHub UI:\n\n- **Manual Trigger**: Click a button in GitHub Actions to create releases\n- **Automatic Version Calculation**: Choose major/minor/patch, version is calculated automatically\n- **Git Tag Creation**: Creates and pushes version tags\n- **GitHub Releases**: Auto-generates release notes from commits\n- **Triggers Publishing**: Tag push automatically triggers the PyPI publish workflow\n\n## Creating Releases\n\nYou have **two ways** to create releases:\n\n### Option 1: GitHub Actions UI (Recommended) **NEW!**\n\n**Prerequisites**: Create a `RELEASE_PAT` secret (see [Setting Up Automated Release Publishing](#setting-up-automated-release-publishing))\n\n1. Go to **Actions** tab in your repository\n2. Select **Create Release** workflow\n3. Click **Run workflow**\n4. Choose release type:\n - **patch**: Bug fixes (0.1.0 \u2192 0.1.1)\n - **minor**: New features (0.1.1 \u2192 0.2.0)\n - **major**: Breaking changes (0.2.0 \u2192 1.0.0)\n5. (Optional) Specify custom token secret name if not using `RELEASE_PAT`\n6. Click **Run workflow**\n\nThe workflow will:\n- Calculate the next version number\n- Create and push a git tag\n- Create a GitHub Release with auto-generated notes\n- **Automatically trigger the PyPI publish workflow** (requires RELEASE_PAT)\n- Publish your package to PyPI\n\n**Benefits**: Works from anywhere, full automation, easy for AI agents to use.\n\n### Option 2: CLI (Local)\n\n```bash\npypi-release patch # or minor, major\n```\n\nThis creates and pushes the tag locally, which triggers the publish workflow.\n\n## Workflow Generation Options\n\n```bash\n# Generate both workflows (default)\npypi-workflow-generator --python-version 3.11\n\n# Generate only PyPI publishing workflow\npypi-workflow-generator --skip-release-workflow\n\n# Generate only release creation workflow\npypi-workflow-generator-release\n```\n\n## Setting Up Trusted Publishers\n\nThe generated GitHub Actions workflow (`pypi-publish.yml`) utilizes [PyPI Trusted Publishers](https://docs.pypi.org/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.\n\n**Why Trusted Publishers?**\n- **Enhanced Security:** Eliminates the need to store PyPI API tokens, reducing the risk of token compromise.\n- **Best Practice:** Recommended by PyPI for publishing from automated environments like GitHub Actions.\n\n**How to Set Up Trusted Publishers for Your Project:**\n\nBefore your workflow can successfully publish to PyPI or TestPyPI, you must configure Trusted Publishers for your project on the respective PyPI instance.\n\n1. **Log in to PyPI/TestPyPI:**\n - For TestPyPI: Go to `https://test.pypi.org/` and log in.\n - For official PyPI: Go to `https://pypi.org/` and log in.\n\n2. **Navigate to Your Project's Publishing Settings:**\n - Go to your project's management page. The URL will typically look like:\n `https://[test.]pypi.org/manage/project/<your-package-name>/settings/publishing/`\n - Replace `<your-package-name>` with the actual name of your Python package (e.g., `pypi-workflow-generator`).\n\n3. **Add a New Trusted Publisher:**\n - Click on the \"Add a new publisher\" button.\n - Select \"GitHub Actions\" as the publisher type.\n - Provide the following details:\n - **Owner:** The GitHub username or organization that owns your repository (e.g., `hitoshura25`).\n - **Repository:** The name of your GitHub repository (e.g., `pypi-workflow-generator`).\n - **Workflow Name:** The name of your workflow file (e.g., `pypi-publish.yml`).\n - **Environment (Optional):** If your GitHub Actions workflow uses a specific environment, specify its name here. Otherwise, leave it blank.\n\n4. **Save the Publisher:** Confirm and save the new publisher.\n\nOnce configured, your GitHub Actions workflow will be able to publish packages without needing `PYPI_API_TOKEN` or `TEST_PYPI_API_TOKEN` secrets.\n\n## Setting Up Automated Release Publishing\n\n### Why You Need a Personal Access Token\n\nGitHub Actions workflows triggered by the default `GITHUB_TOKEN` cannot trigger other workflows (security feature to prevent infinite loops). To enable the `create-release.yml` workflow to automatically trigger `pypi-publish.yml` after creating a release tag, you need to provide a Personal Access Token (PAT) with appropriate permissions.\n\n**Without a PAT:** The create-release workflow will successfully create tags and GitHub Releases, but the PyPI publish workflow won't trigger automatically. You would need to manually trigger it.\n\n**With a PAT:** Full automation - create a release via GitHub UI, and your package automatically publishes to PyPI.\n\n### Creating the Required PAT\n\n1. **Generate a Personal Access Token**:\n - Go to GitHub Settings \u2192 Developer settings \u2192 [Personal access tokens \u2192 Tokens (classic)](https://github.com/settings/tokens/new)\n - Click \"Generate new token (classic)\"\n - Give it a descriptive name: `Release Automation Token for <repo-name>`\n - Set expiration (recommended: 1 year, with calendar reminder to rotate)\n - Select scope: **repo** (full control of private repositories)\n - Click \"Generate token\"\n - **Copy the token immediately** (you won't see it again)\n\n2. **Add Token to Repository Secrets**:\n - Go to your repository \u2192 Settings \u2192 Secrets and variables \u2192 Actions\n - Click \"New repository secret\"\n - Name: `RELEASE_PAT`\n - Value: Paste the token you copied\n - Click \"Add secret\"\n\n3. **Verify Setup**:\n - Go to Actions tab \u2192 Create Release workflow \u2192 Run workflow\n - Select release type (patch/minor/major)\n - Leave token secret name as default (`RELEASE_PAT`)\n - The workflow should complete successfully\n - The PyPI publish workflow should trigger automatically\n - Your package should be published to PyPI\n\n### Using a Custom Token Name (Optional)\n\nIf your organization uses a different secret name (e.g., `GITHUB_ORG_TOKEN`), you can specify it when running the workflow:\n\n1. Go to Actions \u2192 Create Release\n2. Click \"Run workflow\"\n3. Fill in:\n - **Release type**: patch/minor/major\n - **Token secret name**: `GITHUB_ORG_TOKEN` (or your custom name)\n\n### Security Considerations\n\n- **Token Scope**: The PAT needs `repo` scope to push tags and trigger workflows\n- **Token Rotation**: Set expiration dates and rotate tokens regularly (recommended: annually)\n- **Access Control**: Only repository admins can add/view secrets\n- **Audit Trail**: GitHub logs all token usage in the repository audit log\n\n### Troubleshooting\n\n**Workflow fails with \"Secret 'RELEASE_PAT' not found\"**\n- You haven't created the PAT or added it to repository secrets\n- Follow the steps above to create and add the token\n\n**PyPI publish workflow still doesn't trigger**\n- Verify the PAT has `repo` scope (not just `public_repo`)\n- Check that the token hasn't expired\n- Ensure the token is added to repository secrets (not environment secrets)\n\n**Alternative: Use CLI Method**\n\nIf you prefer not to set up a PAT, you can create releases locally using the CLI:\n```bash\npypi-release patch # This runs on your machine, no PAT needed\n```\nThe CLI method pushes tags from your local machine, which doesn't have the GitHub Actions token limitation.\n\n## CLI Options\n\n### `pypi-workflow-generator`\n\nGenerate GitHub Actions workflows for PyPI publishing (generates both workflows by default).\n\n```\nOptions:\n --python-version VERSION Python version (default: 3.11)\n --output-filename NAME Workflow filename (default: pypi-publish.yml)\n --release-on-main-push Trigger release on main branch push\n --test-path PATH Path to tests (default: .)\n --verbose-publish Enable verbose publishing\n --skip-release-workflow Only generate pypi-publish.yml (skip create-release.yml)\n```\n\n### `pypi-workflow-generator-init`\n\nInitialize a new Python project with PyPI configuration.\n\n```\nOptions:\n --package-name NAME Package name (required)\n --author NAME Author name (required)\n --author-email EMAIL Author email (required)\n --description TEXT Package description (required)\n --url URL Project URL (required)\n --command-name NAME CLI command name (required)\n```\n\n### `pypi-release`\n\nCreate and push a git release tag (local CLI method).\n\n```\nUsage:\n pypi-release {major,minor,patch} [--overwrite]\n\nArguments:\n {major,minor,patch} The type of release (major, minor, or patch)\n\nOptions:\n --overwrite Overwrite an existing tag\n```\n\n**Note**: The CLI uses semantic versioning (major/minor/patch) for convenience. The MCP tool `create_release` accepts explicit version strings (e.g., \"v1.0.0\") for flexibility. See [Interface Differences](#interface-differences) below.\n\n### `pypi-workflow-generator-release` **NEW!**\n\nGenerate only the release creation workflow.\n\n```\nOptions:\n --output-filename NAME Workflow filename (default: create-release.yml)\n```\n\nUse this if you already have a PyPI publishing workflow and only want to add the release creation workflow.\n\n## MCP Server Details\n\nThe MCP server runs via stdio transport and provides four tools:\n\n**Tool: `generate_workflow`**\n- Generates GitHub Actions workflow files (both publishing and release by default)\n- Parameters: python_version, output_filename, release_on_main_push, test_path, verbose_publish, include_release_workflow\n\n**Tool: `generate_release_workflow`** **NEW!**\n- Generates only the release creation workflow\n- Parameters: output_filename\n\n**Tool: `initialize_project`**\n- Creates pyproject.toml and setup.py\n- Parameters: package_name, author, author_email, description, url, command_name\n\n**Tool: `create_release`**\n- Creates and pushes git tag\n- Parameters: version\n\nSee [MCP-USAGE.md](./MCP-USAGE.md) for detailed MCP configuration and usage.\n\n## Interface Differences\n\nThe package provides two interfaces with slightly different APIs for different use cases:\n\n### CLI vs MCP: Release Creation\n\n**CLI Mode** (`pypi-release`):\n- Uses semantic versioning keywords: `major`, `minor`, `patch`\n- Automatically increments version from latest git tag\n- Convenience for developers who want simple versioning\n\n```bash\npypi-release patch # Creates v1.0.1 (if current is v1.0.0)\npypi-release minor # Creates v1.1.0\npypi-release major # Creates v2.0.0\n```\n\n**MCP Mode** (`create_release` tool):\n- Accepts explicit version strings: `v1.0.0`, `v2.5.3`, etc.\n- Direct control over version numbers\n- Flexibility for AI agents to determine versions programmatically\n\n```json\n{\n \"version\": \"v1.0.0\"\n}\n```\n\n**Why the difference?** The CLI optimizes for human convenience (automatic incrementing), while MCP optimizes for programmatic control (explicit versions).\n\n### Entry Point Naming Convention\n\nThe MCP server uses the `mcp-` prefix (industry standard for MCP tools):\n- `mcp-pypi-workflow-generator` - Follows MCP ecosystem naming\n- Makes it discoverable when searching for MCP servers\n- Clearly distinguishes server mode from CLI mode\n\nAll other commands use the `pypi-` prefix for CLI operations:\n- `pypi-workflow-generator`\n- `pypi-workflow-generator-init`\n- `pypi-release`\n\n## Architecture\n\n```\nUser/AI Agent\n \u2502\n \u251c\u2500\u2500\u2500 MCP Mode \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500> server.py (MCP protocol)\n \u2502 \u2502\n \u251c\u2500\u2500\u2500 CLI Mode \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500> main.py / init.py / create_release.py\n \u2502 \u2502\n \u2514\u2500\u2500\u2500 Programmatic \u2500\u2500\u2500\u2500> __init__.py\n \u2502\n All modes use shared core:\n \u25bc\n generator.py\n (Business logic)\n```\n\n## Dogfooding\n\nThis project uses itself to generate its own GitHub Actions workflows! The workflow files at:\n- `.github/workflows/pypi-publish.yml`\n- `.github/workflows/create-release.yml`\n\nWere both created by running:\n\n```bash\npypi-workflow-generator \\\n --python-version 3.11 \\\n --test-path pypi_workflow_generator/ \\\n --verbose-publish\n```\n\nThis ensures:\n- \u2705 The tool actually works (we use it ourselves)\n- \u2705 Both workflows are tested in production\n- \u2705 The templates stay consistent with real-world usage\n- \u2705 We practice what we preach\n- \u2705 Users can see real examples of the generated output\n\nCheck the workflow file headers to see the exact command used. Try creating a release using the GitHub Actions UI!\n\n## Development\n\n```bash\n# Clone repository\ngit clone https://github.com/hitoshura25/pypi-workflow-generator.git\ncd pypi-workflow-generator\n\n# Install dependencies\npip install -r requirements.txt\n\n# Run tests\npytest\n\n# Build package\npython -m build\n```\n\n## Contributing\n\nContributions welcome! Please open an issue or PR.\n\n## License\n\nApache-2.0\n\n## Links\n\n- **Repository**: https://github.com/hitoshura25/pypi-workflow-generator\n- **Issues**: https://github.com/hitoshura25/pypi-workflow-generator/issues\n- **PyPI**: https://pypi.org/project/pypi-workflow-generator/\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Dual-mode tool (MCP server + CLI) for generating GitHub Actions workflows",
"version": "0.2.10",
"project_urls": {
"Documentation": "https://github.com/hitoshura25/pypi-workflow-generator/blob/main/README.md",
"Homepage": "https://github.com/hitoshura25/pypi-workflow-generator",
"Issues": "https://github.com/hitoshura25/pypi-workflow-generator/issues",
"Repository": "https://github.com/hitoshura25/pypi-workflow-generator"
},
"split_keywords": [
"mcp",
" github-actions",
" pypi",
" workflow",
" ci-cd",
" code-generator"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "4dac0234a42ada072e5e83a8e904a114b445dab9ffa7ee68665d7d30a9b8c945",
"md5": "5305412f09ddc29acd355710d518a98a",
"sha256": "82e5c65b1f7d03c6d6fc91eb8ffd807806576364b43f71390caa8ff970e77e2e"
},
"downloads": -1,
"filename": "pypi_workflow_generator-0.2.10-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5305412f09ddc29acd355710d518a98a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 32176,
"upload_time": "2025-11-03T22:46:08",
"upload_time_iso_8601": "2025-11-03T22:46:08.134390Z",
"url": "https://files.pythonhosted.org/packages/4d/ac/0234a42ada072e5e83a8e904a114b445dab9ffa7ee68665d7d30a9b8c945/pypi_workflow_generator-0.2.10-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "bc83dadac5f7c6d92b5e8fcaa3c0617147b3c1f9208ec3157e2377e65e275b21",
"md5": "bf59c376a64a50305b645786b3ebd9e9",
"sha256": "7e6a39f7b3ae8737a5820450736b375d0ca21546be38e696bbbc8bfb3f5d8867"
},
"downloads": -1,
"filename": "pypi_workflow_generator-0.2.10.tar.gz",
"has_sig": false,
"md5_digest": "bf59c376a64a50305b645786b3ebd9e9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 63434,
"upload_time": "2025-11-03T22:46:09",
"upload_time_iso_8601": "2025-11-03T22:46:09.729283Z",
"url": "https://files.pythonhosted.org/packages/bc/83/dadac5f7c6d92b5e8fcaa3c0617147b3c1f9208ec3157e2377e65e275b21/pypi_workflow_generator-0.2.10.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-11-03 22:46:09",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "hitoshura25",
"github_project": "pypi-workflow-generator",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "pytest",
"specs": []
},
{
"name": "pytest-asyncio",
"specs": []
},
{
"name": "Jinja2",
"specs": []
},
{
"name": "pyyaml",
"specs": []
},
{
"name": "twine",
"specs": []
},
{
"name": "wheel",
"specs": []
},
{
"name": "setuptools_scm",
"specs": []
},
{
"name": "build",
"specs": []
}
],
"lcname": "pypi-workflow-generator"
}
JSON
