Feature/654 add and use general matrix

.github/workflows/matrix-all.yml → .github/workflows/matrix.yml

@@ -1,16 +1,21 @@
 # Generated and maintained by the exasol-toolbox.
 # Last generated with exasol-toolbox version 8.1.1.
-name: Build Matrix (All Versions)
+name: Build Matrix
 
 on:
   workflow_call:
+    inputs:
+      matrix_keys_json:
+        description: "JSON array of BaseConfig keys to include in the generated matrix output."
+        required: true
+        type: string
     outputs:
       matrix:
-        description: "Generates the all versions build matrix"
-        value: ${{ jobs.set-matrix-all.outputs.matrix }}
+        description: "Generates the requested build matrix"
+        value: ${{ jobs.set-matrix.outputs.matrix }}
 
 jobs:
-  set-matrix-all:
+  set-matrix:
     runs-on: "ubuntu-24.04"
     permissions:
       contents: read
@@ -29,13 +34,15 @@ jobs:
           poetry-version: "2.3.0"
 
       - name: Generate Matrix
-        id: generate-matrix
-        run: poetry run -- nox -s matrix:all
-
-      - name: Set Matrix
         id: set-matrix
+        env:
+          MATRIX_KEYS_JSON: ${{ inputs.matrix_keys_json }}
         run: |
-          echo "matrix=$(poetry run -- nox -s matrix:all)" >> $GITHUB_OUTPUT
+          readarray -t matrix_keys < <(jq -r '.[]' <<< "$MATRIX_KEYS_JSON")
+          matrix_json="$(poetry run -- nox -s matrix:generate -- "${matrix_keys[@]}")"
+          echo "Generated matrix JSON:"
+          jq . <<< "$matrix_json"
+          echo "matrix=$matrix_json" >> "$GITHUB_OUTPUT"
 
     outputs:
       matrix: ${{ steps.set-matrix.outputs.matrix }}

.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` as the new 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 singular 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 can 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,7 +8,7 @@ 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
@@ -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