
# Simple Releaser configuration examples

This file is for reference only. Simple Releaser reads releaser.toml (or the alternative filename
selected by RELEASER_CONFIG), not this file. Copy only the settings you need into your actual
configuration file. For the full configuration reference, see the Simple Releaser documentation.

To regenerate this file, run 'release init' again (existing files will not be overwritten).

____________________________________________________________________________________________________

GENERAL SETTINGS

Simple Releaser supplies defaults for these optional settings.

  tag_prefix = "v"               # Prefix prepended to the version tag
  auto_confirm = false           # Prompt for confirmation before publishing
  subprocess_output = "live"     # "live" (default) or "errors"
  gitignore_releases = true      # Create .gitignore inside archive directory

____________________________________________________________________________________________________

REPOSITORY SETTINGS

Simple Releaser discovers values for these from Git origin by default.

  repo_remote = "origin"                       # Git remote for tags and repository publication
  repo_host = "forgejo"                        # Usually discovered; required with repo_base_url
  repo_base_url = "https://git.example.com"    # Usually discovered; may be customized

____________________________________________________________________________________________________

PACKAGE INDEX SETTINGS

Simple Releaser publishes to PyPI by default. To publish elsewhere, select an alternative index
using its upload URL.

  index_upload_url = "https://test.pypi.org/legacy/"    # TestPyPI
    or
  index_upload_url = "https://example.com/legacy/"      # Custom index

For custom indexes, the following optional settings enable project links and verification of an
existing-publication, respectively.

  index_project_base_url = "https://packages.example.com/project"   # To enable project links
  index_api_base_url = "https://packages.example.com/pypi"          # Verify existing-publication

Simple Releaser automatically selects a suitable destination environment variable for supported
publishers. Override it if necessary.

  publish_index_env = "CUSTOM_UPLOAD_URL"

Auto-selected 'publish_index_env' values for currently supported publishers include:

  Twine     TWINE_REPOSITORY_URL
  uv        UV_PUBLISH_URL
  Hatch     HATCH_INDEX_REPO
  PDM       PDM_PUBLISH_REPO
  Poetry    POETRY_REPOSITORIES_<NAME>_URL

No environment variable is needed if the publishing command uses the {index_url} placeholder or
otherwise specifies its own destination.

____________________________________________________________________________________________________

AUTHENTICATION

Package-index authentication defaults to 'publisher' which delegates management of authentication
tokens to the default Twine publisher. See Twine documentation for more.

Repository host authentication defaults to 'environment' which gets the token from an environment
variable or a local '.env' file. The default token variable name is derived from the host name
(e.g., CODEBERG_TOKEN or GITHUB_TOKEN).

No special auth configuration is needed to use these defaults. To override the default auth
configuration, choose one `[auth.repo]` and/or one `[auth.index]` example from the list below.

More settings:

- If using a custom publishing command with Simple Releaser-managed package-index authentication
  (environment or keyring), you must also configure 'publish_variable'. This identifies the variable
  used to deliver the token to the publisher.

- If using 'keyring' as an authentication source, it's assumed that the `keyring` CLI is on your
  executable path. If it's not, then set the `auth.keyring` setting to the correct path for your
  keyring executable.

    [auth]
    keyring = "/path/to/keyring"

Warnings:

- DO NOT store secret token values in the releaser configuration file.
- DO NOT commit .env files containing secrets to version control.

____________________________________________________________________________________________________

AUTH EXAMPLE 1 - Package-index authentication managed by publisher  [PYPI DEFAULT]

Simple Releaser delegates package-index authentication to the publisher:

  [auth.index]
  source = "publisher"

The default Twine uploader supports environment variables, .pypirc, and keyring, but does not
automatically load .env files. Twine's standard keyring lookup is based on the repository URL and
username, rather than the Python project. It therefore doesn't automatically select different
project-specific tokens for projects published to the same PyPI repository. To instead have Simple
Releaser select a project-specific token automatically, consider using the 'environment' or
'keyring' authentication sources.

____________________________________________________________________________________________________

AUTH EXAMPLE 2 - Repo token from environment  [REPO DEFAULT]

Repository token from an environment variable or local .env file.

  [auth.repo]
  source = "environment"
  variable = "MY_REPO_TOKEN"    # optional: override host-specific default


____________________________________________________________________________________________________

AUTH EXAMPLE 3 - Repo token from keyring

Repository token stored in the system keyring. Install the separate keyring CLI then run
'release auth set repo'. If token is shared with multiple projects, also set the shared 'profile'
value and choose a shared profile when running 'release auth set repo'.

  [auth.repo]
  source = "keyring"
  profile = "team"              # optional: shared with multiple projects

____________________________________________________________________________________________________

AUTH EXAMPLE 4 - Package-index token from environment

Package-index token from an environment variable or local .env file. With the default uploader,
TWINE_PASSWORD is the default variable.

  [auth.index]
  source = "environment"
  variable = "MY_PYPI_TOKEN"    # optional
  publish_variable = "MY_VAR"   # required for custom publishers

____________________________________________________________________________________________________

AUTH EXAMPLE 5 - Package-index token from keyring

Run 'release auth set index' to store a keyring token. The token retrieved from the keyring is then
passed into the publisher via a publisher-specific environment variable. With the default Twine
uploader, TWINE_PASSWORD is used automatically.

  [auth.index]
  source = "keyring"
  profile = "team"              # optional: shared with multiple projects
  publish_variable = "MY_VAR"   # required for custom publishers

____________________________________________________________________________________________________

USEFUL COMMANDS

  release show                Show resolved configuration

  release auth                Show commands and getting-started help
  release auth check          Check token retrieval and format
  release auth set repo       Store a repo token in the keyring
  release auth set index      Store a package-index token in the keyring
  release auth delete repo    Delete a repo token from the keyring
  release auth delete index   Delete a package-index token from the keyring
