UV Semantic Release Action

🚀 Automatic version bumping, changelog generation, and releases for UV Python projects using conventional commits.

graph LR
    A[1. Push<br/>feat: new feature<br/>fix: bug fix] --> B[2. Analyze<br/>Parse commits<br/>Determine bump]
    B --> C[3. Version<br/>Update pyproject.toml<br/>0.1.0 → 0.2.0]
    C --> D[4. Changelog<br/>Generate notes<br/>CHANGELOG.md]
    D --> E[5. Tag<br/>Create git tag<br/>v0.2.0]
    E --> F[6. Release<br/>GitHub Release<br/>+ Artifacts]
    F --> G[7. Build<br/>uv build<br/>.whl + .tar.gz]
    G -.-> H[8. Publish<br/>PyPI optional<br/>uv publish]

    style A fill:#e94560,stroke:#e94560,color:#fff
    style B fill:#0ea5e9,stroke:#0ea5e9,color:#fff
    style C fill:#22c55e,stroke:#22c55e,color:#fff
    style D fill:#f59e0b,stroke:#f59e0b,color:#fff
    style E fill:#a855f7,stroke:#a855f7,color:#fff
    style F fill:#ec4899,stroke:#ec4899,color:#fff
    style G fill:#14b8a6,stroke:#14b8a6,color:#fff
    style H fill:#6366f1,stroke:#6366f1,stroke-dasharray: 5 5,color:#fff

✨ Features

🔄 Automatic Semantic Versioning - Version bumps based on conventional commits
📝 Auto-generated Changelog - Beautiful CHANGELOG.md from commit history
🏷️ Git Tags - Automatic tag creation (e.g., v1.2.3)
📦 GitHub Releases - Full releases with notes and artifacts
🐍 UV Native - Built specifically for UV Python projects
📤 PyPI Publishing - Optional automatic PyPI deployment
⚡ Zero Config - Sensible defaults, works out of the box
🔧 Highly Configurable - Customize every aspect of the release process

🚀 Quick Start

1. Add the workflow to your repository

Create .github/workflows/release.yml:

name: Release

on:
  push:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: write

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: UV Semantic Release
        uses: anomius/uv-semantic-release@v1
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}

2. Add semantic-release config to `pyproject.toml`

[tool.semantic_release]
version_toml = ["pyproject.toml:project.version"]
branch = "main"
commit_parser = "conventional_commits"
tag_format = "v{version}"

[tool.semantic_release.changelog]
changelog_file = "CHANGELOG.md"

3. Use Conventional Commits

git commit -m "feat: add user authentication"
git commit -m "fix: resolve login timeout issue"
git push origin main

That's it! 🎉 The action will automatically create releases when you push to main.

📖 Usage

Basic Usage

- uses: anomius/uv-semantic-release@v1
  with:
    github_token: ${{ secrets.GITHUB_TOKEN }}

With PyPI Publishing

- uses: anomius/uv-semantic-release@v1
  with:
    github_token: ${{ secrets.GITHUB_TOKEN }}
    publish_to_pypi: 'true'
    pypi_token: ${{ secrets.PYPI_TOKEN }}

Full Configuration

- uses: anomius/uv-semantic-release@v1
  with:
    github_token: ${{ secrets.GITHUB_TOKEN }}
    python_version: '3.12'
    uv_version: 'latest'
    semantic_release_version: '9.14.0'
    changelog: 'true'
    push: 'true'
    vcs_release: 'true'
    build: 'true'
    upload_to_release: 'true'
    publish_to_pypi: 'false'
    working_directory: '.'
    git_committer_name: 'github-actions[bot]'
    git_committer_email: 'github-actions[bot]@users.noreply.github.com'

📥 Inputs

