TEST-INFRA: [ci-pipeline-design] Implement Matrix Build Strategy in CI Workflow #5916

Open
opened 2026-04-09 11:45:53 +00:00 by HAL9000 · 1 comment
Owner

Metadata

  • Branch: test-infra/ci-pipeline-design/matrix-build-strategy
  • Commit Message: refactor(ci): implement matrix build strategy to consolidate CI job definitions and reduce duplication
  • Milestone: (backlog — see note below)
  • Parent Epic: #5407

Description

The current CI workflow in .forgejo/workflows/ci.yml defines multiple separate jobs (lint, typecheck, unit_tests, etc.) that share a significant amount of boilerplate configuration for setup steps like checking out the repository, installing dependencies, and configuring caching. This duplication makes the workflow configuration verbose, harder to maintain, and less flexible.

This proposal suggests refactoring the CI workflow to use a matrix build strategy. A matrix would allow us to define a single job template and run it for each of our required CI checks.

Proposed Solution

  1. Define a Matrix: Create a matrix in the ci.yml file that lists the different CI tasks to be run (e.g., [lint, typecheck, security, unit_tests, integration_tests]).
  2. Create a Templated Job: Define a single job that uses the matrix variable (e.g., ${{ matrix.task }}) to run the corresponding nox session.
  3. Consolidate Setup: All setup steps (checkout, cache, install nox) will be defined only once in the templated job.

Benefits

  • Reduced Duplication: Significantly reduces the lines of code in ci.yml.
  • Improved Maintainability: Easier to add, remove, or modify CI steps.
  • Increased Flexibility: Simple to add new dimensions to the matrix, such as different Python versions ([3.12, 3.13]).

Subtasks

  • Audit .forgejo/workflows/ci.yml and identify all duplicated setup steps across jobs
  • Design the matrix strategy (task list, matrix variable naming)
  • Refactor ci.yml to use a single templated job with strategy.matrix.task
  • Consolidate all shared setup steps (checkout, cache, install nox) into the templated job
  • Verify all existing CI checks (lint, typecheck, tests, etc.) pass within the new matrix structure
  • Confirm the total number of lines in ci.yml is significantly reduced

Definition of Done

  • The ci.yml workflow is refactored to use a build matrix for the primary CI jobs.
  • All existing CI checks (lint, typecheck, tests, etc.) are executed successfully within the new matrix structure.
  • The total number of lines in ci.yml is significantly reduced.
  • All nox stages pass (nox -e lint, nox -e typecheck, nox -e unit_tests, nox -e integration_tests).
  • Coverage >= 97% (nox -e coverage_report).
  • PR is merged and linked issue is closed.

Duplicate Check

  • Searched for open and closed issues containing "matrix": 0 results.
  • Searched for open and closed issues containing "ci refactor": 0 results.
  • Searched for open and closed issues containing "parallel": Found many results, but they appeared to be related to test execution parallelism within nox, not CI job parallelism. This proposal addresses job-level parallelization and configuration.
  • Note: #5760 covers matrix build for multiple Python versions; this issue covers using a matrix to consolidate and template CI job definitions — distinct concerns.

Backlog note: This issue was discovered during autonomous operation
on milestone v3.7.0. It does not block milestone completion and has been
placed in the backlog for human review and future milestone assignment.


Automated by CleverAgents Bot
Supervisor: Test Infrastructure | Agent: new-issue-creator

## Metadata - **Branch**: `test-infra/ci-pipeline-design/matrix-build-strategy` - **Commit Message**: `refactor(ci): implement matrix build strategy to consolidate CI job definitions and reduce duplication` - **Milestone**: *(backlog — see note below)* - **Parent Epic**: #5407 ## Description The current CI workflow in `.forgejo/workflows/ci.yml` defines multiple separate jobs (lint, typecheck, unit_tests, etc.) that share a significant amount of boilerplate configuration for setup steps like checking out the repository, installing dependencies, and configuring caching. This duplication makes the workflow configuration verbose, harder to maintain, and less flexible. This proposal suggests refactoring the CI workflow to use a matrix build strategy. A matrix would allow us to define a single job template and run it for each of our required CI checks. ## Proposed Solution 1. **Define a Matrix**: Create a `matrix` in the `ci.yml` file that lists the different CI tasks to be run (e.g., `[lint, typecheck, security, unit_tests, integration_tests]`). 2. **Create a Templated Job**: Define a single job that uses the matrix variable (e.g., `${{ matrix.task }}`) to run the corresponding `nox` session. 3. **Consolidate Setup**: All setup steps (checkout, cache, install nox) will be defined only once in the templated job. ## Benefits * **Reduced Duplication**: Significantly reduces the lines of code in `ci.yml`. * **Improved Maintainability**: Easier to add, remove, or modify CI steps. * **Increased Flexibility**: Simple to add new dimensions to the matrix, such as different Python versions (`[3.12, 3.13]`). ## Subtasks - [ ] Audit `.forgejo/workflows/ci.yml` and identify all duplicated setup steps across jobs - [ ] Design the matrix strategy (task list, matrix variable naming) - [ ] Refactor `ci.yml` to use a single templated job with `strategy.matrix.task` - [ ] Consolidate all shared setup steps (checkout, cache, install nox) into the templated job - [ ] Verify all existing CI checks (lint, typecheck, tests, etc.) pass within the new matrix structure - [ ] Confirm the total number of lines in `ci.yml` is significantly reduced ## Definition of Done - [ ] The `ci.yml` workflow is refactored to use a build matrix for the primary CI jobs. - [ ] All existing CI checks (lint, typecheck, tests, etc.) are executed successfully within the new matrix structure. - [ ] The total number of lines in `ci.yml` is significantly reduced. - [ ] All nox stages pass (`nox -e lint`, `nox -e typecheck`, `nox -e unit_tests`, `nox -e integration_tests`). - [ ] Coverage >= 97% (`nox -e coverage_report`). - [ ] PR is merged and linked issue is closed. ## Duplicate Check * Searched for open and closed issues containing "matrix": 0 results. * Searched for open and closed issues containing "ci refactor": 0 results. * Searched for open and closed issues containing "parallel": Found many results, but they appeared to be related to test execution parallelism within `nox`, not CI job parallelism. This proposal addresses job-level parallelization and configuration. * Note: #5760 covers matrix build for *multiple Python versions*; this issue covers using a matrix to *consolidate and template CI job definitions* — distinct concerns. > **Backlog note:** This issue was discovered during autonomous operation > on milestone v3.7.0. It does not block milestone completion and has been > placed in the backlog for human review and future milestone assignment. --- **Automated by CleverAgents Bot** Supervisor: Test Infrastructure | Agent: new-issue-creator
HAL9000 added this to the v3.8.0 milestone 2026-04-09 12:21:11 +00:00
Author
Owner

Label compliance fix applied:

  • Added missing labels and/or milestone to bring issue into compliance with CONTRIBUTING.md

Automated by CleverAgents Bot
Supervisor: Backlog Grooming | Agent: backlog-groomer

Label compliance fix applied: - Added missing labels and/or milestone to bring issue into compliance with CONTRIBUTING.md --- **Automated by CleverAgents Bot** Supervisor: Backlog Grooming | Agent: backlog-groomer
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Reference
cleveragents/cleveragents-core#5916
No description provided.