Feature/654 add and use general matrix

.gitattributes

@@ -12,7 +12,7 @@ doc/changes/changelog.md  linguist-generated=true
 .github/workflows/dependency-update.yml     linguist-generated=true
 .github/workflows/fast-tests.yml            linguist-generated=true
 .github/workflows/gh-pages.yml              linguist-generated=true
-.github/workflows/matrix-*.yml              linguist-generated=true
+.github/workflows/matrix.yml                linguist-generated=true
 .github/workflows/merge-gate.yml            linguist-generated=true
 .github/workflows/periodic-validation.yml   linguist-generated=true
 .github/workflows/pr-merge.yml              linguist-generated=true

.github/workflows/merge-gate-extension.yml

@@ -4,8 +4,20 @@ on:
   workflow_call:
 
 jobs:
+  approve-run-slow-tests:
+    name: Approve Running Slow Tests?
+    runs-on: "ubuntu-24.04"
+    permissions:
+      contents: read
+    environment: manual-approval
+    steps:
+      - name: Tests
+        run: echo "Slow tests approved"
+
   test-python-environment:
     name: Test python-environment Action
     uses: ./.github/workflows/test-python-environment.yml
+    needs:
+      - approve-run-slow-tests
     permissions:
       contents: read

.github/workflows/slow-checks.yml

@@ -6,12 +6,14 @@ on:
 jobs:
   build-matrix:
     name: Build Matrix
-    uses: ./.github/workflows/matrix-python.yml
+    uses: ./.github/workflows/matrix.yml
+    with:
+      matrix_keys_json: '["python_versions"]'
     permissions:
       contents: read
 
   run-integration-tests:
-    name: Run Integration Tests (Python-${{ matrix.python-version }})
+    name: Run Integration Tests (Python-${{ matrix.python_versions }})
     needs:
       - build-matrix
     runs-on: "ubuntu-24.04"
@@ -33,7 +35,7 @@ jobs:
         id: set-up-python-and-poetry-environment
         uses: exasol/python-toolbox/.github/actions/python-environment@v8
         with:
-          python-version: ${{ matrix.python-version }}
+          python-version: ${{ matrix.python_versions }}
           poetry-version: "2.3.0"
 
       - name: Run Integration Tests
@@ -44,7 +46,7 @@ jobs:
         id: upload-artifacts
         uses: actions/upload-artifact@v7
         with:
-          name: coverage-python${{ matrix.python-version }}-slow
+          name: coverage-python${{ matrix.python_versions }}-slow
           path: .coverage
           include-hidden-files: true
           overwrite: false

.github/workflows/test-python-environment.yml

@@ -27,8 +27,8 @@ jobs:
 
           # Otherwise, check if any relevant files were changed in this PR
           else
-            if git diff --quiet "origin/$BASE_REF...HEAD" -- .github/actions/python-environment; then
-              echo "No changes in .github/actions/python-environment, skipping."
+            if git diff --quiet "origin/$BASE_REF...HEAD" -- .github/actions/python-environment .github/workflows/test-python-environment.yml; then
+              echo "No changes in .github/actions/python-environment or .github/workflows/test-python-environment.yml, skipping."
               echo "should_run=false" >> $GITHUB_OUTPUT
             else
               echo "Changes detected in directory, running."
@@ -41,7 +41,9 @@ jobs:
     needs:
       - check-changes
     if: needs.check-changes.outputs.should_run == 'true'
-    uses: ./.github/workflows/matrix-all.yml
+    uses: ./.github/workflows/matrix.yml
+    with:
+      matrix_keys_json: '["python_versions"]'
     permissions:
       contents: read
 
@@ -60,8 +62,8 @@ jobs:
           - int-linux-x64-4core-gpu-t4-ubuntu24.04-1
           - int-linux-x64-4core-ubuntu24.04-1
           - int-linux-x64-2core-ubuntu24.04-1
-        python-version: ${{ fromJson(needs.build-matrix.outputs.matrix).python-version }}
-    name: Verify Poetry Setup for ${{ matrix.runner }} (Python-${{ matrix.python-version }})
+        python-versions: ${{ fromJson(needs.build-matrix.outputs.matrix).python_versions }}
+    name: Verify Poetry Setup for ${{ matrix.runner }} (Python-${{ matrix.python-versions }})
     runs-on:
       labels: ${{ matrix.runner }}
     steps:
@@ -75,7 +77,7 @@ jobs:
         id: set-up-python-and-poetry-environment
         uses: ./.github/actions/python-environment
         with:
-          python-version: "${{ matrix.python-version }}"
+          python-version: "${{ matrix.python-versions }}"
           poetry-version: "2.3.0"
 
       - name: Check Poetry Version
@@ -85,7 +87,7 @@ jobs:
       - name: Validate Python Version
         id: validate-python-version
         env:
