Making Your First Release#
This guide covers creating your first release on a repository that already uses Jupyter Releaser.
Write access to the target repository
Publish access to PYPI and/or npm assets associated with the repo
Generate a GitHub Access token with access to target GitHub repo to run GitHub Actions
Add the token as
ADMIN_GITHUB_TOKENin the repository secrets of your fork. The token must have
If the repo generates PyPI release(s), create a scoped PyPI token. We recommend using a scoped token for security reasons.
You can store the token as
PYPI_TOKENin your fork’s
Advanced usage: if you are releasing multiple repos, you can create a secret named
PYPI_TOKENthat is formatted as follows:
If you have multiple Python packages in the same repository, you can point to them as follows:
If the repo generates npm release(s), add access token for npm, saved as
Go to the “Actions” tab in your fork of
Select the “Draft Changelog” workflow on the left
Click on the “Run workflow” dropdown button on the right
Fill in the appropriate parameters
The “New Version Spec” will usually be the full version (e.g. 0.7.1). Repos using
tbumpcan also use the “next” option, which will bump the micro version (or the build version in the case of a prerelease). The “minor” option allows projects using “tbump” to bump to the next minor version directly.
Use the “since” field to select PRs prior to the latest tag to include in the release
Type “true” in the “since the last stable git tag” if you would like to include PRs since the last non-prerelease version tagged on the target repository and branch.
The workflow will use the GitHub API to find the relevant pull requests and make an appropriate changelog entry.
The workflow will create a pull request to the target repository and branch. It will print the link in the “** Next Step **” job step.
Review Changelog PR#
Go to the pull request created by the “Draft Changelog” workflow
Review the contents, fixing typos or otherwise editing as necessary.
If there is a section called “Other Merged PRs”, it means those PRs did not have one of the appropriate labels. If desired, you can go label those PRs and then re-run the workflow, or move the entries manually to the desired section. The appropriate labels are: bug, maintenance, enhancement, feature, and documentation.
The PR will lay out which steps you should take next based on how the “Draft Changelog” workflow was run.
Merge the PR
Delete the temporary branch
Return to your fork of
Click on the “Actions” tab
Select the “Full Release” workflow on the left
Click on the “Run workflow” button on the right
Fill in the entries as prompted by the automated changelog text
The additional “Post Version Spec” field should be used if your repo uses a dev version (e.g. 0.7.0.dev0)
The workflow will draft a GitHub release, publish assets to the appropriate registries.
If the workflow is not targeting the default branch, it will also generate a forward-port pull request for the changelog entry to the default branch.
When the workflow finishes it will print a link to the GitHub release and the forward-port PR (if appropriate) in the “** Next Step **” output.
Note If the publish portion fails you can attempt to publish the draft GitHub release given by the URL in the “** Failure Message **” using the “Publish Release” workflow.
Note GitHub Actions caches the secrets used on a given workflow run. So if you run into an auth issue, you’ll need to run a new workflow instead of re-running the existing workflow.
Review and merge the forward-port PR if applicable
Announce the release on appropriate channels