Publish to PyPI with OIDC trusted publisher

This commit will update Python package publishing to the newest format
recommended by PyPI. This project previously published packages with a
project-scoped PyPI API token (token only valid for this project) stored
in GitHub Secrets and the `hatch publish` command. The project will now
publish packages using a PyPI OIDC (OpenID Connect) trusted publisher
with the pypa/gh-action-pypi-publish action. This is the method that
Hatch uses (Hatch does not "dogfood" its own `hatch publish` feature).

The advantage to OIDC is that authentication is performed with temporary
API tokens (only valid for 15 minutes) instead of persistent tokens that
must be manually generated on PyPI and pasted into GitHub Secrets. The
disadvantage is that authentication is more complicated.

To use PyPI OIDC, a trusted publisher was set up for the PyPI project
as shown in the [PyPI docs](https://docs.pypi.org/trusted-publishers/).
Next, a dedicated GitHub Actions deployment environment was created for
PyPI, with protection rules that only allow use of the environment with
workflow runs triggered by Git tags. The environment protection rules
combine with tag protection rules in existing GitHub rulesets to ensure
PyPI packages can only be published when a maintainer pushes a Git tag.

The GitHub Actions workflow will be updated to use the deployment
environment. Deployment environments must be selected at the job level
before the job begins, so a setup job will be added that selects the
appropriate deployment environment and passes it to the PyPI job.
Finally, after `hatch build` outputs the package build files to the
`dist/` directory, pypa/gh-action-pypi-publish will be used to publish
the package to PyPI. The pypa/gh-action-pypi-publish action publishes
exact version tags like pypa/gh-action-pypi-publish@v1.8.14, and offers
Git branches for major and minor version numbers like
pypa/gh-action-pypi-publish@release/v1.8.

https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-pypi
https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment
https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets
https://docs.pypi.org/trusted-publishers/
https://github.com/pypa/gh-action-pypi-publish

.github/workflows/ci.yml

@@ -6,10 +6,37 @@ on:
     branches: [develop, main]
     tags: ["[0-9]+.[0-9]+.[0-9]+*"]
   workflow_dispatch:
+    inputs:
+      environment:
+        description: GitHub Actions deployment environment
+        required: false
+        type: environment
 
 jobs:
+  setup:
+    runs-on: ubuntu-latest
+    outputs:
+      environment: ${{ steps.set-env.outputs.environment }}
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set GitHub Actions deployment environment
+        id: set-env
+        run: |
+          if ${{ github.event_name == 'workflow_dispatch' }}; then
+            environment=${{ inputs.environment }}
+          elif ${{ github.ref_type == 'tag' }}; then
+            environment="PyPI"
+          else
+            environment=""
+          fi
+          echo "environment=$environment" >>"$GITHUB_OUTPUT"
+      - name: Create annotation for deployment environment
+        if: steps.set-env.outputs.environment != ''
+        run: echo "::notice::Deployment environment ${{ steps.set-env.outputs.environment }}"
   ci:
     runs-on: ubuntu-latest
+    needs: [setup]
+    environment: ${{ needs.setup.outputs.environment }}
     permissions:
       id-token: write
     strategy:
@@ -97,8 +124,11 @@ jobs:
       - name: Build Python package
         run: hatch build
       - name: Publish Python package to PyPI
-        if: github.ref_type == 'tag' && matrix.python-version == '3.11'
-        run: hatch publish -n -u __token__ -a ${{ secrets.PYPI_TOKEN }}
+        if: >
+          github.ref_type == 'tag' &&
+          matrix.python-version == '3.11' &&
+          needs.setup.outputs.environment == 'PyPI'
+        uses: pypa/gh-action-pypi-publish@release/v1.8
   changelog:
     if: github.ref_type == 'tag'
     needs: [ci]