⚠️ Warning ⚠️
Simple Releaser is beta software and still being tested. Expect rough edges and breaking changes.
Simple Releaser
Simple Releaser is a configurable command-line tool for validating, building, tagging, and publishing Python package releases.
The PyPI distribution is named simple-releaser. Once installed, it can be
invoked as either simple-releaser or release.
Simple Releaser grew out of a direct copy of the release workflow used by the QRtsy Project, which was itself just a copy of similar tooling that I've used in several other projects. This version of the tool has since been updated significantly to generalize it in order to accommodate different release workflows. While Simple Releaser is very configurable, it is deliberately designed to be simple and is unlikely to grow much beyond this initial vision. If you've got more complex needs, you may wish to consider some alternatives.
Project assumptions
Run Simple Releaser from a directory containing the releaser configuration
(releaser.toml by default). This directory may also be the project root,
or the releaser configuration may point at a separate project directory.
The project being released is expected to have:
- Project configuration, including name and version, in
pyproject.toml. - A changelog file named
CHANGELOG.md, withUnreleasedand version sections. - A Git repo with an
originremote.
When publishing a repository release locally, the project is also expected to have:
- A repository hosted by Codeberg, Forgejo, Gitea, GitHub, or GitLab, including supported self-hosted instances.
- Publication credentials configured through the publisher, environment, or system keyring, as appropriate for the destination.
Installation
A convenient way to install Simple Releaser as a standalone command-line
tool is with pipx:
pipx install simple-releaser
Once installed, Simple Releaser can then be invoked as either:
release
or:
simple-releaser
Commands
The available CLI commands are:
$ release --help
Simple Releaser
Validate, build, and publish Python project releases.
Usage:
release [options] COMMAND [arguments]
Main command:
run Run the complete release workflow
Release steps:
validate Validate release readiness
check Run configured project quality checks
build Build and archive the current version
tag Create and push the release tag
to_repo Publish the repository release
to_pypi Publish distributions to PyPI or TestPyPI
Setup and inspection:
init Initialize Simple Releaser configuration
show Show resolved configuration and project information
is_clean Check for a clean Git repository
auth Manage publication authentication
help Show help for Simple Releaser or a command
Options:
-h, --help show this help message and exit
-V, --version show the version number and exit
--dry-run show what would be done without making changes
Initialization
Simple Releaser requires a configuration file in the current working directory.
By default it is named releaser.toml. To use a different filename, set the
RELEASER_CONFIG environment variable to the desired name.
Run release init from the directory where the releaser configuration should
live:
release init
If that directory contains the pyproject.toml for a project, Simple Releaser
creates a minimal releaser.toml for that project. Otherwise it prompts for
the project directory and then records the given project_path in the generated
configuration. Relative paths are used when possible. An existing releaser
configuration is never overwritten.
The init command also creates a text file with configuration examples that
is named with the same prefix as the releaser configuration file so both files
will always be generated near each other. Default is releaser-examples.txt.
Configuration
While the existence of a configuration file is required, its contents are optional
unless overrides to default configuration are desired. An exception is when
the current working directory does not also contain the project's pyproject.toml.
If the project lives elsewhere, project_path is required and must identify a
directory containing pyproject.toml. Relative paths are resolved from the
directory containing the releaser configuration; absolute paths are also
accepted. In this case, the minimum configuration might be:
project_path = "../my-project"
Set auto_confirm = true at the top level to allow PyPI or TestPyPI publication
without an interactive confirmation prompt, for example in a deliberately
unattended release workflow. It defaults to false.
Build artifacts are archived under _releases/<version>/ beside the releaser
configuration file. If _releases is in the project directory, Simple Releaser
creates a .gitignore file to exclude it from Git. Set
gitignore_releases = false at the top level to disable this behavior.
Configuration default values
For reference, the default values for the configuration settings are as follows:
project_path = "."
tag_prefix = "v"
auto_confirm = false
gitignore_releases = true
pypi = "pypi"
[commands]
check = []
build = "{python} -m build --outdir {output}"
publish = "{python} -m twine upload -r {pypi} {dist_dir}/*"
run = "validate check build tag to_repo to_pypi"
[auth]
keyring = "keyring"
[auth.repo]
source = "environment"
[auth.pypi]
source = "publisher"
See later sections of this readme for more details about each of these settings.
See the examples file generated by init for authentication settings and examples.
Configurable commands
The [commands] section currently supports check, build, publish, and run.
A value may be either a shell-like string or a TOML array of argument strings.
The following forms are equivalent:
check = "uv run pytest"
check = ["uv", "run", "pytest"]
Quoting in a string may be used to preserve spaces within one argument:
check = 'python -c "print(1 + 1)"'
An empty string or empty array disables the task associated with that configured command. For example:
[commands]
check = "" # disables 'check' task
build = "" # disables 'build' task
publish = "" # disables 'to_pypi' task
run = "" # disables the entire pipeline
Configuring check
The configured check command is the project's generic handoff to its own
release-readiness policy. Tests, linters, type checks, documentation checks,
project-specific validation, or any other prerequisite can live behind this one
command. Since that policy is project-specific, check is disabled by default
and must be customized for the project:
[commands]
check = ""
Simple Releaser deliberately does not try to model all of those project-specific
tasks itself. A useful pattern is to point check at a project task runner, so
the same check task can be used during development, in CI, and during a
release without duplicating workflow configuration. Command strings are parsed
into arguments but are not executed through a shell; compound shell logic is
therefore also usually cleaner inside a task runner or project script.
The Simple Releaser project dogfoods
its own tooling for releases of itself and uses Poe the Poet
as the task runner for its check task. This is defined in the project's
releaser.toml like so:
[commands]
check = "hatch run poe check"
See the project's pyproject.toml for the poe check task configuration to see
what it runs as part of its pre-release project check.
See Project Checks and Task Runners for a discussion of various other Task Runners that can be used in similar ways.
Configuring build and publish
By default, Simple Releaser builds its release artifacts with build and publishes with twine:
[commands]
build = "{python} -m build --outdir {output}"
publish = "{python} -m twine upload -r {pypi} {dist_dir}/*"
Custom build and publish commands may also use {python}, which expands to the
absolute path of the Python interpreter running Simple Releaser. This lets
an override deliberately use a tool installed alongside Simple Releaser rather
than whichever python happens to be on PATH.
The {output} placeholder in build is replaced with the temporary staging
dist/ directory where the build command must write its distributions. A
non-empty custom build command must include {output}. Publish commands may use
{release_dir} for the release archive root and {dist_dir} for its distribution
subdirectory. Publish commands may also use {pypi},
which expands to the selected pypi or testpypi service name. A custom publish
command does not have to use a placeholder when the command already knows how to
locate the artifacts and which service it should publish to.
The default build and publish commands work with most standards-compliant build
backends declared in the [build-system] section of a project's pyproject.toml
configuration. Projects that prefer their project-management tool's native build
and publish commands can override the defaults. Typical equivalents are:
# Poetry
build = "poetry build --clean --output {output}"
publish = "poetry publish --dist-dir {dist_dir}"
# Hatch
build = "hatch build --clean {output}"
publish = "hatch publish --no-prompt {dist_dir}"
# uv
build = "uv build --no-sources --out-dir {output}"
publish = "uv publish {dist_dir}/*"
# PDM
build = "pdm build --dest {output}"
publish = "pdm publish --no-build --dest {dist_dir}"
The default PyPI publisher uses Twine's normal authentication mechanisms, including
keyring, .pypirc, and TWINE_* environment variables. PyPI and TestPyPI have
separate accounts and tokens; repository-specific .pypirc or keyring entries
are the clearest way to keep those credentials distinct. For repository-host
settings, Simple Releaser checks the process environment first and then falls
back to the .env file beside the releaser configuration.
Run release auth check to check whether configured tokens can be retrieved
and meet basic format requirements. This does not verify token validity against
the destination service or check publication permissions. Publisher-managed
tokens cannot be retrieved directly by Simple Releaser, so they cannot be checked.
To store a token with Simple Releaser, install the keyring CLI separately,
then run release auth set {repo,pypi}. This command stores the token and then
prints a configuration snippet to add to releaser.toml.
release auth delete {repo,pypi} deletes the token from the keyring.
Configuring run
The commands.run setting specifies the sequence of tasks executed by the run
command. Its default value is:
[commands]
run = "validate check build tag to_repo to_pypi"
The available tasks are validate, check, is_clean, build, tag,
to_repo, and to_pypi.
validate checks release readiness, including the project version and release
notes. It is the first task in the default sequence, but custom sequences may
omit it. Omitting validate skips these release readiness checks and may
allow an invalid release to proceed.
is_clean is an optional task that checks that the Git working tree is clean.
This check is already performed when building a new release, so including
is_clean in the run sequence is usually unnecessary.
Release archives and interrupted releases
A successful build creates _releases/<version>/, containing a dist/
subdirectory for distributions, RELEASE.md with the release notes,
SHA256SUMS for distribution checksums, and BUILD_COMMIT identifying the Git
commit used to build the archive. A release can contain multiple wheels and at
most one source distribution (.tar.gz).
If a run sequence is interrupted after the archive is built, running it again
reuses the verified archive instead of rebuilding. In that case, check and
build are skipped, even if they appear in commands.run. The remaining tasks
still execute, including validate if configured. The archived commit is used
for tagging, so later changes to HEAD or the working tree do not change which
source revision is released. An existing archive must pass verification before
it can be reused.
To force a new build, invoke release build directly. Replacing an existing
archive requires interactive confirmation and is refused if the release tag
already exists. You can choose whether to retain the previous archive in
_releases/.backups/ after a successful replacement. An interrupted installation
may also leave a backup in the same location for manual recovery.
Local and CI release strategies
The run sequence also determines where the release process stops.
The default sequence performs the complete release locally:
[commands]
run = "validate check build tag to_repo to_pypi"
For a project whose remote CI publishes after a release tag is pushed, omit the local publication tasks:
[commands]
run = "validate check build tag"
Here the local build acts as a packaging preflight. Simple Releaser verifies
that the distributions can be built and archived before tag creates and pushes
the release tag. The remote workflow may then rebuild the tagged source and
publish its own artifacts.
Projects with expensive, platform-specific, or otherwise CI-authoritative builds may omit the local build as well:
[commands]
run = "validate check tag"
In this form, Simple Releaser runs the project's configured check command and
then creates and pushes the release tag; the remote workflow is responsible for
both building and publishing. This avoids a duplicate local build, but a
packaging failure will not be discovered until after the release tag has been
pushed.
The configured check in these examples remains the project's own quality-check
command, such as its tests, linters, and type checks. It is separate from Simple
Releaser's release validation, which is the first task in the release sequence.
Because tag pushes the tag to origin, it can serve directly as the handoff to
a tag-triggered CI workflow. Simple Releaser does not need to know which CI
system handles the tag or how that system builds and publishes the release.
When a release tag already exists locally or on origin, Simple Releaser reuses
it only if it resolves to the expected release commit. A conflicting tag aborts
the release rather than being overwritten.
For a concrete GitHub Actions workflow using PyPI Trusted Publishing, see GitHub Actions and PyPI Trusted Publishing.
Repository host
Simple Releaser normally determines the repository host and repository identifier
from the project's Git origin. HTTPS and SSH origins on codeberg.org, gitea.com,
github.com, and gitlab.com are recognized automatically.
When automatic detection is insufficient, the following settings can override it:
repo_hostselects the hosting service:codeberg,forgejo,gitea,github, orgitlab.repo_base_urloverrides the server URL derived from Gitorigin. This is primarily useful for self-hosted instances. Specify the web URL, not the API URL. Simple Releaser constructs API URLs automatically.<HOST>_REPOSITORYenvironment variable specifies the repository receiving the release, overriding the repository identifier derived from Git. For example,GITLAB_REPOSITORY=group/project.
For example, to use a self-hosted GitLab instance:
repo_host = "gitlab"
repo_base_url = "https://git.example.org"
Repository overrides may be set as environment variables or in the
.env file beside releaser.toml; an exported environment variable takes
precedence over the same .env entry.
To publish to a Codeberg repository, set CODEBERG_TOKEN. Set
CODEBERG_REPOSITORY=owner/repo to override the repository identifier derived
from the Git origin.
To publish to a Forgejo repository, set FORGEJO_TOKEN and configure
repo_host = "forgejo". Simple Releaser derives the instance URL from the Git
origin unless repo_base_url overrides it. Set FORGEJO_REPOSITORY=owner/repo to
override the derived repository identifier.
To publish to a Gitea repository, set GITEA_TOKEN. Set
GITEA_REPOSITORY=owner/repo to override the derived repository identifier.
For self-hosted Gitea, configure repo_host = "gitea"; use repo_base_url only when
the instance URL cannot be inferred correctly from the Git origin.
To publish to a GitHub repository, set GITHUB_TOKEN. Set
GITHUB_REPOSITORY=owner/repo to override the derived repository identifier.
The GitHub token must have permission to create releases and upload release
assets.
To publish to a GitLab.com repository, set GITLAB_TOKEN. Set
GITLAB_REPOSITORY=namespace/repo to override the derived repository
identifier. Nested namespaces such as group/subgroup/repo are supported.
The GitLab token must have permission to create releases, upload project files,
and create release asset links.
PyPI service
The to_pypi task publishes to production PyPI by default. To exercise the
publishing workflow without affecting the production index, select TestPyPI:
pypi = "testpypi"
The accepted values are "pypi" and "testpypi". TestPyPI is a separate service
from production PyPI and requires its own account and API token.
Before uploading with the default Twine command, Simple Releaser checks the
selected index for an existing release of the same version. If one exists,
it compares the published distribution filenames and SHA-256 checksums with
the archive. Matching, missing, or conflicting files are reported, so you can
decide how to handle an already-published or partially published version.
This check does not apply to custom publishing commands or a custom
TWINE_REPOSITORY_URL endpoint.
Development
For development purposes, some project checks and a test runner are defined as Poe tasks:
poe lint
poe format-check
poe typecheck
poe test
# Run all of the above
poe check
The test suite can also be run across the matrix of supported Python versions, which currently includes Python 3.11, 3.12, 3.13, and 3.14, using another Poe task:
poe test-matrix
A separate packaging smoke test creates isolated test environments, installs the Simple Releaser wheel and sdist package artifacts, and performs some basic checks to verify that the packages are actually installable. This test can be invoked with another Poe task:
poe package-smoke
Finally, a more thorough check meant for CI runs the linters, type checks, tests across all supported Python versions, and the packaging smoke test. It can also be invoked locally via a Poe task:
poe ci
Metadata
Release files for simple-releaser 0.3.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| simple_releaser-0.3.0.tar.gz | 101.0 kB | Without provenance | Details for simple_releaser-0.3.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| simple_releaser-0.3.0-py3-none-any.whl | Python 3 | none | any | Details for simple_releaser-0.3.0-py3-none-any.whl |
Total release size: 157.0 kB
Release files / simple_releaser-0.3.0.tar.gz
| Download URL | simple_releaser-0.3.0.tar.gz |
|---|---|
| Size | 101.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
68b9928b495a6112767851cf0a474407f5bc493f906e703931a63a00c34a9130
|
|
BLAKE2b-256 checksum How to use checksums |
955af272c157e0dd6bd65f4e06d621827221159d016f0b74bbcc0b01218695ca
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.13
|
Release files / simple_releaser-0.3.0-py3-none-any.whl
| Download URL | simple_releaser-0.3.0-py3-none-any.whl |
|---|---|
| Size | 56.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
843788fa213976b02ddb9517027fb66a4d23f830f95ce5271f7e55d735c21875
|
|
BLAKE2b-256 checksum How to use checksums |
a4d2639e7109cf6883c883194240d9f578f9d11f2a62afc75268837d39bfd595
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.13
|
Security for simple-releaser 0.3.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.