✨ Template | CD: Add PyPI Trusted Publisher release workflow

mbercx · mbercx · commit 8fa76b99a92f · 2026-04-09T02:13:48.000+02:00
Generated packages now auto-publish to PyPI on `vX.Y.Z` tag pushes via OIDC Trusted
Publishing — no API tokens stored in the repo. The new `cd.yaml` workflow defaults to
`contents: read`; only the `publish` job holds `id-token: write`, gated on a `pypi`
GitHub environment that can optionally require manual approval.

Publishing docs are split along their two audiences:

- `docs/publishing.md` ("First publication to PyPI") covers the one-time Trusted
  Publisher registration and `pypi` environment setup on the repo — the steps a
  maintainer only does once per project.
- `template/docs/developer.md.jinja` gets a `## Release` section owning the recurring
  flow: `hatch version` bump, tag, push, and the warning that the tag and `__about__.py`
  version must agree. An `important` admonition at the top, branched on the `docs`
  engine so both MyST and MkDocs render correctly, links back to the first-publication
  guide.
- `docs/index.md` surfaces the capability: a `### Publish to PyPI` entry under `## Next
  steps` (noting you can defer publishing, but pushing an early `0.0.1` release is the
  way to claim the name), plus a bullet in the features list.
diff --git a/README.md b/README.md
@@ -15,6 +15,7 @@ Template for Python packages based on [`copier`](https://copier.readthedocs.io/e
 * ⚙️ **GitHub Actions**:
     * Deploy documentation to [GitHub Pages](https://docs.github.com/en/pages/getting-started-with-github-pages/creating-a-github-pages-site) or [Read the Docs](https://about.readthedocs.com/).
     * Run pre-commit checks and tests on every pull request.
+    * Publish to [PyPI](https://pypi.org/) on `vX.Y.Z` tags via [Trusted Publishing](https://docs.pypi.org/trusted-publishers/) — no API tokens.
 
 ## Usage
 
diff --git a/docs/index.md b/docs/index.md
@@ -13,6 +13,7 @@ A `copier`-based template for Python packages.
 * ⚙️ **GitHub Actions**:
     * Deploy documentation to [GitHub Pages](https://docs.github.com/en/pages/getting-started-with-github-pages/creating-a-github-pages-site) or [Read the Docs](https://about.readthedocs.com/).
     * Run pre-commit checks and tests on every pull request.
+    * Publish to [PyPI](https://pypi.org/) on `vX.Y.Z` tags via [Trusted Publishing](https://docs.pypi.org/trusted-publishers/) — no API tokens.
 
 ## Usage
 
@@ -29,6 +30,13 @@ And answer the questions to generate a new Python package.
 
 After copying the template, you might still have to do some additional configuration.
 
+### Publish to PyPI
+
+The generated package ships with a `cd.yaml` workflow that publishes to PyPI on `vX.Y.Z` tag pushes via [Trusted Publishing](https://docs.pypi.org/trusted-publishers/).
+See [Publishing to PyPI](publishing.md) for the one-time setup steps.
+
+You don't have to publish right away, but if you care about the project name, push an early `0.0.1` release to claim it on PyPI before someone else does.
+
 ### Deploy documentation
 
 #### Read the Docs
diff --git a/docs/publishing.md b/docs/publishing.md
@@ -0,0 +1,20 @@
+# First publication to PyPI
+
+The generated package ships with a `.github/workflows/cd.yaml` workflow that publishes to PyPI on `vX.Y.Z` tag pushes, via [PyPI Trusted Publishing](https://docs.pypi.org/trusted-publishers/) — so you never need to store a PyPI API token as a repository secret.
+
+Before the **first** release can succeed, you have to do the steps below once.
+Subsequent releases only require a tag push; see the generated package's own developer guide for that.
+
+## One-time setup
+
+1. **Push the generated package to GitHub.**
+2. **Create a PyPI project** (or a [pending publisher](https://docs.pypi.org/trusted-publishers/creating-a-project-through-oidc/) if the project doesn't exist yet).
+3. **Register the Trusted Publisher.** On PyPI, go to *Your projects → Publishing* and add a new publisher with:
+    - **Owner**: your GitHub user or organisation
+    - **Repository**: the generated repository name
+    - **Workflow name**: `cd.yaml`
+    - **Environment name**: `pypi`
+4. **Create the `pypi` environment** on the GitHub repository (*Settings → Environments → New environment*).
+   The environment name must match what you registered on PyPI, and must exist before you push your first release tag — otherwise the `publish` job will fail to start.
+
+You can optionally add required reviewers on the `pypi` environment to gate releases on manual approval.
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -11,4 +11,5 @@ nav:
   - design.md
   - dev-standards.md
   - semantics.md
+  - publishing.md
   - developer.md
diff --git a/template/.github/workflows/cd.yaml b/template/.github/workflows/cd.yaml
@@ -0,0 +1,48 @@
+name: cd
+
+on:
+  push:
+    tags:
+      - 'v[0-9]*.[0-9]*.[0-9]*'
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+
+      - name: Install Hatch
+        run: pip install hatch
+
+      - name: Build sdist and wheel
+        run: hatch build
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
diff --git a/template/docs/developer.md.jinja b/template/docs/developer.md.jinja
@@ -355,3 +355,37 @@ And the following rules for the files in the `tests` directory:
 | --------- | ------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
 | `INP001`  | [implicit-namespace-package](https://docs.astral.sh/ruff/rules/implicit-namespace-package/)                               | When tests are not part of the package, there is no need for `__init__.py` files.                                                   |
 | `S101`    | [assert](https://docs.astral.sh/ruff/rules/assert/)                                                                       | Asserts should not be used in production environments, but are fine for tests.                                                      |
+
+## Release
+
+{% if docs == 'myst' -%}
+:::{important}
+Before the **first** release works, the repository has to be registered as a PyPI [Trusted Publisher](https://docs.pypi.org/trusted-publishers/) and a `pypi` GitHub environment has to exist.
+See the [`python-copier` first-publication guide](https://mbercx.github.io/python-copier/publishing/) for that one-time setup — you only do it once per project.
+:::
+{%- endif %}
+{%- if docs == 'mkdocs' %}
+!!! important
+    Before the **first** release works, the repository has to be registered as a PyPI [Trusted Publisher](https://docs.pypi.org/trusted-publishers/) and a `pypi` GitHub environment has to exist.
+    See the [`python-copier` first-publication guide](https://mbercx.github.io/python-copier/publishing/) for that one-time setup — you only do it once per project.
+{%- endif %}
+
+Releases of `{{ package_name }}` are cut by pushing a `vX.Y.Z` tag to GitHub.
+The `cd` workflow under `.github/workflows/cd.yaml` then builds an sdist and wheel with Hatch and publishes them to PyPI.
+
+1. Bump the version in `src/{{ package_name }}/__about__.py` to the new release version.
+   The easiest way is:
+
+        hatch version <new-version>
+
+   Commit the bump on `main` (e.g. via a PR).
+
+2. Tag the bump commit and push the tag:
+
+        git tag -a v<new-version> -m '🚀 Release v<new-version>'
+        git push origin v<new-version>
+
+3. The `cd` workflow picks up the tag, builds the distributions, and publishes them to PyPI.
+
+The git tag and the version in `__about__.py` must agree.
+PyPI only sees the version baked into the built distribution, so a mismatch will silently publish under the wrong version (or be rejected as a duplicate of an existing release), and re-tagging after the fact is awkward.
