Publish package
===============

Finally, you can deploy the package on the :term:`Python Package Index`
(:term:`PyPI`) or another index, for example :doc:`gitlab` or :term:`devpi`.

For the :term:`Python Package Index`, you must register with *Test PyPI* . Test
PyPI is a separate instance that is intended for testing and experimenting. To
set up an account there, go to https://test.pypi.org/account/register/. Further
information can be found at `Using
TestPyPI <https://packaging.python.org/en/latest/guides/using-testpypi/>`_.

Now you can create the :file:`~/.config/pip/pip.conf` file:

.. code-block:: ini

    [distutils]
    index-servers=
        test

    [test]
    repository = https://test.pypi.org/legacy/
    username = veit

.. seealso::
    If you’d like to automate PyPI registration, read `Careful With That PyPI
    <https://glyph.twistedmatrix.com/2017/10/careful-with-that-pypi.html>`_.

After you are registered, you can upload your :term:`Distribution Package` with
``uv publish``.

You can either use ``uv publish`` with the option ``--username __token__`` or
set the environment variable ``UV_PUBLISH_USERNAME=__token__`` to upload all
archives under :file:`/dist` to the :term:`Python Package Index`:

.. code-block:: console

    $ uv publish --publish-url https://test.pypi.org/legacy/ --username __token__ dist/*

``--publish-url``
    The URL of the upload endpoint (not the index URL).

``--username``
    The user name for the upload.

.. note::
   If you get an error message similar to

   .. code-block:: console

      The user 'veit' isn't allowed to upload to project 'example'

   you have to choose a unique name for your package:

   #. change the ``name`` argument in the :file:`setup.py` file
   #. remove the ``dist`` directory
   #. regenerate the archives

Check
-----

Installation
~~~~~~~~~~~~

You can use ``uv`` to install your package from *Test PyPI* and check if it
works:

.. code-block:: console

    $ $ uv add -i https://test.pypi.org/simple/ mypack

.. note::
   If you have used a different package name, replace it with your package name
   in the command above.

``uv add`` should install the package from *Test PyPI* and the output should
look something like this:

.. code-block:: console

   Resolved 8 packages in 5ms
   Installed 7 packages in 36ms
    + mypack==0.1.0

You can test whether your package has been installed correctly by calling
:func:`main`:

.. code-block:: console

   $ uv run mypack
   Hello from mypack!

.. note::

   The packages on *Test-PyPI* are only stored temporarily. If you want to
   upload a package to the real :term:`Python Package Index` (:term:`PyPI`),
   you can do so by creating an account on :term:`pypi.org`.

README
~~~~~~

Also check whether the ``README.rst`` is displayed correctly on the test PyPI
page.

PyPI
----

Now register on the :term:`Python Package Index` (:term:`PyPI`) and make sure
that `two-factor authentication
<https://blog.python.org/2019/05/use-two-factor-auth-to-improve-your.html>`_
is activated by adding the following to the :file:`~/.pypirc` file:

.. code-block:: ini

   [distutils]
   index-servers=
       pypi
       test

   [test]
   repository = https://test.pypi.org/legacy/
   username = veit

   [pypi]
   username = __token__

With this configuration, the name/password combination is no longer used for
uploading but an upload token.

.. seealso::
   * `PyPI now supports uploading via API token
     <https://pyfound.blogspot.com/2019/07/pypi-now-supports-uploading-via-api.html>`_
   * `What is two factor authentication and how does it work on PyPI?
     <https://pypi.org/help/#twofa>`_

Finally, you can publish your package on PyPI:

.. code-block:: console

   $ uv publish dist/*

.. note::
   You cannot simply replace releases as you cannot re-upload packages with the
   same version number.

.. note::
   Do not remove old versions from the Python Package Index.This only causes
   work for those who want to keep using that version and then have to switch
   to old versions on GitHub. PyPI has a `yank
   <https://pypi.org/help/#yanked>`_ function that you can use instead. This
   will ignore a particular version if it is not explicitly specified with
   ``==`` or ``===``.

.. seealso::
   * `PyPI Release Checklist
     <https://cookiecutter-namespace-template.readthedocs.io/en/latest/pypi-release-checklist.html>`_

.. _pypi_github_action:

GitHub Action
-------------

You can also create a `GitHub Action <https://github.com/features/actions>`_,
which creates a package and uploads it to PyPI at every time a release is
created. Such a :file:`.github/workflows/pypi.yml` file could look like this:

.. code-block:: yaml
   :caption: .github/workflows/pypi.yml
   :linenos:
   :emphasize-lines: 3-5, 12, 31, 36, 38-

   name: Publish Python Package

    on:
      release:
        types: [created]

   jobs:
     test:
       …
     package-and-deploy:
       runs-on: ubuntu-latest
       needs: [test]
       steps:
       - name: Checkout
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           fetch-depth: 0
       - name: Set up Python
         uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
         with:
           python-version-file: .python-version
           cache-dependency-path: '**/pyproject.toml'
       - name: Setup cached uv
         uses: hynek/setup-cached-uv@4300ec2180bc77d705e626a34e381b81a4772c51 # v2.5.0
       - name: Create venv
         run: |
           uv venv
           echo "$PWD/.venv/bin" >> $GITHUB_PATH
       - name: Build
         run: |
           uv build
       - name: Retrieve and publish
         steps:
         - name: Retrieve release distributions
           uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
         - name: Publish package distributions to PyPI
           uses: pypa/gh-action-pypi-publish@ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e # v1.13.0
           with:
             username: __token__
             password: ${{ secrets.PYPI_TOKEN }}

