Configuration¶

Configuration is read from a file which can be specified using the --config option to semantic-release. Python Semantic Release currently supports a configuration in either TOML or JSON format, and will attempt to auto-detect and parse either format.

When using a JSON-format configuration file, Python Semantic Release looks for its settings beneath a top-level semantic_release key; when using a TOML-format configuration file, Python Semantic Release first checks for its configuration under the table [tool.semantic_release] (in line with the convention for Python tools to require their configuration under the top-level tool table in their pyproject.toml file), followed by [semantic_release], which may be more desirable if using a file other than the default pyproject.toml for configuration.

The examples on this page are given in TOML format, however there is no limitation on using JSON instead. In fact, if you would like to convert any example below to its JSON equivalent, the following commands will do this for you (in Bash):

export TEXT="<the TOML to convert>"

cat <<EOF | python3
import tomlkit, json
print(json.dumps(tomlkit.loads('''$TEXT'''), indent=4))
EOF

A note on null¶

In TOML, there is no such thing as a “null” or “nil” value, and this isn’t planned as a language feature according to the relevant GitHub issue. In Python Semantic Release, options which default to None are inferred from the relevant configuration settings not being present at all in your configuration. Because of this limitation, it’s currently not possible to explicitly specify those settings as “null” in TOML-format configuration. Technically it is possible in JSON-format configuration, but it’s recommended to keep consistency and just omit the relevant settings.

Environment Variables¶

Some settings are best pulled from environment variables rather than being stored in plaintext in your configuration file. Python Semantic Release can be configured to look for an environment variable value to use for a given setting, but this feature is not available for all settings. In order to use an environment variable for a setting, you must indicate in your configuration file the name of the environment variable to use.

The traditional and most common use case for environment variable use is for passing authentication tokens to Python Semantic Release. You do NOT want to hard code your authentication token in your configuration file, as this is a security risk. A plaintext token in your configuration file could be exposed to anyone with access to your repository, including long after its deleted if a token is in your git history. Instead, define the name of the environment variable which contains your remote.token, such as GH_TOKEN, in your configuration file, and Python Semantic Release will do the rest, as seen below.

[semantic_release.remote.token]
env = "GH_TOKEN"

Given basic TOML syntax compatibility, this is equivalent to:

[semantic_release.remote]
token = { env = "GH_TOKEN" }

The general format for specifying that some configuration should be sourced from an environment variable is:

[semantic_release.variable]
env = "ENV_VAR"
default_env = "FALLBACK_ENV_VAR"
default = "default value"

In this structure:

env represents the environment variable that Python Semantic Release will search for
default_env is a fallback environment variable to read in case the variable specified by env is not set. This is optional - if not specified then no fallback will be used.
default is a default value to use in case the environment variable specified by env is not set. This is optional - if default is not specified then the environment variable specified by env is considered required.

`semantic_release` settings¶

The following sections outline all the definitions and descriptions of each supported configuration setting. If there are type mis-matches, PSR will throw validation errors upon load. If a setting is not provided, than PSR will fill in the value with the default value.

Python Semantic Release expects a root level key to start the configuration definition. Make sure to use the correct root key dependending on the configuration format you are using.

Note

If you are using pyproject.toml, this heading should include the tool` prefix as specified within PEP 517, resulting in [tool.semantic_release].

Note

If you are using a releaserc.toml, use [semantic_release] as the root key

Note

If you are using a releaserc.json, semantic_release must be the root key in the top level dictionary.

`allow_zero_version`¶

Type: bool

This flag controls whether or not Python Semantic Release will use version numbers aligning with the 0.x.x pattern.

If set to true and starting at 0.0.0, a minor bump would set the next version as 0.1.0 whereas a patch bump would set the next version as 0.0.1. A breaking change (ie. major bump) would set the next version as 1.0.0 unless the major_on_zero is set to false.

If set to false, Python Semantic Release will consider the first possible version to be 1.0.0, regardless of patch, minor, or major change level. Additionally, when allow_zero_version is set to false, the major_on_zero setting is ignored.

Default: true

`assets`¶

Type: list[str]

One or more paths to additional assets that should committed to the remote repository in addition to any files modified by writing the new version.

Default: []

`branches`¶

This setting is discussed in more detail at Multibranch Releases

Default:

[semantic_release.branches.main]
match = "(main|master)"
prerelease_token = "rc"
prerelease = false

`build_command`¶

Type: Optional[str]

Command to use to build the current project during semantic-release version.

Python Semantic Release will execute the build command in the OS default shell with a subset of environment variables. PSR provides the variable NEW_VERSION in the environment with the value of the next determined version. The following table summarizes all the environment variables that are passed on to the build_command runtime if they exist in the parent process.

If you would like to pass additional environment variables to your build command, see build_command_env.

Variable Name	Description
CI	Pass-through `true` if exists in process env, unset otherwise
BITBUCKET_CI	`true` if Bitbucket CI variables exist in env, unset otherwise
GITHUB_ACTIONS	Pass-through `true` if exists in process env, unset otherwise
GITEA_ACTIONS	Pass-through `true` if exists in process env, unset otherwise
GITLAB_CI	Pass-through `true` if exists in process env, unset otherwise
HOME	Pass-through `HOME` of parent process
NEW_VERSION	Semantically determined next version (ex. `1.2.3`)
PATH	Pass-through `PATH` of parent process
PSR_DOCKER_GITHUB_ACTION	Pass-through `true` if exists in process env, unset otherwise
VIRTUAL_ENV	Pass-through `VIRTUAL_ENV` if exists in process env, unset otherwise

Default: None (not specified)

`build_command_env`¶

Type: Optional[list[str]]

List of environment variables to include or pass-through on to the build command that executes during semantic-release version.

This configuration option allows the user to extend the list of environment variables from the table above in build_command. The input is a list of strings where each individual string handles a single variable definition. There are two formats accepted and are detailed in the following table:

FORMAT	Description
`VAR_NAME`	Detects value from the PSR process environment, and passes value to `build_command` process
`VAR_NAME=value`	Sets variable name to value inside of `build_command` process

Note

Although variable name capitalization is not required, it is recommended as to be in-line with the POSIX-compliant recommendation for shell variable names.

Default: None (not specified)

`changelog`¶

This section outlines the configuration options available that modify changelog generation.

Note

pyproject.toml: [tool.semantic_release.changelog]

releaserc.toml: [semantic_release.changelog]

releaserc.json: { "semantic_release": { "changelog": {} } }

`changelog_file`¶

Type: str

Specify the name of the changelog file (after template rendering has taken place).

Default: "CHANGELOG.md"

`environment`¶

Note

This section of the configuration contains options which customize the template environment used to render templates such as the changelog. Most options are passed directly to the jinja2.Environment constructor, and further documentation one these parameters can be found there.

Note

pyproject.toml: [tool.semantic_release.changelog.environment]

releaserc.toml: [semantic_release.changelog.environment]

releaserc.json: { "semantic_release": { "changelog": { "environment": {} } } }

`autoescape`¶

Type: Union[str, bool]

If this setting is a string, it should be given in module:attr form; Python Semantic Release will attempt to dynamically import this string, which should represent a path to a suitable callable that satisfies the following:

As of Jinja 2.4 this can also be a callable that is passed the template name and has to return True or False depending on autoescape should be enabled by default.

The result of this dynamic import is passed directly to the jinja2.Environment constructor.

If this setting is a boolean, it is passed directly to the jinja2.Environment constructor.

Default: true