Setting up python-semantic-release on GitHub Actions

Python Semantic Release includes a GitHub Action which runs the publish command.


Input Description
github_token See GH_TOKEN. this is usually set to ${{ secrets.GITHUB_TOKEN }}.
pypi_token See PYPI_TOKEN.
pypi_username See PYPI_USERNAME.
pypi_password See PYPI_PASSWORD.
directory A sub-directory to cd into before running. Defaults to the root of the repository.

Other options are taken from your regular configuration file.

Example Workflow

name: Semantic Release

      - master

    runs-on: ubuntu-latest
    concurrency: release

    - uses: actions/checkout@v2
        fetch-depth: 0

    - name: Python Semantic Release
      uses: relekang/python-semantic-release@master
        github_token: ${{ secrets.GITHUB_TOKEN }}
        pypi_token: ${{ secrets.PYPI_TOKEN }}

PYPI_TOKEN should be set as a secret on your repository’s settings page. It is also possible to use username and password authentication in a similar fashion.

concurrency is a beta feature of GitHub Actions which disallows two or more release jobs to run in parallel. This prevents race conditions if there are multiple pushes in a short period of time.


You must set fetch-depth to 0 when using actions/checkout@v2, since Python Semantic Release needs access to the full history to determine whether a release should be made.


The GITHUB_TOKEN secret is automatically configured by GitHub, with the same permissions as the user who triggered the workflow run. This causes a problem if your default branch is protected.

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.

Multiple Projects

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. The step can be called multiple times to release multiple projects.

- name: Release Project 1
  uses: relekang/python-semantic-release@master
    directory: ./project1
    github_token: ${{ secrets.GITHUB_TOKEN }}
    pypi_token: ${{ secrets.PYPI_TOKEN }}

- name: Release Project 2
  uses: relekang/python-semantic-release@master
    directory: ./project2
    github_token: ${{ secrets.GITHUB_TOKEN }}
    pypi_token: ${{ secrets.PYPI_TOKEN }}


The release notes posted to GitHub will not currently distinguish which project they are from (see this issue).