How do I set up trusted publishing for PyPI with this action?

Configure a job with 'id-token: write' permissions and an environment linked to PyPI, then invoke the action without username/password. First, ensure your PyPI project has a trusted publisher configured, as per the trusted publishing section.

pypa/gh-action-pypi-publish or twine directly in CI?

This action wraps twine with security enhancements like OIDC and attestations, making it better for automated, secure publishing. Use twine alone if you need manual control or are in unsupported environments like containerized jobs.

How to turn off digital attestations?

Set the 'attestations' input to false in the action configuration. This disables Sigstore-signed attestation generation, useful for custom repositories or if provenance tracking isn't needed.

Why does my publish job fail on duplicate files?

By default, the action fails on duplicates to prevent incomplete releases. Enable 'skip-existing: true' to tolerate them, but this is discouraged for production PyPI uploads to avoid race conditions.

Can I publish to TestPyPI with this action?

Yes, specify 'repository-url: https://test.pypi.org/legacy/' in the action inputs. Trusted publishing works with TestPyPI if configured, and you should update the environment name accordingly.

How to publish only when a new tag is pushed?

Add a condition to the job: 'if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags')'. This filters the job to run only on tagged commits, as shown in the usage examples.

Open-Awesome

Publish a Python distribution package to PyPI

BSD-3-ClausePythonv1.14.0

A GitHub Action for securely publishing Python packages to PyPI using trusted publishing (OIDC) without requiring API tokens.

Visit Website GitHub

1.2k stars111 forks0 contributors

What is Publish a Python distribution package to PyPI?

PyPI publish GitHub Action is an official GitHub Action for securely uploading Python distribution packages to the Python Package Index (PyPI) from CI/CD workflows. It solves the problem of automating package releases without managing sensitive API tokens by using PyPI's trusted publishing (OIDC) feature.

Target Audience

Python package maintainers and developers who use GitHub Actions for CI/CD and want to automate publishing to PyPI or other Python package repositories securely.

Value Proposition

Developers choose this action because it's the official PyPA solution, offers tokenless authentication via trusted publishing, includes built-in security best practices, and simplifies release automation with minimal configuration.

Overview

The blessed :octocat: GitHub Action, for publishing your :package: distribution files to PyPI, the tokenless way: https://github.com/marketplace/actions/pypi-publish

Use Cases

Best For

Automating Python package releases to PyPI from GitHub Actions
Implementing secure, tokenless authentication using PyPI's trusted publishing
Generating and uploading digital attestations for package provenance
Publishing to multiple indices like PyPI and TestPyPI in separate jobs
Enforcing security best practices by separating build and publish stages
Debugging upload issues with verbose output and hash verification

Not Ideal For

Projects using Windows or macOS GitHub Actions runners
Teams wanting to integrate publishing into reusable workflows
Developers seeking a single-job build and publish solution
Users of custom containerized jobs in CI/CD

Pros & Cons

Pros

Tokenless OIDC Authentication

Uses PyPI's trusted publishing via OpenID Connect, eliminating the need to manage and store API tokens, as highlighted in the trusted publishing setup.

Automatic Digital Attestations

Generates and uploads Sigstore-signed attestations by default for trusted publishing flows, enhancing package provenance and security without extra configuration.

Security-First Job Separation

Enforces building and publishing in separate jobs to prevent privilege escalation and build dependency poisoning, a core philosophy stated in the non-goals section.

Flexible Index Support

Supports PyPI, TestPyPI, and custom repositories with configurable URLs, allowing for diverse publishing targets as shown in the advanced release management examples.

Cons

Linux-Only Constraint

The action is docker-based and only supported in GNU/Linux jobs, explicitly unsupported for other runner OSes, limiting cross-platform CI/CD setups.

Complex Workflow Orchestration

Requires manual setup of artifact sharing between separate build and publish jobs using actions like upload/download-artifact, adding overhead for simple projects.

Unsupported Workflow Patterns

Cannot be used in reusable workflows or composite actions with trusted publishing, and invoking it multiple times in one job is not supported, restricting CI/CD modularity.

Frequently Asked Questions

Related Projects

Executing remote ssh commands

GitHub Actions for executing remote ssh commands.

Stars6,074

Forks674

Last commit3 days ago

FTP Deploy Action, Deploys a GitHub project to a FTP server using GitHub actions

Deploys a GitHub project to a FTP server using GitHub actions

Stars4,944

Forks430

Last commit9 days ago

Copy files and artifacts via SSH

GitHub Action that copy files and artifacts via SSH.

Stars1,548

Forks173

Last commit1 month ago

GitHub Action for GoReleaser, a release automation tool for Go projects

GitHub Action for GoReleaser

Stars995

Forks98

Last commit12 hours ago

Community-curated · Updated weekly · 100% open source

Found a gem we're missing?

Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.

Submit a project Star on GitHub