Use a PR for Release Commits

.github/actions/check-release/action.yml

@@ -14,20 +14,18 @@ inputs:
 runs:
   using: "composite"
   steps:
-    - shell: bash -eux {0}
-      id: install-releaser
+    - id: install-releaser
+      shell: bash
       run: |
-        # Install Jupyter Releaser from git unless we are testing Releaser itself
-        if ! command -v jupyter-releaser &> /dev/null
-        then
-            pip install -q git+https://github.com/jupyter-server/jupyter_releaser.git@v2
-        fi
+        cd "${{ github.action_path }}/../../scripts"
+        bash install-releaser.sh
 
     - id: prep-release
       shell: bash -eux {0}
       run: |
         export RH_DRY_RUN="true"
         export GITHUB_ACCESS_TOKEN=${{ inputs.token }}
+        export GITHUB_REF=""
         export RH_VERSION_SPEC=${{ inputs.version_spec }}
         export RH_STEPS_TO_SKIP=${{ inputs.steps_to_skip }}
         python -m jupyter_releaser.actions.prep_release
@@ -37,6 +35,7 @@ runs:
       run: |
         export RH_DRY_RUN="true"
         export GITHUB_ACCESS_TOKEN=${{ inputs.token }}
+        export GITHUB_REF=""
         export RH_RELEASE_URL=${{ steps.prep-release.outputs.release_url }}
         export RH_STEPS_TO_SKIP=${{ inputs.steps_to_skip }}
         export YARN_UNSAFE_HTTP_WHITELIST=0.0.0.0
@@ -46,6 +45,7 @@ runs:
       shell: bash -eux {0}
       run: |
         export RH_DRY_RUN="true"
+        export GITHUB_REF=""
         export GITHUB_ACCESS_TOKEN=${{ inputs.token }}
         export RH_RELEASE_URL=${{ steps.populate-release.outputs.release_url }}
         export RH_STEPS_TO_SKIP=${{ inputs.steps_to_skip }}

.github/actions/finalize-release/action.yml

@@ -4,6 +4,9 @@ inputs:
   token:
     description: "GitHub access token"
     required: true
+  personal_access_token:
+    description: "GitHub PAT used to create pull requests"
+    required: false
   target:
     description: "The owner/repo GitHub target"
     required: false
@@ -33,18 +36,16 @@ runs:
   using: "composite"
   steps:
     - name: install-releaser
-      shell: bash -eux {0}
+      shell: bash
       run: |
-        # Install Jupyter Releaser from git unless we are testing Releaser itself
-        if ! command -v jupyter-releaser &> /dev/null
-        then
-            pip install -q git+https://github.com/jupyter-server/jupyter_releaser.git@v2
-        fi
+        cd "${{ github.action_path }}/../../scripts"
+        bash install-releaser.sh
 
     - id: finalize-release
       shell: bash -eux {0}
       run: |
         export GITHUB_ACCESS_TOKEN=${{ inputs.token }}
+        export PERSONAL_ACCESS_TOKEN=${{ inputs.personal_access_token }}
         export GITHUB_ACTOR=${{ github.triggering_actor }}
         export RH_REPOSITORY=${{ inputs.target }}
         export RH_DRY_RUN=${{ inputs.dry_run }}

.github/actions/install-releaser/action.yml

@@ -6,9 +6,5 @@ runs:
     - shell: bash
       id: install-releaser
       run: |
-        set -eux
-        # Install Jupyter Releaser from git unless we are testing Releaser itself
-        if ! command -v jupyter-releaser &> /dev/null
-        then
-            pip install -q git+https://github.com/jupyter-server/jupyter_releaser.git@v2
-        fi
+        cd "${{ github.action_path }}/../../scripts"
+        bash install-releaser.sh

.github/actions/populate-release/action.yml

@@ -4,6 +4,9 @@ inputs:
   token:
     description: "GitHub access token"
     required: true
+  personal_access_token:
+    description: "GitHub PAT used to create pull requests"
+    required: false
   target:
     description: "The owner/repo GitHub target"
     required: false
@@ -30,18 +33,16 @@ runs:
   using: "composite"
   steps:
     - name: install-releaser
-      shell: bash -eux {0}
+      shell: bash
       run: |
-        # Install Jupyter Releaser from git unless we are testing Releaser itself
-        if ! command -v jupyter-releaser &> /dev/null
-        then
-            pip install -q git+https://github.com/jupyter-server/jupyter_releaser.git@v2
-        fi
+        cd "${{ github.action_path }}/../../scripts"
+        bash install-releaser.sh
 
     - id: populate-release
       shell: bash -eux {0}
       run: |
         export GITHUB_ACCESS_TOKEN=${{ inputs.token }}
