Update the documentation

docs/source/background/theory.md

@@ -13,6 +13,13 @@ This project should help maintainers reduce toil and save time in the release pr
 - Dry run publish on CI
 - Revert to Dev version after release (optional)
 
+## Security
+
+We strive to use the most secure release practices possible, reflected in the `Checklist for Adoption`
+and the example workflows.
+This includes using PyPI Trusted Publishing, using GitHub Environments, encouraging the use of Rulesets and GitHub Apps with limited bypass capability, and provenance data for npm.
+In addition, there is an automatic check for whether the user who triggered the action is an admin.
+
 ## Action Details
 
 Detailed workflows are available to draft a changelog, draft a release, publish a release, and check a release.

docs/source/how_to_guides/convert_repo_from_repo.md

@@ -16,25 +16,30 @@ See checklist below for details:
 
 ## Checklist for Adoption
 
-- [ ] Add a GitHub [personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token), preferably from a "machine user" GitHub
-  account that has admin access to the repository. The token itself will
-  need "public_repo", and "repo:status" permissions. Save the token as
-  `ADMIN_GITHUB_TOKEN`
-  in the [repository secrets](https://docs.github.com/en/actions/reference/encrypted-secrets#creating-encrypted-secrets-for-a-repository). We need this
-  access token to allow for branch protection rules, which block the pushing
-  of commits when using the `GITHUB_TOKEN`, even when run from an admin user
-  account.
+- [ ] Set up a GitHub App on your organization (or personal account for a personal project).
 
-- [ ] Set up PyPI:
+  - Disable the web hook
+  - Enable Repository permissions > Contents > Read and write
+  - Select "Only on this account"
+  - Click "Create GitHub App"
+  - Browse to the App Settings
+  - Select "Install App" and install on all repositories
+  - Under "General" click "Generate a private key"
+  - Store the `APP_ID` and the private key in a secure location (Jupyter Vault if using a Jupyter Org)
 
-<details><summary>Using PyPI token (legacy way)</summary>
+- [ ] Create a "release" environment on your repository and add an `APP_ID` Environment Variable and `APP_PRIVATE_KEY` secret.
 
-- Add access token for the [PyPI registry](https://packaging.python.org/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows/#saving-credentials-on-github) stored as `PYPI_TOKEN`.
-  _Note_ For security reasons, it is recommended that you scope the access
-  to a single repository. Additionally, this token should belong to a
-  machine account and not a user account.
+- [ ] Configure Rulesets for the repository
 
-</details>
+  - Set up branch protection but only disable force pushes.
+  - Remove global tag protection.
+  - Add a branch Ruleset for all branches
+    - Allow the GitHub App to bypass protections
+    - Set up Pull Request and Required Checks
+  - Add a tags Ruleset for all tags
+    - Allow the GitHub App to bypass protections
+
+- [ ] Set up PyPI:
 
 <details><summary>Using PyPI trusted publisher (modern way)</summary>
 
@@ -45,10 +50,18 @@ See checklist below for details:
 
 </details>
 
+<details><summary>Using PyPI token (legacy way)</summary>
+
+- Add access token for the [PyPI registry](https://packaging.python.org/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows/#saving-credentials-on-github) stored as `PYPI_TOKEN`.
+  _Note_ For security reasons, it is recommended that you scope the access
+  to a single repository. Additionally, this token should belong to a
+  machine account and not a user account.
+
+</details>
+
 - [ ] If needed, add access token for [npm](https://docs.npmjs.com/creating-and-viewing-access-tokens), saved as `NPM_TOKEN`. Again this should
   be created using a machine account that only has publish access.
-- [ ] Ensure that only trusted users with 2FA have admin access to the
-  repository, since they will be able to trigger releases.
+- [ ] Ensure that only trusted users with 2FA have admin access to the repository, since they will be able to trigger releases.
 - [ ] Switch to Markdown Changelog
   - We recommend [MyST](https://myst-parser.readthedocs.io/en/latest/?badge=latest), especially if some of your docs are in reStructuredText.
   - Can use `pandoc -s changelog.rst -o changelog.md` and some hand edits as needed.

docs/source/how_to_guides/maintain_fork.md

@@ -2,7 +2,7 @@
 
 ## How to keep fork of Jupyter Releaser up to date
 
-- The manual workflow files target the `@v1` actions in the source repository, which means that as long as
+- The manual workflow files target the `@v2` actions in the source repository, which means that as long as
   the workflow files themselves are up to date, you will always be running the most up to date actions.
 
 - Make sure your workflow is up to date by checking the "Fetch Upstream" dropdown on the main page of your fork.