docs: Added documentation around the GitHub Actions Environments used…

… by the various reusable workflows

workflows/package-build.md

@@ -5,6 +5,10 @@ This workflow will build the package using the
 action, and then verify that the package can be installed on each combination of Python version
 and operating system specified.
 
+> [!NOTE]
+> When building the Python package, this workflow will run in the `package-build` GitHub Actions environment.
+> This environment will be created in the repository that calls this workflow. No additional setup is required.
+
 > [!IMPORTANT]
 > When calling this reusable workflow, the permissions must be set as follows:
 >

workflows/package-release.md

@@ -31,6 +31,29 @@ will be used to fill in the GitHub Release Notes.
 > - Fixed
 > - Security
 
+> [!IMPORTANT]
+> This workflow uses several GitHub Actions environments.
+>
+> The `bump-version` job runs in the
+> `package-release-gate` environment. It is recommended to limit this environment to only the
+> `main` branch as well as enable the `Required reviewers` setting to enforce approval
+> before creating a new release of the package. It is also recommended to store the token used
+> to check out the repo and the SSH public/private keys as environment secrets so that
+> they can only be used by the `package-release-gate` environment. These secrets will need to be
+> passed in as secrets when calling the reusable workflow, see the [example](#example) below.
+>
+> The `upload-testpypi` job (run when `inputs.build-and-publish-python-package == true`) runs in the `package-testpypi` environment. It is recommended to
+> limit this environment to only the `main` branch. It is also recommended to store the token
+> for uploading to [test.pypi.org](https://test.pypi.org) as an environment secret so that it can only be
+> accessed by the `package-testpypi` environment. This secret will need to be passed in as a
+> secret when calling the reusable workflow, see the [example](#example) below.
+>
+> The `upload-pypi` job (run when `inputs.build-and-publish-python-package == true`) runs in the `package-release` environment. It is recommended to
+> limit this environment to only the `main` branch. It is also recommended to store the token
+> for uploading to [pypi.org](https://pypi.org) as an environment secret so that it can only be
+> accessed by the `package-release` environment. This secret will need to be passed in as a
+> secret when calling the reusable workflow, see the [example](#example) below.
+
 > [!IMPORTANT]
 > When calling this reusable workflow, the permissions must be set as follows:
 >
@@ -129,11 +152,11 @@ jobs:
       id-token: write
       attestations: write
     secrets:
-      checkout-token: ${{ secrets.CHECKOUT_TOKEN }}
-      ssh-signing-key-private: ${{ secrets.SSH_SIGNING_KEY_PRIVATE }}
-      ssh-signing-key-public: ${{ secrets.SSH_SIGNING_KEY_PUBLIC }}
-      pypi-api-token: ${{ secrets.PYPI_API_TOKEN }}
-      test-pypi-api-token: ${{ secrets.TEST_PYPI_API_TOKEN }}
+      checkout-token: ${{ secrets.CHECKOUT_TOKEN }}  # required for the `bump-version` job, recommended to store this in the `package-release-gate` environment
+      ssh-signing-key-private: ${{ secrets.SSH_SIGNING_KEY_PRIVATE }}  # required for the `bump-version` job, recommended to store this in the `package-release-gate` environment
+      ssh-signing-key-public: ${{ secrets.SSH_SIGNING_KEY_PUBLIC }}  # required for the `bump-version` job, recommended to store this in the `package-release-gate` environment
+      pypi-api-token: ${{ secrets.PYPI_API_TOKEN }}  # required for the `upload-pypi` job (run when `inputs.build-and-publish-python-package == true`), recommended to store this in the `package-release` environment
+      test-pypi-api-token: ${{ secrets.TEST_PYPI_API_TOKEN }}  # required for the `upload-testpypi` job (run when `inputs.build-and-publish-python-package == true`), recommended to store this in the `package-testpypi` environment
 ```
 
 [workflow-file]: ../.github/workflows/_reusable-package-release.yml

workflows/package-testpypi.md

@@ -9,6 +9,14 @@ In order to ensure each version uploaded to [TestPyPI](https://test.pypi.org) is
 workflow will first create a unique `.postN` version number for the package on top of the
 officially released version of the package, incrementing `N` each time the workflow runs.
 
+> [!IMPORTANT]
+> When uploading the Python package to [test.pypi.org](https://test.pypi.org), this workflow
+> will run in the `package-testpypi` GitHub Actions environment. It is recommended to
+> limit this environment to only the `main` branch. It is also recommended to store the token
+> for uploading to [test.pypi.org](https://test.pypi.org) as an environment secret so that it can only be
+> accessed by the `package-testpypi` environment. This secret will need to be passed in as a
+> secret when calling the reusable workflow, see the [example](#example) below.
+
 > [!IMPORTANT]
 > When calling this reusable workflow, the permissions must be set as follows:
 >