Input	Description	Required	Default
`github_token`	GitHub token for releases and pushing	Yes	`${{ github.token }}`
`pypi_token`	PyPI token for publishing	No	`''`
`python_version`	Python version to use	No	`'3.12'`
`uv_version`	UV version to use	No	`'latest'`
`semantic_release_version`	python-semantic-release version	No	`'9.14.0'`
`root_options`	Additional semantic-release options	No	`''`
`changelog`	Generate changelog	No	`'true'`
`push`	Push changes to remote	No	`'true'`
`vcs_release`	Create GitHub release	No	`'true'`
`build`	Build the package	No	`'true'`
`publish_to_pypi`	Publish to PyPI	No	`'false'`
`upload_to_release`	Upload artifacts to release	No	`'true'`
`working_directory`	Working directory	No	`'.'`
`git_committer_name`	Git committer name	No	`'github-actions[bot]'`
`git_committer_email`	Git committer email	No	`'...[bot]@users.noreply.github.com'`

📤 Outputs

Output	Description
`released`	Whether a new release was created (`'true'` or `'false'`)
`version`	The new version number (e.g., `'1.2.3'`)
`previous_version`	The previous version number
`tag`	The git tag for the release (e.g., `'v1.2.3'`)

Using Outputs

- name: UV Semantic Release
  id: release
  uses: anomius/uv-semantic-release@v1
  with:
    github_token: ${{ secrets.GITHUB_TOKEN }}

- name: Post-release actions
  if: steps.release.outputs.released == 'true'
  run: |
    echo "Released version ${{ steps.release.outputs.version }}"
    echo "Tag: ${{ steps.release.outputs.tag }}"

⚙️ Configuration

pyproject.toml Configuration

Add this to your pyproject.toml:

[project]
name = "your-package"
version = "0.1.0"  # This will be auto-updated

[tool.semantic_release]
# Version location(s)
version_toml = ["pyproject.toml:project.version"]

# Branch configuration
branch = "main"

# Commit parser
commit_parser = "conventional_commits"

# Tag format
tag_format = "v{version}"

# Build command
build_command = "uv build"

# Release settings
upload_to_vcs_release = true
upload_to_pypi = false

# Commit message for version bumps
commit_message = "chore(release): bump version to {version} [skip ci]"

# Allow 0.x versions
allow_zero_version = true
major_on_zero = false

[tool.semantic_release.changelog]
changelog_file = "CHANGELOG.md"
exclude_commit_patterns = [
    '''chore\(deps.*\):.*''',
    '''chore\(release\):.*''',
    '''Merge.*''',
]

[tool.semantic_release.branches.main]
match = "^(main|master)$"
prerelease = false

[tool.semantic_release.branches.develop]
match = "^(dev|develop)$"
prerelease = true
prerelease_token = "dev"

[tool.semantic_release.commit_parser_options]
allowed_tags = ["feat", "fix", "docs", "style", "refactor", "perf", "test", "build", "ci", "chore"]
minor_tags = ["feat"]
patch_tags = ["fix", "perf"]

Multiple Version Locations

If you have version in multiple places:

[tool.semantic_release]
version_toml = ["pyproject.toml:project.version"]
version_variables = ["src/mypackage/__init__.py:__version__"]

📝 Conventional Commits

This action uses Conventional Commits to determine version bumps.

Commit Format

<type>(<scope>): <description>

[optional body]

[optional footer(s)]

Version Bump Rules

Commit Type	Example	Version Bump
`fix:`	`fix: resolve null pointer`	PATCH (0.0.X)
`perf:`	`perf: optimize queries`	PATCH (0.0.X)
`feat:`	`feat: add dark mode`	MINOR (0.X.0)
`feat!:`	`feat!: redesign API`	MAJOR (X.0.0)
`BREAKING CHANGE:`	See below	MAJOR (X.0.0)

Breaking Changes

# Option 1: ! after type
git commit -m "feat!: remove deprecated endpoints"

# Option 2: Footer
git commit -m "refactor: update database schema

BREAKING CHANGE: requires database migration"

Non-Releasing Types

These types don't trigger a release:

docs: - Documentation changes
style: - Code style changes
refactor: - Code refactoring
test: - Test changes
build: - Build system changes
ci: - CI configuration
chore: - Maintenance tasks

📚 Examples

Basic Release Workflow

name: Release

on:
  push:
    branches: [main]

permissions:
  contents: write

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: anomius/uv-semantic-release@v1
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}

Release with PyPI Publishing

name: Release and Publish

on:
  push:
    branches: [main]

