attestations: document in README.md

Author: facutuesca

README.md

@@ -246,6 +246,25 @@ for example. See [Creating & using secrets]. While still secure,
 [trusted publishing] is now encouraged over API tokens as a best practice
 on supported platforms (like GitHub).
 
+### Generating and uploading attestations (EXPERIMENTAL)
+
+> [!NOTE]
+> Support for generating and uploading [PEP 740 attestations] is currently
+> experimental and limited only to Trusted Publishing flows using PyPI or TestPyPI.
+
+You can generate signed [PEP 740 attestations] for all the distribution files and
+upload them all together by enabling the `attestations` setting:
+
+```yml
+   with:
+     attestations: true
+```
+
+This will use `sigstore` to create attestation objects for each distribution package,
+signing them with the identity provided by the GitHub's OIDC token associated with the
+current workflow. This means both the trusted publishing authentication and the
+attestations are tied to the same identity.
+
 ## License
 
 The Dockerfile and associated scripts and documentation in this project
@@ -287,3 +306,5 @@ https://github.com/vshymanskyy/StandWithUkraine/blob/main/docs/README.md
 [configured on PyPI]: https://docs.pypi.org/trusted-publishers/adding-a-publisher/
 
 [how to specify username and password]: #specifying-a-different-username
+
+[PEP 740 attestations]: https://peps.python.org/pep-0740/