README: document OIDC publishing

Signed-off-by: William Woodruff <[email protected]>

Author: woodruffw

README.md

@@ -61,6 +61,46 @@ PyPI, which is recommended to restrict the access the action has.
 The secret used in `${{ secrets.PYPI_API_TOKEN }}` needs to be created on the
 settings page of your project on GitHub. See [Creating & using secrets].
 
+### Publishing with OpenID Connect
+
+**IMPORTANT**: This functionality is in beta, and will not work for you
+unless you're a member of the PyPI OIDC beta testers' group. For more
+information, see
+[warehouse#12965](https://github.com/pypi/warehouse/issues/12965).
+
+This action supports PyPI's
+[OpenID Connect publishing](https://pypi.org/help/#openid-connect)
+implementation, which allows authentication to PyPI without a manually
+configured API token or username/password combination. To perform
+OIDC publishing with this action, your project's OIDC publisher must
+already be configured on PyPI.
+
+To enter the OIDC flow, configure this action's job with the `id-token: write`
+permission and **without** an explicit username or password:
+
+```yaml
+jobs:
+  pypi-publish:
+    name: upload release to PyPI
+    runs-on: ubuntu-latest
+    permissions:
+      # IMPORTANT: this permission is mandatory for OIDC publishing
+      id-token: write
+    steps:
+      # retrieve your distributions here
+
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+```
+
+Other indices that support OIDC publishing can also be used, like TestPyPI:
+
+```yaml
+- name: Publish package distributions to TestPyPI
+  uses: pypa/gh-action-pypi-publish@release/v1
+  with:
+    repository-url: https://test.pypi.org/legacy/
+```
 
 ## Non-goals