GitLab Integration documentation (#6857)

<!--
Thank you for contributing to uv! To help us out with reviewing, please
consider the following:

- Does this pull request include a summary of the change? (See below.)
- Does this pull request include a descriptive title?
- Does this pull request include references to any relevant issues?
-->

## Summary
Documentation for GitLab integration, reliant on the new tags introduced
in https://github.com/astral-sh/uv/pull/6053

## Test Plan

<!-- How was it tested? -->

---------

Co-authored-by: David Fritzsche <9479371+davidfritzsche@users.noreply.github.com>
Co-authored-by: Zanie Blue <contact@zanie.dev>

docs/guides/index.md

@@ -13,6 +13,7 @@ Learn how to integrate uv with other software:
 - [Using with Jupyter](./integration/jupyter.md)
 - [Using with pre-commit](./integration/pre-commit.md)
 - [Using in GitHub Actions](./integration/github.md)
+- [Using in GitLab CI/CD](./integration/gitlab.md)
 - [Using with alternative package indexes](./integration/alternative-indexes.md)
 - [Building a FastAPI application](./integration/fastapi.md)
 

docs/guides/integration/gitlab.md

@@ -0,0 +1,72 @@
+# Using uv in GitLab CI/CD
+
+## Using the uv image
+
+Astral provides [Docker images](docker.md#available-images) with uv preinstalled.
+Select a variant that is suitable for your workflow.
+
+```yaml title="gitlab-ci.yml
+variables:
+  UV_VERSION: 0.4
+  PYTHON_VERSION: 3.12
+  BASE_LAYER: bookworm-slim
+
+stages:
+  - analysis
+
+UV:
+  stage: analysis
+  image:
+    name: ghcr.io/astral-sh/uv:$UV_VERSION-python$PYTHON_VERSION-$BASE_LAYER
+  script: >
+    cd $CI_PROJECT_DIR
+    # your `uv` commands
+```
+
+## Caching
+
+Persisting the uv cache between workflow runs can improve performance.
+
+```yaml
+UV Install:
+  variables:
+    UV_CACHE_DIR: /tmp/.uv-cache
+  cache:
+    - key:
+        files:
+          - uv.lock
+      paths:
+        - $UV_CACHE_DIR
+  steps: >
+    # Your uv commands
+    run: uv cache prune --ci
+```
+
+See the [GitLab caching documentation](https://docs.gitlab.com/ee/ci/caching/) for more details on
+configuring caching.
+
+Using `uv cache prune --ci` at the end of the job is recommended to reduce cache size. See the [uv
+cache documentation](../../concepts/cache.md#caching-in-continuous-integration) for more details.
+
+## Using `uv pip`
+
+If using the `uv pip` interface instead of the uv project interface, uv requires a virtual
+environment by default. To allow installing packages into the system environment, use the `--system`
+flag on all uv invocations or set the `UV_SYSTEM_PYTHON` variable.
+
+The `UV_SYSTEM_PYTHON` variable can be defined in at different scopes. You can read more about
+how [variables and their precedence works in GitLab here](https://docs.gitlab.com/ee/ci/variables/)
+
+Opt-in for the entire workflow by defining it at the top level:
+
+```yaml title="gitlab-ci.yml"
+variables:
+  UV_SYSTEM_PYTHON: 1
+
+# [...]
+```
+
+To opt-out again, the `--no-system` flag can be used in any uv invocation.
+
+When persisting the cache, you may want to use `requirement.txt` or `pyproject.toml` as
+your cache key files instead of `uv.lock`.

docs/guides/integration/index.md

@@ -3,6 +3,9 @@
 Learn how to integrate uv with other software:
 
 - [Using in Docker images](./docker.md)
+- [Using with Jupyter](./jupyter.md)
 - [Using with pre-commit](./pre-commit.md)
 - [Using in GitHub Actions](./github.md)
-- [Using an Azure Artifacts index](./alternative-indexes.md#azure-artifacts)
+- [Using in GitLab CI/CD](./gitlab.md)
+- [Using with alternative package indexes](./alternative-indexes.md)
+- [Building a FastAPI application](./fastapi.md)