README: document OIDC publishing

Signed-off-by: William Woodruff <william@trailofbits.com>

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