Lines 3–5
    This ensures that the workflow is executed every time a new GitHub
    release is created for the repository.
Line 12
    The job waits for the ``test`` job to pass before it is executed.
Line 31
    Here :samp:`{mypack}` should be replaced by your package name.
Line 36
    The GitHub action `actions/download-artifact
    <https://github.com/actions/download-artifact>`_ provides the built
    distribution packages.
Lines 38–41
    The GitHub action `pypa/gh-action-pypi-publish
    <https://github.com/pypa/gh-action-pypi-publish>`_ publishes the packages
    with the upload token on :term:`PyPI`.

.. seealso::

   * `GitHub Actions <https://docs.github.com/en/actions>`_
   * :doc:`cibuildwheel`

.. _secure-release-workflow:

Securing the release workflow
-----------------------------

Continuous deployment systems used to publish Python packages are a popular
target for attacks. You can avoid many of these risks by following a few
security recommendations:

Avoid insecure triggers
    Workflows that can be triggered by an attacker, particularly those that rely
    on inputs controlled by the attacker (such as :ref:`pull request
    <merge-pull-requests>` or :doc:`branch
    <Python4DataScience:productive/git/branch>` titles), have been used in the
    past to inject commands. In particular, the `pull_request_target
    <https://docs.github.com/en/actions/reference/workflows-and-actions/events-that-trigger-workflows#pull_request_target>`_
    trigger in :ref:`github-actions` should be avoided.

    .. seealso::
       * `Keeping your GitHub Actions and workflows secure Part 2: Untrusted
         input
         <https://securitylab.github.com/resources/github-actions-untrusted-input/>`_
       * `Mitigating Attack Vectors in GitHub Workflows: Workflow triggers
         <https://openssf.org/blog/2024/08/12/mitigating-attack-vectors-in-github-workflows/>`_
       * `Misuse of pull_request_target trigger
         <https://securitylab.github.com/resources/github-actions-new-patterns-and-mitigations/#misuse-of-pull_request_target-trigger>`_

Sanitise parameters and inputs
    Any workflow parameter or input that can be expanded into an executable
    command has the potential to be exploited in attacks. Sanitise values by
    passing them to commands as environment variables to prevent
    `template injection <https://docs.zizmor.sh/audits/#template-injection>`_
    attacks.
Avoid mutable references
    Fix your dependencies in workflows.

    * Prefer Git commit `SHA
      <https://en.wikipedia.org/wiki/Secure_Hash_Algorithms>`_ values over
      :doc:`Git tags <Python4DataScience:productive/git/tag>`, as tags are
      mutable.

      .. tip::
         * To update GitHub Actions and `dependency cooldowns,
           <https://blog.yossarian.net/2025/11/21/We-should-all-be-using-dependency-cooldowns>`_
           you can use `pinact <https://github.com/suzuki-shunsuke/pinact>`_,
           for example:

           .. code-block:: console

              $ pinact run -u --min-age 7

    * Use a :ref:`uv_lock` file for PyPI dependencies used in workflows.

Use verifiable deployments
    With :ref:`trusted_publishers`, you can use verifiable GitHub environments
    to build your Python packages. If you use GitHub Actions for continuous
    delivery, you should use :ref:`zizmorcore` to detect and fix insecure
    workflows.

.. _trusted_publishers:

Trusted Publishers
~~~~~~~~~~~~~~~~~~

`Trusted Publishers <https://docs.pypi.org/trusted-publishers/>`_ is a procedure
for publishing packages on the :term:`PyPI`. It is based on OpenID Connect and
requires neither a password nor a token. Only the following steps are required:

#. Add a *Trusted Publisher* on PyPI

   Depending on whether you want to publish a new package or update an existing
   one, the process is slightly different:

   * to update an existing package, see `Adding a trusted publisher to an
     existing PyPI project
     <https://docs.pypi.org/trusted-publishers/adding-a-publisher/>`_
   * to publish a new package, there is a special procedure called *Pending
     Publisher*; see also `Creating a PyPI project with a trusted publisher
     <https://docs.pypi.org/trusted-publishers/creating-a-project-through-oidc/>`_

     You can also use it to reserve a package name before you publish the first
     version. This allows you to ensure that you can publish the package under
     the desired name.

     To do this, you need to create a new *Pending Publisher* in
     `pypi.org/manage/account/publishing/
     <https://pypi.org/manage/account/publishing/>`_ with

     * Name of the PyPI project
     * GitHub repository owner
     * Name of the workflow, for example :file:`publish.yml`
     * Name of the environment (optional), for example ``release``