permissions:
  contents: write

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Release
        id: release
        uses: anomius/uv-semantic-release@v1
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_to_pypi: 'true'
          pypi_token: ${{ secrets.PYPI_TOKEN }}

      - name: Announce Release
        if: steps.release.outputs.released == 'true'
        run: |
          echo "🎉 Released v${{ steps.release.outputs.version }}!"

Monorepo Setup

name: Release Package A

on:
  push:
    branches: [main]
    paths:
      - 'packages/package-a/**'

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: anomius/uv-semantic-release@v1
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          working_directory: 'packages/package-a'

Manual Release with Dry Run

name: Manual Release

on:
  workflow_dispatch:
    inputs:
      dry_run:
        description: 'Dry run (no actual release)'
        required: false
        default: 'false'
        type: boolean

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: anomius/uv-semantic-release@v1
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          root_options: ${{ inputs.dry_run == 'true' && '--noop' || '' }}

Pre-release from Feature Branches

name: Pre-release

on:
  push:
    branches:
      - 'develop'
      - 'beta'

jobs:
  prerelease:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: anomius/uv-semantic-release@v1
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          root_options: '--prerelease'

🔧 Troubleshooting

No release created

Problem: Commits are pushed but no release is created.

Solutions:

Ensure commits follow conventional commit format
Check that commits include feat:, fix:, or perf: types
Verify fetch-depth: 0 in checkout step
Check workflow has contents: write permission

Permission denied

Problem: Push or release creation fails with permission error.

Solutions:

For protected branches, use a Personal Access Token (PAT):

- uses: actions/checkout@v4
  with:
    token: ${{ secrets.PAT_TOKEN }}
    fetch-depth: 0

- uses: anomius/uv-semantic-release@v1
  with:
    github_token: ${{ secrets.PAT_TOKEN }}

Ensure the token has repo scope

Version not updating

Problem: Release created but pyproject.toml version unchanged.

Solutions:

Check version_toml path is correct:
- PEP 621: ["pyproject.toml:project.version"]
- Poetry: ["pyproject.toml:tool.poetry.version"]
Ensure pyproject.toml has a version field

Changelog not generated

Problem: CHANGELOG.md not created or updated.

Solutions:

Ensure changelog: 'true' in action inputs
Check [tool.semantic_release.changelog] config exists
Verify file permissions in repository

PyPI publishing fails

Problem: Release succeeds but PyPI upload fails.

Solutions:

Verify PYPI_TOKEN secret is set correctly
Check token has upload permissions
Ensure package name is available on PyPI
Verify pyproject.toml has valid metadata

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

Development Setup

# Clone the repository
git clone https://github.com/anomius/uv-semantic-release.git
cd uv-semantic-release

# Install UV
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install dependencies
uv sync --dev

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

python-semantic-release - The core release automation tool
UV - The fast Python package manager
Conventional Commits - The commit specification

Made with ❤️ for the Python community

Name		Name	Last commit message	Last commit date
Latest commit History 3 Commits
.github		.github
docs		docs
examples		examples
.DS_Store		.DS_Store
.commitlintrc.json		.commitlintrc.json
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
action.yml		action.yml

Folders and files

Latest commit

History

Repository files navigation

UV Semantic Release Action

✨ Features

📋 Table of Contents

🚀 Quick Start

1. Add the workflow to your repository

2. Add semantic-release config to pyproject.toml

3. Use Conventional Commits

📖 Usage

Basic Usage

With PyPI Publishing

Full Configuration

📥 Inputs

📤 Outputs

Using Outputs

⚙️ Configuration

pyproject.toml Configuration

Multiple Version Locations

📝 Conventional Commits

Commit Format

Version Bump Rules

Breaking Changes

Non-Releasing Types

📚 Examples

Basic Release Workflow

Release with PyPI Publishing

Monorepo Setup

Manual Release with Dry Run

Pre-release from Feature Branches

🔧 Troubleshooting

No release created

Permission denied

Version not updating

Changelog not generated

PyPI publishing fails

🤝 Contributing

Development Setup

📄 License

🙏 Acknowledgments

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Contributors

Uh oh!

2. Add semantic-release config to `pyproject.toml`

Packages