GitHub Actions¶
There are two official GitHub Actions for Python Semantic Release:
- python-semantic-release/python-semantic-release@TAG
This is the main action that runs the version CLI command. It is used to (1) determine the next version number, (2) stamp the version number, (3) run the build command, (4) build the changelog, (5) commit the changes, (6) tag the commit, (7) publish the commit & tag and lastly (8) create a GitHub release. For more information review the version command documentation and see below for the Action configuration options.
- python-semantic-release/publish-action@TAG
This action is used to execute the publish CLI command. It is used to upload files, such as distribution artifacts and other assets, to a GitHub release.
Note
These GitHub Actions are only simplified wrappers around the python-semantic-release CLI. Ultimately, they download and install the published package from PyPI so if you find that you are trying to do something more advanced or less common, you may need to install and use the CLI directly.
Python Semantic Release Action¶
The official Python Semantic Release GitHub Action is a GitHub Docker Action, which means at the beginning of the job it will build a Docker image that contains the Python Semantic Release package and its dependencies. It will then run the job step inside the Docker Container. This is done to ensure that the environment is consistent across all GitHub Runners regardless of platform. With this choice, comes some limitations of non-configurable options like a pre-defined python version, lack of installed build tools, and an inability to utilize caching.
The primary benefit of using the GitHub Action is that it is easy to set up and use for most projects. We handle a lot of the git configuration under the hood, so you don’t have to handle it yourself. There are a plenty of customization options available which are detailed individually below.
Most importantly your project’s configuration file will be used as normal, as your project will be mounted into the container for the action to use.
See also
action.yml: the code definition of the action
Inputs¶
GitHub Action inputs are used for select configuration and provide the necessary
information to execute the action. The inputs are passed to the action using the
with
keyword in the workflow file. Many inputs will mirror the command line
options available in the version command. This section
outlines each supported input and its purpose.
build
¶
Type: Literal["true", "false"]
Override whether the action should execute the build command or not. This option is
equivalent to adding the command line switch --skip-build
(when false
) to
the version command. If set to true
, no command line switch
is passed and the default behavior of the version is used.
Required: false
Note
If not set or set to true
, the default behavior is defined by the
version command and any user configurations.
See also
--skip-build option for the version command.
build_metadata
¶
Type: string
Explicitly set the build metadata of the version. This is equivalent to running the command:
semantic-release version --build-metadata <metadata>
Required: false
See also
--build-metadata [VALUE] option for the version command
changelog
¶
Type: Literal["true", "false"]
Override whether the action should generate a changelog or not. This option is
equivalent to adding either --changelog
(on true
) or --no-changelog
(on false
) to the version command.
Required: false
Note
If not set, the default behavior is defined by the version command and any user configurations.
See also
--changelog/--no-changelog options for the version command
commit
¶
Type: Literal["true", "false"]
Override whether the action should commit any changes to the local repository. Changes
include the version stamps, changelog, and any other files that are modified and added
to the index during the build command. This option is equivalent to adding either
--commit
(on true
) or --no-commit
(on false
) to the
version command.
Required: false
Note
If not set, the default behavior is defined by the version command and any user configurations.
See also
--commit/--no-commit options for the version command
directory
¶
If the project is not at the root of the repository (like in monorepos), you can specify a sub-directory to change into before running semantic-release.
Required: false
Default: .
force
¶
Type: Literal["prerelease", "patch", "minor", "major"]
Force the next version to be a specific bump type. This is equivalent to running the command:
semantic-release version --<type>
# Ex: force a patch level version bump
semantic-release version --patch
Required: false
See also
--major/--minor/--patch/--prerelease options for the version command
git_committer_email
¶
The email of the account used to commit. If customized, it must be associated with the provided token.
Required: false
git_committer_name
¶
The name of the account used to commit. If customized, it must be associated with the provided token.
Required: false
github_token
¶
The GitHub Token is essential for access to your GitHub repository to allow the push of commits & tags as well as to create a release. Not only do you need to provide the token as an input but you also need to ensure that the token has the correct permissions.
The token should have the following permissions:
id-token: write
contents: write
Required: true
prerelease
¶
Force the version to be a prerelease version when set to true
. This is equivalent
to running the command:
semantic-release version --as-prerelease
Required: false
Note
If not set, the default behavior is defined by the version command and any user configurations.
See also
--as-prerelease option for the version command
prerelease_token
¶
Override any prerelease token in the configuration file with this value, if it is
a pre-release. This will override the matching release branch configuration’s
prerelease_token
value. If you always want it to be a prerelease then you must
also set the prerelease input to true
.
This option is equivalent to running the command:
semantic-release version --prerelease-token <token>
Required: false
Note
If not set, the default behavior is defined by the version command and any user configurations.
See also
--prerelease-token [VALUE] option for the version command
push
¶
Type: Literal["true", "false"]
Override whether the action should push any commits or tags from the local repository
to the remote repository. This option is equivalent to adding either --push
(on
true
) or --no-push
(on false
) to the version command.
Required: false
Note
If not set, the default behavior is defined by the version command and any user configurations.
See also
--push/--no-push options for the version command
root_options
¶
Additional options for the main semantic-release
command, which will come
before the version subcommand.
Example
- uses: python-semantic-release/python-semantic-release@v9.12.0 with: root_options: "-vv --noop"This configuration would cause the command to be
semantic-release -vv --noop version
, which would run the version command verbosely but in no-operation mode.
Required: false
Default: -v
See also
Options for the semantic-release command
ssh_public_signing_key
¶
The public key associated with the private key used in signing a commit and tag.
Required: false
ssh_private_signing_key
¶
The private key used to sign a commit and tag.
Required: false
tag
¶
Type: Literal["true", "false"]
Override whether the action should create a version tag in the local repository. This
option is equivalent to adding either --tag
(on true
) or --no-tag
(on
false
) to the version command.
Required: false
Note
If not set, the default behavior is defined by the version command and any user configurations.
See also
--tag/--no-tag options for the version command
vcs_release
¶
Type: Literal["true", "false"]
Override whether the action should create a release on the VCS. This option is
equivalent to adding either --vcs-release
(on true
) or --no-vcs-release
(on false
) to the version command.
Required: false
Note
If not set, the default behavior is defined by the version command and any user configurations.
See also
--vcs-release/--no-vcs-release options for the version command
Outputs¶
The Python Semantic Release Action also provides outputs that can be used in subsequent steps of the workflow. These outputs are used to provide information about the release and any actions that were taken.
is_prerelease
¶
Type: Literal["true", "false"]
A boolean value indicating whether the released version is a prerelease.
released
¶
Type: Literal["true", "false"]
A boolean value indicating whether a release was made.
version
¶
Type: string
The newly released SemVer version string if one was made, otherwise the current version.
Example: 1.2.3
tag
¶
Type: string
The Git tag corresponding to the version
output but in
the tag format dictated by your configuration.
Example: v1.2.3
Python Semantic Release Publish Action¶
The official Python Semantic Release Publish Action is a GitHub Docker Action, which means at the beginning of the job it will build a Docker image that contains the Python Semantic Release package and its dependencies. It will then run the job step inside the Docker Container. This is done to ensure that the environment is consistent across all GitHub Runners regardless of platform. With this choice, comes some limitations of non-configurable options like a pre-defined python version, lack of additional 3rd party tools, and an inability to utilize caching.
The primary benefit of using the GitHub Action is that it is easy to set up and use for most projects. We handle some additional configuration under the hood, so you don’t have to handle it yourself. We do however provide a few customization options which are detailed individually below.
Most importantly your project’s configuration file will be used as normal, as your project will be mounted into the container for the action to use.
If you have issues with the action, please open an issue on the python-semantic-release/publish-action repository.
See also
action.yml: the code definition for the publish action
Inputs¶
GitHub Action inputs are used for select configuration and provide the necessary
information to execute the action. The inputs are passed to the action using the
with
keyword in the workflow file. Many inputs will mirror the command line
options available in the publish command and others will be
specific to adjustment of the action environment. This section outlines each
supported input and its purpose.
directory
¶
If the project is not at the root of the repository (like in monorepos), you can specify a sub-directory to change into before running semantic-release.
Required: false
Default: .
github_token
¶
The GitHub Token is essential for access to your GitHub repository to allow the publish of assets to a release. Not only do you need to provide the token as an input but you also need to ensure that the token has the correct permissions.
The token should have the following permissions:
contents: write
: Required for modifying a GitHub Release
Required: true
root_options
¶
Additional options for the main semantic-release
command, which will come
before the publish subcommand.
Example
- uses: python-semantic-release/publish-action@v9.8.9 with: root_options: "-vv --noop"This configuration would cause the command to be
semantic-release -vv --noop publish
, which would run the publish command verbosely but in no-operation mode.
Required: false
Default: -v
See also
Options for the semantic-release command
tag
¶
Type: string
The tag corresponding to the GitHub Release that the artifacts should be published to. This option is equivalent to running the command:
semantic-release publish --tag <tag>
Python Semantic Release will automatically determine the latest release if no
--tag
option is provided.
Required: false
Outputs¶
There are no outputs provided by the Python Semantic Release Publish Action at this time.
Note
If you would like outputs to be provided by this action, please open an issue on the python-semantic-release/publish-action repository.
Examples¶
Common Workflow Example¶
The following is a common workflow example that uses both the Python Semantic Release Action
and the Python Semantic Release Publish Action. This workflow will run on every push to the
main
branch and will create a new release upon a successful version determination. If a
version is released, the workflow will then publish the package to PyPI and upload the package
to the GitHub Release Assets as well.
name: Continuous Delivery
on:
push:
branches:
- main
jobs:
release:
runs-on: ubuntu-latest
concurrency: release
permissions:
id-token: write
contents: write
steps:
# Note: we need to checkout the repository at the workflow sha in case during the workflow
# the branch was updated. To keep PSR working with the configured release branches,
# we force a checkout of the desired release branch but at the workflow sha HEAD.
- name: Setup | Checkout Repository at workflow sha
uses: actions/checkout@v4
with:
fetch-depth: 0
ref: ${{ github.sha }}
- name: Setup | Force correct release branch on workflow sha
run: |
git checkout -B ${{ github.ref_name }} ${{ github.sha }}
- name: Action | Semantic Version Release
id: release
# Adjust tag with desired version if applicable.
uses: python-semantic-release/python-semantic-release@v9.12.0
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
git_committer_name: "github-actions"
git_committer_email: "actions@users.noreply.github.com"
- name: Publish | Upload package to PyPI
uses: pypa/gh-action-pypi-publish@v1
if: steps.release.outputs.released == 'true'
- name: Publish | Upload to GitHub Release Assets
uses: python-semantic-release/publish-action@v9.8.9
if: steps.release.outputs.released == 'true'
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
tag: ${{ steps.release.outputs.tag }}
Important
The concurrency directive is used on the job to prevent race conditions of more than
one release job in the case if there are multiple pushes to main
in a short period
of time.
Warning
You must set fetch-depth
to 0 when using actions/checkout@v4
, since
Python Semantic Release needs access to the full history to build a changelog
and at least the latest tags to determine the next version.
Warning
The GITHUB_TOKEN
secret is automatically configured by GitHub, with the
same permissions role as the user who triggered the workflow run. This causes
a problem if your default branch is protected to specific users.
You can work around this by storing an administrator’s Personal Access Token
as a separate secret and using that instead of GITHUB_TOKEN
. In this
case, you will also need to pass the new token to actions/checkout
(as
the token
input) in order to gain push access.
Version Overrides Example¶
In the case where you want to provide multiple command line options to the
version command, you provide them through the with
directive in the workflow file. In this example, we want to force a patch
version bump, not produce a changelog, and provide specialized build
metadata. As a regular CLI command, this would look like:
semantic-release version --patch --no-changelog --build-metadata abc123
The equivalent GitHub Action configuration would be:
# snippet
- name: Action | Semantic Version Release
# Adjust tag with desired version if applicable.
uses: python-semantic-release/python-semantic-release@v9.12.0
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
force: patch
changelog: false
build_metadata: abc123
Actions with Monorepos¶
While python-semantic-release
does NOT have full monorepo support, if you
have multiple projects stored within a single repository (or your project is
not at the root of the repository), you can pass the
directory input to the action to change
directory before semantic-release execution.
For multiple packages, you would need to run the action multiple times, to release each project. The following example demonstrates how to release two projects in a monorepo.
The directory
input directive is also available for the Python Semantic Release
Publish Action.
- name: Release Project 1
uses: python-semantic-release/python-semantic-release@v9.12.0
with:
directory: ./project1
github_token: ${{ secrets.GITHUB_TOKEN }}
- name: Release Project 2
uses: python-semantic-release/python-semantic-release@v9.12.0
with:
directory: ./project2
github_token: ${{ secrets.GITHUB_TOKEN }}