From d283f03b1347304c9d45cec2fed7bc8266fab51e Mon Sep 17 00:00:00 2001
From: Julian Krauth <j.krauth@cosine.nl>
Date: Fri, 24 Oct 2025 09:24:46 +0200
Subject: [PATCH] Add GitLab release job example

Add example of a GitLab release job to the integration docs:
- Publish to GitLab PyPI registry
- Create a release item
- Link wheel files in PyPI registry to the release using assets-links
---
 docs/guides/integration/gitlab.md | 35 +++++++++++++++++++++++++++++++
 1 file changed, 35 insertions(+)

diff --git a/docs/guides/integration/gitlab.md b/docs/guides/integration/gitlab.md
index 0a4073394..53ea6a5d0 100644
--- a/docs/guides/integration/gitlab.md
+++ b/docs/guides/integration/gitlab.md
@@ -84,3 +84,38 @@ To opt-out again, the `--no-system` flag can be used in any uv invocation.
 
 When persisting the cache, you may want to use `requirements.txt` or `pyproject.toml` as
 your cache key files instead of `uv.lock`.
+
+## Publishing to the GitLab PyPI index
+
+`uv publish` can be used to publish to the GitLab PyPI registry, but it will not update your release with corresponding assets links to the uploaded wheel files. It also does not provide assets links as they would be required by `glab release create --assets-links` to connect the wheel files with their corresponding release item.
+
+The following example of a release job, triggered by a pushed tag, will publish all wheel files in the GitLab PyPI registry of the project and create assets links for the corresponding release item.
+
+```yaml title="gitlab-ci.yml"
+release-job:
+  stage: release
+  rules:
+    - if: $CI_COMMIT_TAG
+  variables:
+    GLAB_CHECK_UPDATE: 'no'
+    UV_PUBLISH_URL: "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/pypi"
+    UV_PUBLISH_USERNAME: "gitlab-ci-token"
+    UV_PUBLISH_PASSWORD: "${CI_JOB_TOKEN}"
+  script:
+    - uv build --wheel --all-packages
+  release:
+    tag_name: '$CI_COMMIT_TAG'
+    description: '$CI_PROJECT_NAME release $CI_COMMIT_TAG'
+  after_script:
+    - |
+      for package in dist/*.whl; do
+          uv publish "$package" && \
+          GITLAB_HOST=$CI_SERVER_URL glab release create "$CI_COMMIT_TAG" \
+            --repo "$CI_PROJECT_PATH" \
+            --assets-links='[{"name": "'$(basename "${package%-*-*-*}")'",
+                             "url": "'"$UV_PUBLISH_URL/files/$(sha256sum "$package" | cut --delimiter=' ' --fields=1)/$(basename "$package")"'",
+                             "link_type": "package"}]'
+      done
+```
+
+The items in the PyPI registry of the GitLab project will also be available via the PyPI registry of the corresponding GitLab group.