diff --git a/docs/user/trusted-publishers/troubleshooting.md b/docs/user/trusted-publishers/troubleshooting.md
index e9a45aba4974..4136da28449e 100644
--- a/docs/user/trusted-publishers/troubleshooting.md
+++ b/docs/user/trusted-publishers/troubleshooting.md
@@ -51,7 +51,9 @@ endpoint:
   is well-formed (and has a valid signature), but doesn't match any known
   (pending) OIDC publisher. This likely indicates a mismatch between the
   OIDC publisher specified in the user/project settings and the claims
-  represented in the actual OIDC token. Check for typos!
+  represented in the actual OIDC token. Check for typos! If you're using
+  GitHub Actions, check if the workflow is using the same environment
+  as configured when the publisher was configured on PyPI.
 
 [reusable workflows]: https://docs.github.com/en/actions/using-workflows/reusing-workflows
 
diff --git a/docs/user/trusted-publishers/using-a-publisher.md b/docs/user/trusted-publishers/using-a-publisher.md
index 07af43776fbb..76dc79bf481d 100644
--- a/docs/user/trusted-publishers/using-a-publisher.md
+++ b/docs/user/trusted-publishers/using-a-publisher.md
@@ -19,6 +19,8 @@ jobs:
   pypi-publish:
     name: upload release to PyPI
     runs-on: ubuntu-latest
+    # Specifying a GitHub environment is optional, but strongly encouraged
+    environment: release
     permissions:
       # IMPORTANT: this permission is mandatory for trusted publishing
       id-token: write
@@ -37,6 +39,8 @@ flow, your diff might look like this:
    pypi-publish:
      name: upload release to PyPI
      runs-on: ubuntu-latest
++    # Specifying a GitHub environment is optional, but strongly encouraged
++    environment: release
 +    permissions:
 +      # IMPORTANT: this permission is mandatory for trusted publishing
 +      id-token: write