-          PYTHON_VERSION: ${{ matrix.python-version }}
+          PYTHON_VERSION: ${{ matrix.python-versions }}
         run: |
           poetry run which python
           poetry run python --version

doc/changes/unreleased.md

@@ -2,8 +2,32 @@
 
 ## Summary
 
+This major version introduces `matrix.yml` whose results are generated by the nox session `matrix:generate`.
+
+Projects can extend `BaseConfig` with additional matrix values when they need to expose
+more entries to the workflows.
+
+```python
+class Config(BaseConfig):
+    extra_matrix_value: str = "extra"
+
+    @computed_field  # type: ignore[misc]
+    @property
+    def computed_matrix_value(self) -> str:
+        # This can be requested when generating the matrix. If it is a simple string value,
+        # like is shown here, then the code will automatically wrap it in an array.
+        return f"{self.project_name}-computed"
+```
+
+The corresponding nox sessions (`matrix:all`, `matrix:exasol`, and `matrix:python`) will
+remain available until September 15, 2026, to provide a transition period for existing projects.
+
+At the same time, the workflows `matrix-all.yml`, `matrix-exasol.yml`, and `matrix-python.yml` 
+are deprecated and are no longer maintained by the exasol-toolbox. You can still use 
+these workflows in your project until you transition fully to using `matrix.yml`.
 
 ## Feature
 
 * #730: Added support to extend GitHub workflow `cd.yml`
-* #864: Modified PTB workflow templates to not persist credentials and to use pinned SHAs
+* #864: Modified PTB workflow templates to not persist credentials and to use pinned SHAs
+* #654: Added and used general matrix `matrix.yml` for PTB-provided workflows

doc/user_guide/features/github_workflows/create_and_update.rst

@@ -8,10 +8,10 @@ update existing workflows.
 
 The workflows are based on Jinja templates with variables populated by the
 PTB. The PTB reads the values from various attributes and properties of your
-project's config, see :ref:`template_variables`.
+project's config, see :ref:`workflow_templates`.
 
 Please note that the PTB only updates the values in the GitHub workflows when
-*updating* the workflows. So, after updating the :ref:`list of Python versions
+updating the workflows in general. So, after updating the :ref:`list of Python versions
 <python_versions>` in file ``noxconfig.py``, you need to :ref:`re-generate
 <update_workflows>` the GitHub workflows.
 
@@ -49,6 +49,11 @@ The PTB has a default for these versions, but you can override it in the
 Some workflows are expected to not depend on a specific Python version and
 will use only the lowest Python version in the list specified above.
 
+If you need more than the built-in matrix inputs, you can extend
+:class:`exasol.toolbox.config.BaseConfig` with extra properties or computed fields
+and consume them from ``matrix.yml`` via ``matrix:generate``. See
+:ref:`workflow_matrix` for an example.
+
 .. _customize_workflows:
 
 Customize Workflows for Your Project

doc/user_guide/features/github_workflows/index.rst

@@ -9,7 +9,7 @@ GitHub Workflow Templates
 
     github_project_configuration
     create_and_update
-    template_variables
+    workflow_variables
     workflow_patcher
 
 The PTB ships with configurable GitHub workflow templates covering the most common
@@ -44,6 +44,12 @@ The PTB has three categories of workflows:
 Maintained by the PTB
 ^^^^^^^^^^^^^^^^^^^^^
 
+.. note::
+  The ``matrix.yml`` workflow replaces the older ``matrix-all.yml``, ``matrix-exasol.yml``,
+  and ``matrix-python.yml`` workflows. The associated nox sessions (``matrix:all``,
+  ``matrix:exasol``, and ``matrix:python``) are deprecated and will be removed
+  2026-09-15.
+
 .. list-table::
    :widths: 25 25 50
    :header-rows: 1
@@ -79,18 +85,10 @@ Maintained by the PTB
    * - ``gh-pages.yml``
      - Workflow call
      - Builds the documentation and deploys it to GitHub Pages.
-   * - ``matrix-all.yml``
-     - Workflow call
-     - Calls Nox session ``matrix:all``, which typically evaluates ``exasol_versions``
-       and ``python_versions`` from the ``PROJECT_CONFIG``.
-   * - ``matrix-exasol.yml``
-     - Workflow call
-     - Calls Nox session ``matrix:exasol`` to get the ``exasol_versions`` from the
-       ``PROJECT_CONFIG``.
-   * - ``matrix-python.yml``
+   * - ``matrix.yml``
      - Workflow call
-     - Calls Nox session ``matrix:python`` to get the ``python_versions`` from the
-       ``PROJECT_CONFIG``.
+     - Calls Nox session ``matrix:generate`` to build a custom matrix from the
+       ``PROJECT_CONFIG``. See :ref:`workflow_matrix`.
    * - ``merge-gate.yml``
      - Workflow call
      - Acts as a final status check (gatekeeper) to ensure all required CI steps have