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.

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

Given basic TOML syntax compatibility, this is equivalent to:

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

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

[tool.semantic_release.<setting>]
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.

Settings#

`[tool.semantic_release]`#

`assets (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:

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

`build_command (Optional[str])`#

Command to use when building the current project during semantic-release version

Default: None (not specified)

`commit_author (str)`#

Author used in commits in the format name <email>.

Note

If you are using the built-in GitHub Action, the default value is set to github-actions <actions@github.com>. You can modify this with the git_committer_name and git_committer_name inputs.

`commit_message (str)`#

Commit message to use when making release commits. The message can use {version} as a format key, in which case the version being released will be formatted into the message.

If at some point in your project’s lifetime you change this, you may wish to consider, adding the old message pattern(s) to exclude_commit_patterns.

Default: "{version}\n\nAutomatically generated by python-semantic-release"

`commit_parser (str)`#

Specify which commit parser Python Semantic Release should use to parse the commits within the Git repository.

Built-in parsers:

angular - AngularCommitParser
emoji - EmojiCommitParser
scipy - ScipyCommitParser
tag - TagCommitParser

You can set any of the built-in parsers by their keyword but you can also specify your own commit parser in module:attr form.

For more information see Commit Parsing.

Default: "angular"

`commit_parser_options (Dict[str, Any])`#

These options are passed directly to the parser_options method of the commit parser, without validation or transformation.

For more information, see Parser Options.

The default value for this setting depends on what you specify as commit_parser. The table below outlines the expections from commit_parser value to default options value.

`commit_parser`		Default `commit_parser_options`
`"angular"`	->	[tool.semantic_release.commit_parser_options] allowed_types = [ "build", "chore", "ci", "docs", "feat", "fix", "perf", "style", "refactor", "test" ] minor_types = ["feat"] patch_types = ["fix", "perf"]
`"emoji"`	->	[tool.semantic_release.commit_parser_options] major_tags = [":boom:"] minor_tags = [ ":sparkles:", ":children_crossing:", ":lipstick:", ":iphone:", ":egg:", ":chart_with_upwards_trend:" ] patch_tags = [ ":ambulance:", ":lock:", ":bug:", ":zap:", ":goal_net:", ":alien:", ":wheelchair:", ":speech_balloon:", ":mag:", ":apple:", ":penguin:", ":checkered_flag:", ":robot:", ":green_apple:" ]
`"scipy"`	->	[tool.semantic_release.commit_parser_options] allowed_tags = [ "API", "DEP", "ENH", "REV", "BUG", "MAINT", "BENCH", "BLD", "DEV", "DOC", "STY", "TST", "REL", "FEAT", "TEST", ] major_tags = ["API",] minor_tags = ["DEP", "DEV", "ENH", "REV", "FEAT"] patch_tags = ["BLD", "BUG", "MAINT"]
`"tag"`	->	[tool.semantic_release.commit_parser_options] minor_tag = ":sparkles:" patch_tag = ":nut_and_bolt:"
`"module:class"`	->	`**module:class.parser_options()`

Default: ParserOptions { ... }, where ... depends on commit_parser as indicated above.

`logging_use_named_masks (bool)`#

Whether or not to replace secrets identified in logging messages with named masks identifying which secrets were replaced, or use a generic string to mask them.

Default: false

`allow_zero_version (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

`major_on_zero (bool)`#

This flag controls whether or not Python Semantic Release will increment the major version upon a breaking change when the version matches 0.y.z. This value is set to true by default, where breaking changes will increment the 0 major version to 1.0.0 like normally expected.

If set to false, major (breaking) releases will increment the minor digit of the version while the major version is 0, instead of the major digit. This allows for continued breaking changes to be made while the major version remains 0.

From the Semantic Versioning Specification:

Major version zero (0.y.z) is for initial development. Anything MAY change at any time. The public API SHOULD NOT be considered stable.

When you are ready to release a stable version, set major_on_zero to true and run Python Semantic Release again. This will increment the major version to 1.0.0.

When allow_zero_version is set to false, this setting is ignored.

Default: true

`tag_format (str)`#

Specify the format to be used for the Git tag that will be added to the repo during a release invoked via semantic-release version. The format string is a regular expression, which also must include the format keys below, otherwise an exception will be thrown. It may include any of the optional format keys, in which case the contents described will be formatted into the specified location in the Git tag that is created.

For example, "(dev|stg|prod)-v{version}" is a valid tag_format matching tags such as:

dev-v1.2.3
stg-v0.1.0-rc.1
prod-v2.0.0+20230701

This format will also be used for parsing tags already present in the repository into semantic versions; therefore if the tag format changes at some point in the repository’s history, historic versions that no longer match this pattern will not be considered as versions.

Format Key	Mandatory	Contents
`{version}`	Yes	The new semantic version number, for example `1.2.3`, or `2.1.0-alpha.1+build.1234`

Tags which do not match this format will not be considered as versions of your project.

Default: "v{version}"

`version_variables (List[str])`#

Each entry represents a location where the version is stored in the source code, specified in file:variable format. For example:

[tool.semantic_release]
version_variables = [
    "semantic_release/__init__.py:__version__",
    "docs/conf.py:version",
]

Default: []

`version_toml (List[str])`#

Similar to version_variables (List[str]), but allows the version number to be identified safely in a toml file like pyproject.toml, with each entry using dotted notation to indicate the key for which the value represents the version:

[tool.semantic_release]
version_toml = [
    "pyproject.toml:tool.poetry.version",
]

Default: []

`[tool.semantic_release.changelog]`#

`template_dir (str)`#

If given, specifies a directory of templates that will be rendered during creation of the changelog. If not given, the default changelog template will be used.

This option is discussed in more detail at Changelog Templates

Default: "templates"

`changelog_file (str)`#

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

Default: "CHANGELOG.md"

`exclude_commit_patterns (List[str])`#

Any patterns specified here will be excluded from the commits which are available to your changelog. This allows, for example, automated commits to be removed if desired. Python Semantic Release also removes its own commits from the Changelog via this mechanism; therefore if you change the automated commit message that Python Semantic Release uses when making commits, you may wish to add the old commit message pattern here.

The patterns in this list are treated as regular expressions.

Default: []

`[tool.semantic_release.changelog.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.