clarify best practice for python matrix strategy github workflow

docs/guides/integration/github.md

@@ -67,37 +67,6 @@ jobs:
 
 This will respect the Python version pinned in the project.
 
-Or, when using a matrix, as in:
-
-```yaml title="example.yml"
-strategy:
-  matrix:
-    python-version:
-      - "3.10"
-      - "3.11"
-      - "3.12"
-```
-
-Provide the version to the `python install` invocation:
-
-```yaml title="example.yml" hl_lines="14 15"
-name: Example
-
-jobs:
-  uv-example:
-    name: python
-    runs-on: ubuntu-latest
-
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Install uv
-        uses: astral-sh/setup-uv@v4
-
-      - name: Set up Python ${{ matrix.python-version }}
-        run: uv python install ${{ matrix.python-version }}
-```
-
 Alternatively, the official GitHub `setup-python` action can be used. This can be faster, because
 GitHub caches the Python versions alongside the runner.
 
@@ -148,6 +117,52 @@ jobs:
           python-version-file: "pyproject.toml"
 ```
 
+## Multiple Python versions
+
+When using a matrix test test multiple Python versions, set the Python version using
+`astral-sh/setup-uv`, which will override the Python version specification in the `pyproject.toml`
+or `.python-version` files:
+
+```yaml title="example.yml" hl_lines="17 18"
+jobs:
+  build:
+    name: continuous-integration
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version:
+          - "3.10"
+          - "3.11"
+          - "3.12"
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv and set the python version
+        uses: astral-sh/setup-uv@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+```
+
+If not using the `setup-uv` action, you can set the `UV_PYTHON` environment variable:
+
+```yaml title="example.yml" hl_lines="12"
+jobs:
+  build:
+    name: continuous-integration
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version:
+          - "3.10"
+          - "3.11"
+          - "3.12"
+    env:
+      UV_PYTHON: ${{ matrix.python-version }}
+    steps:
+      - uses: actions/checkout@v4
+```
+
 ## Syncing and running
 
 Once uv and Python are installed, the project can be installed with `uv sync` and commands can be