+        export PERSONAL_ACCESS_TOKEN=${{ inputs.personal_access_token }}
         export GITHUB_ACTOR=${{ github.triggering_actor }}
         export RH_REPOSITORY=${{ inputs.target }}
         export RH_DRY_RUN=${{ inputs.dry_run }}

.github/actions/prep-release/action.yml

@@ -35,13 +35,10 @@ runs:
   using: "composite"
   steps:
     - name: install-releaser
-      shell: bash -eux {0}
+      shell: bash
       run: |
-        # Install Jupyter Releaser from git unless we are testing Releaser itself
-        if ! command -v jupyter-releaser &> /dev/null
-        then
-            pip install -q git+https://github.com/jupyter-server/jupyter_releaser.git@v2
-        fi
+        cd "${{ github.action_path }}/../../scripts"
+        bash install-releaser.sh
 
     - id: prep-release
       shell: bash -eux {0}

.github/scripts/bump_tag.sh

@@ -1,7 +1,7 @@
 set -eux
 
-# Update the v1 tag for GitHub Actions consumers
+# Update the stable tag for GitHub Actions consumers
 if [[ ${RH_DRY_RUN:=true} != 'true' ]]; then
-    git tag -f -a v2 -m "Github Action release"
+    git tag -f -a v3 -m "Github Action release"
     git push origin -f --tags
 fi

.github/scripts/install-releaser.sh

@@ -0,0 +1,10 @@
+set -eux
+# Install Jupyter Releaser if it is not already installed
+
+SCRIPT_DIR=$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )
+
+if ! command -v jupyter-releaser &> /dev/null
+then
+    cd "${SCRIPT_DIR}/../.."
+    pip install -e .
+fi

.gitignore

@@ -128,8 +128,9 @@ dmypy.json
 # Pyre type checker
 .pyre/
 
-# Local git checkout
+# Local git checkouts
 .jupyter_releaser_checkout
+.jupyter_release_bare_repo
 
 # macOS
 .DS_Store

CONTRIBUTING.md

@@ -52,3 +52,12 @@ To run the Python tests, use:
 ```bash
 pytest
 ```
+
+## End to End Verification Testing
+
+If you're making substantial changes, you may want to test the release workflow
+on a test repo that uses `TWINE_REPOSITORY_URL: https://test.pypi.org/legacy/`.
+
+Update the actions on that repo to point to your releaser fork and branch, e.g.
+
+`uses: blink1073/jupyter_releaser/.github/actions/populate-release@use-pr-for-changes`

docs/source/background/theory.md

@@ -46,12 +46,12 @@ Detailed workflows are available to draft a changelog, draft a release, publish
   - Builds tarball(s) using `npm pack`
   - Make sure tarball(s) can be installed and imported in a new npm package
 - Adds a commit that includes the hashes of the dist files
-- Creates an annotated version tag in standard format
 - If given, bumps the version using the post version spec. he post version
   spec can also be given as a setting, [Write Releaser Config Guide](../how_to_guides/write_config.md).
 - Verifies that the SHA of the most recent commit has not changed on the target
   branch, preventing a mismatch of release commit.
-- Pushes the commits and tag to the target `branch`
+- Creates a Pull Request with the release and optional post version commit and
+  automatically merges the PR.
 - Pusehes the created assets to the draft release, along with an `asset_shas.json` file capturing the checksums of the files.
 
 ### Finalize Release Action
@@ -61,6 +61,7 @@ Detailed workflows are available to draft a changelog, draft a release, publish
 - Downloads the dist assets from the release
 - Verifies shas of release assets against the `asset_shas.json` file.
 - Publishes assets to appropriate registries.
+- Creates an annotated version tag in standard format and pushes to the remote.
 - Publishes the final GitHub release
 - If the tag is on a backport branch, makes a forwardport PR for the changelog entry
 

docs/source/get_started/making_release_from_releaser.md

@@ -12,12 +12,22 @@ already uses Jupyter Releaser.
 
 - Fork `jupyter_releaser`
 
-- Generate a [GitHub Access token](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token) with access to target GitHub repo to run GitHub Actions
+- Generate a [GitHub Access token](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token) with access to target GitHub repo to run GitHub Actions.  You must use a classic
+  token since it will need writes to multiple repositories.
 
