📝 Update GitLab package registry

Author: veit

CHANGELOG.rst

@@ -30,6 +30,7 @@ Added
 Changed
 ~~~~~~~
 
+* 📝 Update GitLab package registry
 * 📝 Expand the pytest plugins section
 * 📝 Rearrange functions section
 * 📝 Update installation of freethreaded Python

docs/libs/glossary.rst

@@ -383,7 +383,8 @@ Glossary
        * :doc:`Developing applications <../packs/apps>`
        * Testing libraries with different :ref:`Python versions
          <various-python-versions>` and :ref:`tox_uv`
-       * :doc:`Publishing packages <../packs/publish>`
+       * Publishing packages on :doc:`PyPI <../packs/publish>` and :doc:`GitLab
+         <../packs/gitlab>`
        * :doc:`Python4DataScience:productive/envs/uv/cicd`
        * :doc:`Python Docker Containers
          <Python4DataScience:productive/envs/uv/docker>`

docs/packs/gitlab.rst

@@ -2,7 +2,18 @@ GitLab Package Registry
 =======================
 
 You can also publish your distribution packages in the package registry of your
-GitLab project and use them with both :term:`Pip` and :term:`twine`.
+GitLab project. However, the following conditions must be met:
+
+* You must `authenticate
+  <https://docs.gitlab.com/ee/user/packages/pypi_repository/?tab=With+a+deploy+token#authenticate-with-the-gitlab-package-registry>`_
+  yourself when registering the package.
+* Your `version information
+  <https://docs.gitlab.com/ee/user/packages/pypi_repository/?tab=With+a+deploy+token#use-valid-version-strings>`_
+  must be valid.
+* The package must be smaller than 5 GB and the description must not be longer than 4000 characters.
+* The package has not yet been published in the package registry. Attempting to publish the same version of a package will return ``400 Bad Request``.
+
+You can then use the package with both :term:`pip` and :term:`uv`.
 
 .. seealso::
    `PyPI packages in the Package Registry
@@ -14,6 +25,53 @@ Authentication
 To authenticate to the GitLab Package Registry, you can use one of the following
 methods:
 
+* a `personal access token
+  <https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html>`_ with
+  the scope ``api``.
+* a `deploy token
+  <https://docs.gitlab.com/ee/user/project/deploy_tokens/index.html>`_ with the
+  scopes ``read_package_registry``, ``write_package_registry`` or both.
+* a `CI job token <https://docs.gitlab.com/ee/ci/jobs/ci_job_token.html>`_.
+
+.. tab:: personal access token
+
+   .. code-block:: yaml
+      :caption: .gitlab-ci.yml
+      :emphasize-lines: 5-6
+
+      variables:
+        UV_VERSION: 0.5
+        PYTHON_VERSION: 3.12
+        BASE_LAYER: bookworm-slim
+        UV_PUBLISH_USERNAME: <personal_access_token_name>
+        UV_PUBLISH_PASSWORD: <personal_access_token>
+
+.. tab:: deploy token
+
+   .. code-block:: yaml
+      :caption: .gitlab-ci.yml
+      :emphasize-lines: 5-6
+
+      variables:
+        UV_VERSION: 0.5
+        PYTHON_VERSION: 3.12
+        BASE_LAYER: bookworm-slim
+        UV_PUBLISH_USERNAME: <deploy_token_username>
+        UV_PUBLISH_PASSWORD: <deploy_token>
+
+.. tab:: job token
+
+   .. code-block:: yaml
+      :caption: .gitlab-ci.yml
+      :emphasize-lines: 5-6
+
+      variables:
+        UV_VERSION: 0.5
+        PYTHON_VERSION: 3.12
+        BASE_LAYER: bookworm-slim
+        UV_PUBLISH_USERNAME: <gitlab-ci-token>
+        UV_PUBLISH_PASSWORD: $CI_JOB_TOKEN
+
 * A :ref:`personal access token <personal-access-tokens>` with the scope
   ``api``.
 * A :ref:`deploy token <deploy-tokens>` with the scopes
@@ -85,16 +143,30 @@ Use the :samp:`{GROUP_URL}` instead of the :samp:`{PROJECT_ID}`.
 Publishing the distribution package
 -----------------------------------
 
-You can publish your package with the help of :term:`twine`:
+Now you can publish your package on GitLab with :
 
-.. code-block:: console
-
-    $ uv run twine upload -r gitlab dist/*
+.. code-block:: yaml
+   :caption: .gitlab-ci.yml
+
+   …
+   stages:
+     - publish
+   uv:
+     stage: publish
+     image: ghcr.io/astral-sh/uv:$UV_VERSION-python$PYTHON_VERSION-$BASE_LAYER
+     script:
+       - uv build
+       - uv publish --publish-url ${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/pypi dist/*
+
+.. tip::
+   If necessary, you can use ``RUST_LOG=uv=trace`` to obtain further information
+   on the authentication attempts, for example with ``RUST_LOG=uv=trace uv
+   --verbose publish --publish-url
+   ${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/pypi dist/*``.
 
-.. note::
-   If you try to publish a package that already exists with the same name and
-   version, you will get the error ``400 Bad Request``; you will have to delete
-   the existing package first.
+.. seealso::
+   In :ref:`uv-gitlab` you will find further instructions on how to configure
+   the :file:`.gitlab-ci.yml` file.
 
 Installing the package
 ----------------------
@@ -103,13 +175,13 @@ You can install the latest version of your package for example with
 
 .. code-block:: console
 
-   uv add -i https://{NAME}:{PERSONAL_ACCESS_TOKEN}@ce.cusy.io/api/v4/projects/{PROJECT_ID}/packages/pypi/simple --no-deps {PACKAGE_NAME}
+   $ uv add -i https://{NAME}:{PERSONAL_ACCESS_TOKEN}@ce.cusy.io/api/v4/projects/{PROJECT_ID}/packages/pypi/simple --no-deps {PACKAGE_NAME}
 
 … or from the group level with
 
 .. code-block:: console
 
-   uv add -i https://{NAME}:{PERSONAL_ACCESS_TOKEN}@ce.cusy.io/api/v4/groups/{GROUP_ID}/-/packages/pypi/simple --no-deps {PACKAGE_NAME}
+   $ uv add -i https://{NAME}:{PERSONAL_ACCESS_TOKEN}@ce.cusy.io/api/v4/groups/{GROUP_ID}/-/packages/pypi/simple --no-deps {PACKAGE_NAME}
 
 … or in the :file:`pyproject.toml` file with