scriv-release

Changesets-style release automation on top of scriv.

scriv already manages per-PR changelog fragments. scriv-release adds the missing pieces for fully automated releases:

A policy for mapping changelog categories to semver bump levels.
Orchestration commands (bump-level, next-version, collect, tag) that wrap scriv and a configurable version provider.
A GitHub Action that opens a "Changelog Preview" PR when fragments are pending, and tags a release once that PR is merged — the same flow popularized by Changesets in the JS ecosystem.

Quickstart

pip install "scriv-release[bump-my-version]"

# pyproject.toml
[tool.scriv-release]
version_provider = "bump-my-version"

In your repo's .github/workflows/release.yml:

on:
  push:
    branches: [main]

permissions: {}

jobs:
  release:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 0
          persist-credentials: false

      - uses: whitphx/scriv-release@v0.4.0
        with:
          client-id: ${{ vars.RELEASE_APP_CLIENT_ID }}
          app-private-key: ${{ secrets.RELEASE_APP_KEY }}

RELEASE_APP_CLIENT_ID and RELEASE_APP_KEY come from a GitHub App that you own. The action mints a short-lived installation token from the App so the tag-push it does at release time can trigger downstream workflows (the default GITHUB_TOKEN cannot — by design, to avoid recursion). To skip the manual App-creation flow, open

https://whitphx.github.io/scriv-release/install-app/

and click Create on your personal account (or fill the org name). GitHub's confirmation page is pre-populated with the recommended permissions (contents: write, pull_requests: write); submit, and the App is registered under your account. The page then walks you through generating a key, installing the App on the repo, and setting the secrets. See docs/token-setup.md for the longer explanation and a manual fallback.

For end-to-end onboarding, see docs/quickstart.md.

How it works

Two phases, branched on whether changelog fragments are present on HEAD:

Fragments present → scriv collect into a scriv-release-preview branch and open/update a "Changelog Preview" PR.
No fragments on HEAD, but fragments on HEAD~1 → that means the preview PR was just merged. Determine the bump level from HEAD~1's fragments, tag the release, push the tag.

This is the same file-presence-based detection Changesets uses, so it survives squash, rebase, and merge commits alike.

Status

Early scaffold. Public API and config keys may shift before 1.0.

License

MIT — see LICENSE.

Development Status
- 3 - Alpha
Intended Audience
- Developers
Programming Language
- Python :: 3
Topic
- Software Development :: Build Tools

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

scriv_release-0.7.0.tar.gz (145.8 kB view details)

Uploaded May 16, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

scriv_release-0.7.0-py3-none-any.whl (15.5 kB view details)

Uploaded May 16, 2026 Python 3

File details

Details for the file scriv_release-0.7.0.tar.gz.

File metadata

Download URL: scriv_release-0.7.0.tar.gz
Upload date: May 16, 2026
Size: 145.8 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.13

File hashes

Hashes for scriv_release-0.7.0.tar.gz
Algorithm	Hash digest
SHA256	`4ecd94dc74d457c1166d14ec6593954aadcab3ef6ac748d34ed3d0eac1a060f6`
MD5	`22c1b0993626a018677e64147d9fa91e`
BLAKE2b-256	`7880ae2514780b1229d802d938152e9ec737a9cad6323d2d1650f4cdffb34d35`

See more details on using hashes here.

Provenance

The following attestation bundles were made for scriv_release-0.7.0.tar.gz:

Publisher: publish.yml on whitphx/scriv-release

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: scriv_release-0.7.0.tar.gz
- Subject digest: 4ecd94dc74d457c1166d14ec6593954aadcab3ef6ac748d34ed3d0eac1a060f6
- Sigstore transparency entry: 1551810798
- Sigstore integration time: May 16, 2026
Source repository:
- Permalink: whitphx/scriv-release@591fbdc73d28e1fc559c92ead1e227f7aa05b2fa
- Branch / Tag: refs/tags/v0.7.0
- Owner: https://github.com/whitphx
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish.yml@591fbdc73d28e1fc559c92ead1e227f7aa05b2fa
- Trigger Event: push