Configuration

Configuration options can be given in three ways:

  • setup.cfg file in a [semantic_release] section

  • pyproject.toml file in a [tool.semantic_release] section

  • -D option, like so:

    semantic-release <command> -D <option_name>=<option_value>
    

Each location has priority over the ones listed above it.

Releases

branch

The branch to run releases from.

Default: master

version_variable

The file and variable name of where the version number is stored, for example:

semantic_release/__init__.py:__version__

You can specify multiple version variables (i.e. in different files) by providing comma-separated list of such strings:

semantic_release/__init__.py:__version__,docs/conf.py:version

In pyproject.toml specifically, you can also use the TOML list syntax to specify multiple versions:

[tool.semantic_release]
version_variable = [
    'semantic_release/__init__.py:__version__',
    'docs/conf.py:version',
]

version_pattern

Similar to config-version_variable, but allows the version number to be identified using an arbitrary regular expression:

README.rst:VERSION (\d+\.\d+\.\d+)

The regular expression must contain a parenthesized group that matches the version number itself. Anything outside that group is just context. For example, the above specifies that there is a version number in README.rst preceded by the string “VERSION”.

If the pattern contains the string {version}, it will be replaced with the regular expression used internally by python-semantic-release to match semantic version numbers. So the above example would probably be better written as:

README.rst:VERSION {version}

As with config-version_variable, it is possible to specify multiple version patterns in pyproject.toml.

version_source

The way we get and set the new version. Can be commit or tag.

  • If set to tag, will get the current version from the latest tag matching vX.Y.Z. This won’t change the source defined in version_variable.
  • If set to commit, will get the current version from the source defined in version_variable, edit the file and commit it.

Default: commit

patch_without_tag

If this is set to true, semantic-release will create a new patch release even if there is no tag in any commits since the last release.

Default: false

Commit Parsing

commit_parser

Import path of a Python function that can parse commit messages and return information about the commit as described in Parsing of commit logs.

The following parsers are built in to Python Semantic Release:

  • semantic_release.history.angular_parser()

    The default parser, which uses the Angular commit style with the following differences:

    • Multiple BREAKING CHANGE: paragraphs are supported
    • revert is not currently supported
  • semantic_release.history.emoji_parser()

    Parser for commits using one or more emojis as tags in the subject line.

    If a commit contains multiple emojis, the one with the highest priority (major, minor, patch, none) or the one listed first is used as the changelog section for that commit. Commits containing no emojis go into an “Other” section.

    See major_emoji, minor_emoji and patch_emoji. The default settings are for Gitmoji.

  • semantic_release.history.tag_parser()

    The original parser from v1.0.0 of Python Semantic Release. Similar to the emoji parser above, but with less features.

major_emoji

Comma-separated list of emojis used by semantic_release.history.emoji_parser() to create major releases.

Default: :boom:

minor_emoji

Comma-separated list of emojis used by semantic_release.history.emoji_parser() to create minor releases.

Default: :sparkles:, :children_crossing:, :lipstick:, :iphone:, :egg:, :chart_with_upwards_trend:

patch_emoji

Comma-separated list of emojis used by semantic_release.history.emoji_parser() to create patch releases.

Default: :ambulance:, :lock:, :bug:, :zap:, :goal_net:, :alien:, :wheelchair:, :speech_balloon:, :mag:, :apple:, :penguin:, :checkered_flag:, :robot:, :green_apple:

Commits

commit_version_number

Whether or not to commit changes when bumping version.

Default: True if version_source is tag, False if version_source is commit

commit_subject

Git commit subject line. Accepts the following variables as format fields:

Variable Contents
{version} The new version number in the format X.Y.Z.

Default: {version}

commit_message

Git commit message body. Accepts the following variables as format fields:

Variable Contents
{version} The new version number in the format X.Y.Z.

Default: Automatically generated by python-semantic-release

commit_author

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

Default: semantic-release <semantic-release>

Note

If you are using the built-in GitHub Action, this is always set to github-actions <actions@github.com>.

Changelog

changelog_sections

Comma-separated list of sections to display in the changelog. They will be displayed in the order they are given.

The available options depend on the commit parser used.

Default: feature, fix, breaking, documentation, performance plus all the default emojis for semantic_release.history.emoji_parser.

changelog_components

A comma-separated list of the import paths of components to include in the changelog.

The following components are included in Python Semantic Release:

  • semantic_release.changelog.changelog_headers()

    Only component displayed by default.

    List of commits between this version and the previous one, with sections and headings for each type of change present in the release.

  • semantic_release.changelog.changelog_table()

    List of commits between this version and the previous one, dsplayed in a table.

  • semantic_release.changelog.compare_url()

    Link to view a comparison between this release and the previous one on GitHub. Only appears when running through semantic-release publish.

    If you are using a different HVCS, the link will not be included.

It is also possible to create your own components. Each component is simply a function which returns a string, or None if it should be skipped, and may take any of the following values as keyword arguments:

changelog A dictionary with section names such as feature as keys, and the values are lists of (SHA, message) tuples. There is a special section named breaking for breaking changes, where the same commit can appear more than once with a different message.
changelog_sections A list of sections from changelog which the user has set to be displayed.
version The current version number in the format X.X.X, or the new version number when publishing.
previous_version The previous version number. Only present when publishing, None otherwise.

You can should use **kwargs to capture any arguments you don’t need.

Distributions

upload_to_pypi

If set to false the pypi uploading will be disabled. See PYPI_TOKEN which must also be set for this to work.

upload_to_release

If set to false, do not upload distributions to GitHub releases. If you are not using GitHub, this will be skipped regardless.

dist_path

The relative path to the folder for dists configured for setuptools. This allows for customized setuptools processes.

Default: dist/

remove_dist

Flag for whether the dist folder should be removed after a release.

Default: true

build_command

Command to build dists. Build output should be stored in the directory configured in dist_path. If necessary, multiple commands can be specified using &&, e.g. pip install -m flit && flit build.

Default: python setup.py sdist bdist_wheel

HVCS

hvcs

The name of your hvcs. Currently only GitHub and GitLab are supported.

Default: github

check_build_status

If enabled, the status of the head commit will be checked and a release will only be created if the status is success.

Default: false