
# 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 recreate this file, run 'release init' in the directory containing
your Simple Releaser configuration. Existing configuration is preserved.

________________________________________________________________________

GENERAL SETTINGS

These options are optional. Simple Releaser supplies defaults for them.

 repo_host = "forgejo"            # Usually discovered; required with repo_url
 repo_url = "https://example.org" # Custom/self-hosted instance base URL
 pypi = "testpypi"                # Default: "pypi"
 tag_prefix = "v"                 # Prefix prepended to the version tag
 auto_confirm = false             # Require confirmation before PyPI publishing
 gitignore_releases = true        # Create .gitignore inside release archive directory

________________________________________________________________________

AUTHENTICATION

PyPI authentication defaults to 'publisher': the default Twine uploader
handles its own authentication, including supported environment/keyring
mechanisms.

Repository host authentication defaults to 'environment' and derives the
token variable name from the host (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 one `[auth.pypi]` example from the list below. 

More settings:

- If using a custom publishing command with managed PyPI 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 actual secret token values in the configuration file.
- DO NOT commit .env files containing secrets to version control.

________________________________________________________________________

EXAMPLE 1 - PyPI authentication managed by publisher  [PYPI DEFAULT]

Simple Releaser delegates PyPI authentication to the publisher:

[auth.pypi]
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.

________________________________________________________________________

EXAMPLE 2 - Repo token from environment  [REPO DEFAULT]

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

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


________________________________________________________________________

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

________________________________________________________________________

EXAMPLE 4 - PyPI token from environment

PyPI token from an environment variable or adjacent .env file.
With the default uploader, TWINE_PASSWORD is the default variable.

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

________________________________________________________________________

EXAMPLE 5 - PyPI token from keyring

Run 'release auth set pypi' 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.pypi]
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 pypi      Store a PyPI token in the keyring
release auth delete repo   Delete a repo token from the keyring
release auth delete pypi   Delete a PyPI token from the keyring