#. Create an environment for the GitHub actions

   If we have specified an environment on :term:`PyPI`, we must now also create
   it. This can be done in :menuselection:`Settings --> Environments` for the
   repository. The name of our environment is ``release``.

#. Configure the workflow

   To do this, we now create the :file:`.github/workflows/publish.yml` file in
   our repository:

   .. code-block:: diff
      :caption: .github/workflows/pypi.yml
      :lineno-start: 10
      :emphasize-lines: 3-5

          package-and-deploy:
            runs-on: ubuntu-latest
        +   environment: release
        +   permissions:
        +     id-token: write
            needs: [test]
            steps:

   Line 12
       The specification of a GitHub environment is optional, but strongly
       recommended.
   Lines 13–14
       The ``write`` authorisation is required for *Trusted Publishing*.

   Zeilen 40–44
       ``username`` and ``password`` are no longer required for the GitHub
       action ``pypa/gh-action-pypi-publish``.

       .. code-block:: yaml
          :lineno-start: 40
          :emphasize-lines: 3-

          - name: Publish package distributions to PyPI
            uses: pypa/gh-action-pypi-publish@ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e # v1.13.0
            with:
              username: __token__
              password: ${{ secrets.PYPI_TOKEN }}

.. _package-attestations:

Since 14 November 2024, :term:`PyPI` also supports :pep:`740` with `Digital
Attestations <https://docs.pypi.org/attestations/>`_. PyPI uses the
`in-toto Attestation Framework <https://github.com/in-toto/attestation>`_ to
generate the Digital Attestations `SLSA Provenance
<https://slsa.dev/spec/v1.0/provenance>`_ and `PyPI Publish Attestation (v1)
<https://docs.pypi.org/attestations/publish/v1/>`_.

The creation and publication takes place by default, provided that
:ref:`Trusted Publishing <trusted_publishers>` and the GitHub action
`pypa/gh-action-pypi-publish <https://github.com/pypa/gh-action-pypi-publish>`_
are used for publishing:

.. code-block:: yaml
   :caption: .github/workflows/pypi.yml

   jobs:
     pypi-publish:
       name: Upload release to PyPI
       runs-on: ubuntu-latest
       environment:
         name: pypi
         url: https://pypi.org/p/{YOUR-PYPI-PROJECT-NAME}
       permissions:
         id-token: write
       steps:
       - name: Publish package distributions to PyPI
         uses: pypa/gh-action-pypi-publish@ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e # v1.13.0

.. note::
   Support for the automatic creation of digital attestations and publishing
   from other Trusted Publisher environments is planned.

.. seealso::
   `PyPI now supports digital attestations
   <https://blog.pypi.org/posts/2024-11-14-pypi-now-supports-digital-attestations/>`_

.. _zizmorcore:

zizmor
~~~~~~

`zizmor <https://docs.zizmor.sh>`_ can detect and resolve many security issues
+in typical GitHub Actions CI/CD configurations, such as
+:ref:`token_exfiltration`. zizmor is designed to integrate with GitHub Actions.
+A typical GitHub Action we’ve created for zizmor looks like this:

.. code-block:: yaml
   :caption: .github/workflows/zizmor.yml

   # https://github.com/woodruffw/zizmor
   name: Zizmor

   on:
     push:
       branches: ["main"]
     pull_request:
       branches: ["**"]

   concurrency:
     group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
     cancel-in-progress: true

   permissions: {}

   jobs:
     zizmor:
       name: Run zizmor
       runs-on: ubuntu-latest
       permissions:
         security-events: write # Required for upload-sarif (used by zizmor-action) to upload SARIF files.
       steps:
         - name: Checkout repository
           uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
           with:
             persist-credentials: false
         - name: Run zizmor
           uses: zizmorcore/zizmor-action@71321a20a9ded102f6e9ce5718a2fcec2c4f70d8 # v0.5.2
           with:
             persona: pedantic

However, you can also use zizmor as a pre-commit check to identify issues before
they are pushed:

.. code-block:: yaml
   :caption: .pre-commit-config.yaml

   - repo: https://github.com/zizmorcore/zizmor-pre-commit
     rev: 067260dc5fe6ea86b7551bfd6f8b3ba4e6c93129 # v1.28.0
     hooks:
       - id: zizmor

zizmor also features a `VS Code integration
<https://marketplace.visualstudio.com/items?itemName=zizmor.zizmor-vscode>`_ and
can be run as an LSP server (``zizmor --lsp``) to provide feedback in any
editor.

.. _add_2fa:

2FA for all development accounts
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

You should use two-factor authentication for all your accounts related to
development – not just for :term:`PyPI`. Remember your version control accounts
(`GitHub <https://github.com/>`_, `GitLab <https://about.gitlab.com/>`_,
`Codeberg <https://codeberg.org/>`_, `Forgejo <https://forgejo.org/>`_) and
email.