-- Add 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) of your fork. The token must have `repo` and `workflow` scopes.
+- Add the token as `PERSONAL_ACCESS_TOKEN` in the [repository secrets](https://docs.github.com/en/actions/reference/encrypted-secrets#creating-encrypted-secrets-for-a-repository) of your fork. The token must have `repo` and `workflow` scopes.
 
 - Set up PyPI:
 
+<details><summary>Using PyPI trusted publisher (modern way)</summary>
+
+- Set up your PyPI project by [adding a trusted publisher](https://docs.pypi.org/trusted-publishers/adding-a-publisher/)
+  - if you use the example workflows, the _workflow name_ is `publish-release.yml` (or `full-release.yml`) and the
+    _environment_ should be set to the release environment configured on PyPI.
+- Ensure the publish release job as `permissions`: `id-token : write` (see the [documentation](https://docs.pypi.org/trusted-publishers/using-a-publisher/))
+
+</details>
+
 <details><summary>Using PyPI token (legacy way)</summary>
 
 - If the repo generates PyPI release(s), create a scoped PyPI [token](https://packaging.python.org/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows/#saving-credentials-on-github). We recommend using a scoped token for security reasons.
@@ -40,15 +50,6 @@ already uses Jupyter Releaser.
 
 </details>
 
-<details><summary>Using PyPI trusted publisher (modern way)</summary>
-
-- Set up your PyPI project by [adding a trusted publisher](https://docs.pypi.org/trusted-publishers/adding-a-publisher/)
-  - if you use the example workflows, the _workflow name_ is `publish-release.yml` (or `full-release.yml`) and the
-    _environment_ should be left blank.
-- Ensure the publish release job as `permissions`: `id-token : write` (see the [documentation](https://docs.pypi.org/trusted-publishers/using-a-publisher/))
-
-</details>
-
 - If the repo generates npm release(s), add access token for [npm](https://docs.npmjs.com/creating-and-viewing-access-tokens), saved as `NPM_TOKEN` in "Secrets".
 
 > If you want to set _provenance_ on your package, you need to ensure the publish release job as `permissions`: `id-token : write` (see the [documentation](https://docs.npmjs.com/generating-provenance-statements#publishing-packages-with-provenance-via-github-actions)).

docs/source/get_started/making_release_from_repo.md

@@ -5,8 +5,9 @@ already uses Jupyter Releaser using workflows on its own repository.
 
 ## Prerequisites
 
-- Admin write access to the target repository
-- Previously set up GitHub Actions secrets for PyPI and/or NPM
+- Access to run the workflow, and approve deployments in the environment
+  if applicable.
+- Previously set up GitHub Actions secrets for PERSONAL_ACCESS_TOKEN, PYPI_TOKEN (if not using trusted publishers) and/or NPM_TOKEN.
 
 ## Prep Release
 

docs/source/how_to_guides/convert_repo_from_releaser.md

@@ -19,7 +19,7 @@ A. Prep the `jupyter_releaser` fork:
 - [ ] Clone this repository onto your GitHub user account.
 
 - [ ] Add a GitHub [personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) with access to target GitHub repo to run
-  GitHub Actions, saved as `ADMIN_GITHUB_TOKEN` in the
+  GitHub Actions, saved as `PERSONAL_ACCESS_TOKEN` in the
   [repository secrets](https://docs.github.com/en/actions/reference/encrypted-secrets#creating-encrypted-secrets-for-a-repository).
   The token will need "public_repo", and "repo:status" permissions.
 
@@ -47,7 +47,7 @@ A. Prep the `jupyter_releaser` fork:
 
 <details><summary>Using PyPI trusted publisher (modern way)</summary>
 
-- Set up your PyPI project by [adding a trusted publisher](https://docs.pypi.org/trusted-publishers/adding-a-publisher/)
+- Set up your PyPI project by [adding a trusted publisher](https://docs.pypi.org/trusted-publishers/adding-a-publisher/) pointing to your releaser fork repository and release workflow file.
   - if you use the example workflows, the _workflow name_ is `publish-release.yml` (or `full-release.yml`) and the
     _environment_ should be left blank.
 - Ensure the publish release job as `permissions`: `id-token : write` (see the [documentation](https://docs.pypi.org/trusted-publishers/using-a-publisher/))

docs/source/how_to_guides/convert_repo_from_repo.md

@@ -16,17 +16,28 @@ 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.
+- [ ] Add a GitHub [personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token), preferably a fine-grained personal access token. For fine-grained personal tokens, the org must be configured to allow them.  The org should "Require administrator approval" for fine-grained tokens.  We need this
+  access token to allow the workflows to run when a pull request is
+  created by the action.
+  The fine-grained token should have the org as its
+  "Resource owner" and have "Pull Request: Read and Write" permissions
+  on the target repository. The token will have to have an expiration, but can be regenerated in the UI.  Save the token as
+  `PERSONAL_ACCESS_TOKEN`
+  in the [Environment secrets](https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment#environment-secrets) for the environment used in the release workflow, which is "release" in the default template.  There is no need to store the token anywhere
+  else, since it is only used for this purpose and can be re-generated
+  when expired.
 
 - [ ] Set up PyPI:
 
+<details><summary>Using PyPI trusted publisher (modern way)</summary>
+
+- Set up your PyPI project by [adding a trusted publisher](https://docs.pypi.org/trusted-publishers/adding-a-publisher/)
+  - if you use the example workflows, the _workflow name_ is `publish-release.yml` (or `full-release.yml`) and the
+    _environment_ should match the GitHub environment used in the PyPI trusted publisher setup.
+- Ensure the publish release job as `permissions`: `id-token : write` (see the [documentation](https://docs.pypi.org/trusted-publishers/using-a-publisher/))
+
+</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`.
@@ -36,15 +47,6 @@ See checklist below for details:
 
 </details>
 
-<details><summary>Using PyPI trusted publisher (modern way)</summary>
-
-- Set up your PyPI project by [adding a trusted publisher](https://docs.pypi.org/trusted-publishers/adding-a-publisher/)
-  - if you use the example workflows, the _workflow name_ is `publish-release.yml` (or `full-release.yml`) and the
-    _environment_ should be left blank.
-- Ensure the publish release job as `permissions`: `id-token : write` (see the [documentation](https://docs.pypi.org/trusted-publishers/using-a-publisher/))
-
-</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

example-workflows/full-release.yml

@@ -25,18 +25,23 @@ on:
 jobs:
   full_release:
     runs-on: ubuntu-latest
+    # The use of an environment is important for security, and required if you
+    # use PyPI trusted publisher.
+    environment: release
     permissions:
       # This is useful if you want to use PyPI trusted publisher
       # and NPM provenance
       id-token: write
+      contents: write
+      pull-requests: write
     steps:
       - uses: jupyterlab/maintainer-tools/.github/actions/base-setup@v1
 
       - name: Prep Release
         id: prep-release
         uses: jupyter-server/jupyter_releaser/.github/actions/prep-release@v2
         with:
-          token: ${{ secrets.ADMIN_GITHUB_TOKEN }}
+          token: ${{ secrets.GITHUB_TOKEN }}
           version_spec: ${{ github.event.inputs.version_spec }}
           post_version_spec: ${{ github.event.inputs.post_version_spec }}
           branch: ${{ github.event.inputs.branch }}
@@ -47,7 +52,8 @@ jobs:
         id: populate-release
         uses: jupyter-server/jupyter_releaser/.github/actions/populate-release@v2
         with:
-          token: ${{ secrets.ADMIN_GITHUB_TOKEN }}
+          token: ${{ secrets.GITHUB_TOKEN }}
+          personal_access_token: ${{ secrets.PERSONAL_ACCESS_TOKEN }}
           branch: ${{ github.event.inputs.branch }}
           release_url: ${{ steps.prep-release.outputs.release_url }}
           steps_to_skip: ${{ github.event.inputs.steps_to_skip }}
@@ -62,7 +68,8 @@ jobs:
           NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
         uses: jupyter-server/jupyter-releaser/.github/actions/finalize-release@v2
         with:
-          token: ${{ secrets.ADMIN_GITHUB_TOKEN }}
+          token: ${{ secrets.GITHUB_TOKEN }}
+          personal_access_token: ${{ secrets.PERSONAL_ACCESS_TOKEN }}
           release_url: ${{ steps.populate-release.outputs.release_url }}
 
       - name: "** Next Step **"

example-workflows/prep-release.yml

@@ -29,7 +29,7 @@ jobs:
         id: prep-release
         uses: jupyter-server/jupyter_releaser/.github/actions/prep-release@v2
         with:
-          token: ${{ secrets.ADMIN_GITHUB_TOKEN }}
+          token: ${{ secrets.GITHUB_TOKEN }}
           version_spec: ${{ github.event.inputs.version_spec }}
           post_version_spec: ${{ github.event.inputs.post_version_spec }}
           branch: ${{ github.event.inputs.branch }}