Skip to content

Commit 878acbc

Browse files
committed
Publish releases from GitHub Actions with PyPI provenance
PyPI only accepts PEP 740 attestations on files uploaded by a Trusted Publisher, so a local upload with an API token can't carry provenance. Add a publish.yml workflow that builds the tagged release and uploads it to PyPI or TestPyPI with pypa/gh-action-pypi-publish, which signs and uploads attestations. The build runs in a separate job with read-only permissions, and only the upload job can request an OIDC token. make publish and make publish-test now start that workflow on the tag at HEAD with the GitHub CLI and wait for the run, after checking that the tag on origin matches the local one. uv-publish is no longer used, so drop it from the dev dependency group. Document the release flow and the one-time setup: the Trusted Publishers, the pypi/testpypi environments (tag-only, cmd2-admins approval, no admin bypass), and the ruleset limiting release tags to cmd2-admins.
1 parent 5ffe145 commit 878acbc

4 files changed

Lines changed: 140 additions & 11 deletions

File tree

‎.github/CONTRIBUTING.md‎

Lines changed: 31 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -80,7 +80,7 @@ for a list of dependencies needed for building `cmd2`.
8080
| [setuptools](https://pypi.org/project/setuptools/) | `72.1.0` | Python package management |
8181
| [setuptools-scm](https://github.com/pypa/setuptools-scm) | `8.0.4` | Manage your versions by scm tags |
8282

83-
> [uv-publish](https://pypi.org/project/uv-publish/) is also needed for publishing releases to PyPI,
83+
> The [GitHub CLI](https://cli.github.com/) (`gh`) is also needed for publishing releases to PyPI,
8484
> but that is something only core maintainers need to worry about.
8585
8686
#### Additional prerequisites for developing cmd2
@@ -766,17 +766,44 @@ other branches can be deleted. All releases are tagged so that they can be repro
766766
## Publishing a new release
767767

768768
Since 0.9.2, the process of publishing a new release of `cmd2` to [PyPi](https://pypi.org/) has been
769-
mostly automated. The manual steps are all git operations. Here's the checklist:
769+
mostly automated. Releases are built and uploaded by the
770+
[Publish](https://github.com/python-cmd2/cmd2/actions/workflows/publish.yml) GitHub Actions workflow
771+
using [Trusted Publishing](https://docs.pypi.org/trusted-publishers/), which also attaches
772+
[provenance attestations](https://docs.pypi.org/attestations/) to every file. The `make publish`
773+
targets start that workflow with the [GitHub CLI](https://cli.github.com/) (`gh`), so you need `gh`
774+
installed and authenticated. Here's the checklist:
770775

771776
1. Make sure you're on the proper branch (almost always **main**)
772777
1. Make sure all the unit tests pass with `make test`
773778
1. Make sure latest year in `LICENSE` matches current year
774779
1. Make sure `CHANGELOG.md` describes the version and has the correct release date
775780
1. Add a git tag representing the version number using `make tag TAG=x.y.z`
776781
- Where x, y, and z are all small non-negative integers
777-
1. (Optional) Run `make publish-test` to clean, build, and upload a new release to
782+
1. (Optional) Run `make publish-test` to build and upload the tagged release to
778783
[Test PyPi](https://test.pypi.org)
779-
1. Run `make publish` to clean, build, and upload a new release to [PyPi](https://pypi.org/)
784+
1. Run `make publish` to build and upload the tagged release to [PyPi](https://pypi.org/)
785+
786+
Both targets wait for the workflow run to finish and fail if it fails. Only members of the
787+
`cmd2-admins` team can publish: the upload job waits until one of them approves it, either from the
788+
workflow run page that `make publish` prints or from the repository's Actions tab.
789+
790+
### One-time publishing setup
791+
792+
Trusted Publishing needs this configuration, which only a project owner can change:
793+
794+
- On [PyPI](https://pypi.org/manage/project/cmd2/settings/publishing/), add a GitHub Trusted
795+
Publisher with owner `python-cmd2`, repository `cmd2`, workflow `publish.yml`, and environment
796+
`pypi`
797+
- On [Test PyPI](https://test.pypi.org/manage/project/cmd2/settings/publishing/), add the same
798+
Trusted Publisher, but with environment `testpypi`
799+
- In the GitHub repository settings, create the `pypi` and `testpypi` environments. For each one:
800+
- Limit deployments to tags matching `*.*.*`, so the workflow can only publish a tagged release
801+
- Add the `cmd2-admins` team as required reviewers and turn off administrator bypass, so only
802+
members of that team can approve an upload
803+
- In the GitHub repository rulesets, add an active tag ruleset named "Release tags" that targets
804+
`refs/tags/*.*.*`, restricts creations, updates, and deletions, and lets only the `cmd2-admins`
805+
team bypass it. This stops anyone else from creating or moving the release tags the workflow
806+
publishes from
780807

781808
## Acknowledgement
782809

‎.github/workflows/publish.yml‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
# Builds cmd2 from a release tag and publishes it to PyPI or TestPyPI using Trusted Publishing.
2+
# pypa/gh-action-pypi-publish generates and uploads PEP 740 attestations (provenance) by default.
3+
#
4+
# Started by `make publish` / `make publish-test`, which run:
5+
# gh workflow run publish.yml --ref <tag> -f target=<pypi|testpypi>
6+
#
7+
# One-time setup is described in the "Publishing a new release" section of .github/CONTRIBUTING.md.
8+
#
9+
# For documentation on GitHub Actions Workflows, see:
10+
# https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions
11+
name: Publish
12+
13+
on:
14+
workflow_dispatch:
15+
inputs:
16+
target:
17+
description: Package index to publish to
18+
type: choice
19+
options:
20+
- testpypi
21+
- pypi
22+
default: testpypi
23+
24+
permissions: {}
25+
26+
concurrency:
27+
group: publish-${{ github.ref }}
28+
cancel-in-progress: false
29+
30+
jobs:
31+
build:
32+
name: Build distributions
33+
runs-on: ubuntu-latest
34+
permissions:
35+
contents: read
36+
steps:
37+
- name: Require a tag
38+
if: github.ref_type != 'tag'
39+
run: |
40+
echo "::error::Publish must run on a release tag, not a branch (got ${GITHUB_REF})"
41+
exit 1
42+
- name: Check out
43+
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
44+
with:
45+
fetch-depth: 0 # Needed for setuptools_scm to work correctly
46+
persist-credentials: false
47+
- name: Install uv
48+
uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
49+
with:
50+
enable-cache: false # Never restore a cache into a release build
51+
- name: Validate tag
52+
run: uv run --no-project scripts/validate_tag.py
53+
- name: Build
54+
run: uv build
55+
- name: Upload distributions
56+
uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
57+
with:
58+
name: dist
59+
path: dist/
60+
if-no-files-found: error
61+
62+
publish:
63+
name: Publish to ${{ inputs.target }}
64+
needs: build
65+
runs-on: ubuntu-latest
66+
environment:
67+
name: ${{ inputs.target }}
68+
url: https://${{ inputs.target == 'testpypi' && 'test.' || '' }}pypi.org/p/cmd2
69+
permissions:
70+
id-token: write # Required for Trusted Publishing and for signing attestations
71+
steps:
72+
- name: Download distributions
73+
uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
74+
with:
75+
name: dist
76+
path: dist/
77+
- name: Publish to TestPyPI
78+
if: inputs.target == 'testpypi'
79+
uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # v1.14.3
80+
with:
81+
repository-url: https://test.pypi.org/legacy/
82+
- name: Publish to PyPI
83+
if: inputs.target == 'pypi'
84+
uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # v1.14.3

‎Makefile‎

Lines changed: 25 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -74,15 +74,34 @@ validate-tag: ## Check to make sure that a tag exists for the current HEAD and i
7474
@echo "🚀 Validating version tag"
7575
@uv run scripts/validate_tag.py
7676

77+
# Start the GitHub Actions publish workflow (.github/workflows/publish.yml) on the tag at HEAD and wait for it to finish.
78+
# The workflow builds the release and uploads it with Trusted Publishing, which attaches PEP 740 provenance.
79+
# Argument: the package index to publish to (pypi or testpypi). Requires the GitHub CLI (gh).
80+
define publish-via-workflow
81+
set -e; \
82+
tag=$$(git describe --exact-match --tags); \
83+
if [ "$$(git ls-remote --tags origin "refs/tags/$$tag" | cut -f1)" != "$$(git rev-parse "$$tag")" ]; then \
84+
echo "Tag '$$tag' is missing from origin or differs from it. Push it with: git push origin $$tag"; \
85+
exit 1; \
86+
fi; \
87+
url=$$(gh workflow run publish.yml --ref "$$tag" -f target=$(1) | grep -o 'https://[^ ]*/actions/runs/[0-9]*') || { \
88+
echo "Could not start the publish workflow or find its run URL"; \
89+
exit 1; \
90+
}; \
91+
echo "🚀 Workflow run: $$url"; \
92+
echo "🚀 A member of the cmd2-admins team must approve the deployment on that page before the upload starts"; \
93+
gh run watch "$${url##*/}" --exit-status
94+
endef
95+
7796
.PHONY: publish-test
78-
publish-test: validate-tag build ## Test publishing a release to PyPI, uses token from ~/.pypirc file.
79-
@echo "🚀 Publishing: Dry run."
80-
@uv run uv-publish --repository testpypi
97+
publish-test: validate-tag ## Publish the tag at HEAD to TestPyPI via GitHub Actions
98+
@echo "🚀 Publishing to TestPyPI via GitHub Actions"
99+
@$(call publish-via-workflow,testpypi)
81100

82101
.PHONY: publish
83-
publish: validate-tag build ## Publish a release to PyPI, uses token from ~/.pypirc file.
84-
@echo "🚀 Publishing."
85-
@uv run uv-publish
102+
publish: validate-tag ## Publish the tag at HEAD to PyPI, with provenance, via GitHub Actions
103+
@echo "🚀 Publishing to PyPI via GitHub Actions"
104+
@$(call publish-via-workflow,pypi)
86105

87106
# Define variables for files/directories to clean
88107
BUILD_DIRS = build dist *.egg-info

‎pyproject.toml‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -51,7 +51,6 @@ dev = [
5151
"ruff>=0.16.0",
5252
"textual-tty>=0.4.0 ; sys_platform != 'win32'",
5353
"ty>=0.0.75",
54-
"uv-publish>=1.3",
5554
"zensical>=0.0.57",
5655
]
5756
docs = [

0 commit comments

Comments
 (0)