GitLab Integration documentation

.prettierignore

@@ -4,3 +4,4 @@ PREVIEW-CHANGELOG.md
 docs/reference/cli.md
 docs/reference/settings.md
 ecosystem/home-assistant-core/LICENSE.md
+docs/guides/integration/gitlab.md

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](#caching), 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)

mkdocs.template.yml

@@ -111,6 +111,7 @@ nav:
       - Docker: guides/integration/docker.md
       - Jupyter: guides/integration/jupyter.md
       - GitHub Actions: guides/integration/github.md
+      - GitLab CI/CD: guides/integration/gitlab.md
       - Pre-commit: guides/integration/pre-commit.md
       - FastAPI: guides/integration/fastapi.md
       - Alternative indexes: guides/integration/alternative-indexes.md