.. _github-action:

Python Semantic Release GitHub Action
=====================================

Python Semantic Release is also available as a GitHub action.

In order to use Python Semantic Release to create GitHub Releases against
your repository, you will need to allow the following permissions for the
token generated by GitHub for each job:

* id-token: write
* contents: write

This can be done using the `permissions`_ block in your workflow definition.

.. _permissions: https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idpermissions

Configuring the action can be done in your workflow's YAML definition.
The action provides the following inputs:

Tokens
------
.. _action-github-token:

``github_token``
""""""""""""""""

The GitHub token used to push release notes and new commits/tags.

required: false

Custom Users
------------

.. _action-git-committer-name:

``git_committer_name``
""""""""""""""""""""""

The name of the account used to commit. If customized, it must be associated with the provided token.

default: ``github-actions``

required: false

.. _action-git-committer-email:

``git_committer_email``
"""""""""""""""""""""""

The email of the account used to commit. If customized, it must be associated with the provided token.

default: ``actions@github.com>``

required: false

.. _action-ssh-public-signing-key:

``ssh_public_signing_key``
""""""""""""""""""""""""""

The public key used to verify a commit. If customized, it must be associated with the same account as the provided token.

required: false

.. _action-ssh-private-signing-key:

``ssh_private_signing_key``
"""""""""""""""""""""""""""

The private key used to verify a commit. If customized, it must be associated with the same account as the provided token.

required: false

Additional Options
------------------

.. _action-directory:

``directory``
"""""""""""""

Sub-directory to cd into before running semantic-release

required: false

.. _action-root-options:

``root_options``
""""""""""""""""""""""

Additional options for the main ``semantic-release`` command. Example: ``-vv --noop``

required: false

default: ``-v``

Command Line Options
--------------------

Other inputs which supply additional command-line options to the
:ref:`version <cmd-version>` command can be optionally supplied, and have the same
defaults as their corresponding command line option.

In general, the input for an action corresponding to a command line option has the same
name, with dashes (``-``) replaced by underscores.

The command line arguments ``--prerelease``, ``--patch``, ``--minor`` and ``--major``
are mutually exclusive, and are supplied via the ``force`` input.

Flags, which require either ``--<option>`` or ``--no-<option>`` to be passed on the
command-line, should be specified using the option name (with dashes replaced by
underscores), and set to the value ``"true"`` to supply ``--<option>`` on the
command-line, and ``"false"`` to specify ``--no-<option>``.
Any other values are not accepted.

The flag ``--as-prerelease`` is uniquely provided as just the ``prerelease`` flag value.
This is for compatibility reasons.

For command line options requiring a value, set the input to the required value.

For example, to specify ``--patch --no-push --build-metadata abc123``, you should
provide the following inputs:

.. code:: yaml

   ---

   # ... the rest of the workflow
   - name: Python Semantic Release
     # Adjust tag with desired version if applicable. Version shorthand
     # is NOT available, e.g. vX or vX.X will not work.
     uses: python-semantic-release/python-semantic-release@v9.8.6
     with:
       # ... other options
       force: "patch"
       push: "false"
       build_metadata: "abc123"
