[FEAT] Add support for dynamic matrix evaluation in Gitea Actions workflows

[ZPascal]

Add support for dynamic matrix evaluation in Gitea Actions workflows

Description

This pull request adds support for dynamic matrix evaluation based on job outputs in Gitea Actions workflows. Workflows can now expand matrix strategies using outputs from dependent jobs, enabling more flexible and dynamic CI/CD pipelines.

The problem

Currently, workflow matrix strategies are evaluated statically at workflow creation time. There is no way to dynamically generate matrix values based on job outputs, which limits the flexibility of CI/CD workflows.

The solution

The implementation adds:

• Matrix re-evaluation: When a job has a matrix strategy that depends on outputs from dependent jobs (using needs.<job>.outputs), the matrix is re-evaluated once those jobs complete
• Performance tracking: Metrics collection for matrix re-evaluation operations to monitor performance and identify issues

Features

Supported workflow patterns

jobs:
  generate:
    outputs:
      matrix: ${{ steps.create-matrix.outputs.result }}
    steps:
      - id: create-matrix
        run: echo "result=[1,2,3]" >> $GITHUB_OUTPUT

  build:
    needs: [generate]
    strategy:
      matrix:
        version: ${{ fromJson(needs.generate.outputs.matrix) }}
    runs-on: ubuntu-latest
    steps:
      - run: echo "Building version ${{ matrix.version }}"

Prometheus metrics

When metrics are enabled, the following metrics are available at /metrics:

• gitea_matrix_total_reevaluations - Total re-evaluation attempts
• gitea_matrix_successful_reevaluations - Successful expansions
• gitea_matrix_failed_reevaluations - Failed expansions
• gitea_matrix_deferred_reevaluations - Evaluations waiting for dependencies
• gitea_matrix_jobs_created_total - Total jobs created from matrix expansion
• gitea_matrix_total_reevaluation_time_ms - Cumulative evaluation time
• gitea_matrix_avg_reevaluation_time_ms - Average evaluation time
• gitea_matrix_total_parse_time_ms - Cumulative parse time
• gitea_matrix_avg_parse_time_ms - Average parse time
• gitea_matrix_total_insert_time_ms - Cumulative database insert time
• gitea_matrix_avg_insert_time_ms - Average insert time
• gitea_matrix_success_rate_percent - Evaluation success rate (0-100%)

Backward compatibility

• Fully backward compatible: existing workflows without a dynamic matrix continue to work unchanged
• The new fields are optional and only used when matrix depends on job outputs
• No changes to existing API or workflow syntax

Testing

• Integration test demonstrates full workflow with dynamic matrix expansion
• Tests verify correct job creation and execution order
• Performance metrics are collected and available for monitoring

Checklist

• Database migration added and tested
• Workflow parsing implemented
• Integration tests passing
• Documentation updated (code comments)
• No breaking changes
• Backwards compatible
• The PR contains AI-generated lines of code
• Test the change in a dev environment

Reviewer notes

• Matrix re-evaluation is triggered in the job resolution loop when dependent jobs complete
• The implementation properly handles edge cases such as circular dependencies and missing outputs
• Performance impact is minimal with metrics collection disabled by default
• Metrics can be viewed in Prometheus when enabled with [metrics].ENABLED = true

Depends on:

• https://gitea.com/gitea/act/pulls/149

[silverwind]

Tests are failing. And please stop force-pushing, we want to see the history of changes.

[Copilot]

Pull request overview

This PR adds support for dynamic GitHub Actions-style matrix expansion in Gitea Actions by deferring matrix evaluation until upstream needs.<job>.outputs are available, and exposes related Prometheus metrics for observability.

Changes:

• Persist per-job raw strategy YAML + an is_matrix_evaluated flag so matrix expansion can be deferred until dependencies complete.
• Re-evaluate/expand matrix jobs during the job resolution loop once needs jobs have finished.
• Add Prometheus collector + tests and an integration test demonstrating dynamic matrix expansion.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 15 comments.

Show a summary per file

File	Description
tests/integration/actions_job_test.go	Adds an integration test validating matrix expansion from a producer job’s outputs.
services/actions/run.go	Passes workflow content to insertion and stores raw strategy for deferred matrix evaluation.
services/actions/matrix.go	Implements raw strategy extraction and matrix re-evaluation/DB job creation.
services/actions/job_emitter.go	Hooks matrix re-evaluation into the blocked-job resolver and adds logging + job reload.
services/actions/matrix_metrics.go	Adds in-memory metrics tracking for re-evaluation performance.
services/actions/matrix_metrics_prometheus.go	Exposes the above stats via a Prometheus collector.
services/actions/matrix_metrics_test.go	Adds unit tests and a benchmark for the Prometheus collector.
routers/web/web.go	Registers the matrix metrics collector when metrics are enabled.
models/actions/run_job.go	Adds RawStrategy + IsMatrixEvaluated fields and a helper to insert multiple jobs.
models/migrations/v1_26/v326.go	Adds DB columns for raw strategy storage and matrix evaluation state.
models/migrations/migrations.go	Registers the new migration (v326).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

If no valid expanded jobs are produced (len(newJobs)==0), the code marks job.IsMatrixEvaluated in-memory only. Persist that flag (or mark the job terminal) to avoid re-running expansion every resolver iteration.

Suggested change

	job.IsMatrixEvaluated = true
	job.IsMatrixEvaluated = true
	if _, err := actions_model.UpdateRunJob(ctx, job, nil, "is_matrix_evaluated"); err != nil {
	log.Error("Failed to update job %d is_matrix_evaluated flag after empty matrix expansion: %v", job.ID, err)
	}

[ChristopherHX]

This looks like a design fault, parsing the whole workflow again just to set job.IsMatrixEvaluated = true

[ZPascal]

Tests are failing. And please stop force-pushing, we want to see the history of changes.

Hi @silverwind, as I've mentioned in the PR description, it is necessary to review/merge beforehand this PR.

[ChristopherHX]

Tests are failing. And please stop force-pushing, we want to see the history of changes.

Hi @silverwind, as I've mentioned in the PR description, it is necessary to review/merge beforehand this PR.

mode draft + temporary act dependency override via go.mod replace has been done multiple times for this to be

• able to checkout and build the PR
• be able to check if tests pass generally

[ChristopherHX]

Could you please not force push? This makes reviews harder to follow changes you make

• use git revert <sha> to undo a change
• use git pull --rebase= <remote> <branch> to merge changes

[silverwind]

git pull --rebase=

git merge origin/main should be even better.

Sometimes AI agents like to amend commits and force-push, so it might not be the author doing it, but I recently added instructions to AGENTS.md to not force-push, which may help.

[silverwind]

@ZPascal please also resolve the open copilot review comments above.

[ZPascal]

Could you please not force push? This makes reviews harder to follow changes you make

• use git revert <sha> to undo a change
• use git pull --rebase= <remote> <branch> to merge changes

I've used the rebase button of the GH UI.

[ZPascal]

git pull --rebase=

git merge origin/main should be even better.

Sometimes AI agents like to amend commits and force-push, so it might not be the author doing it, but I recently added instructions to AGENTS.md to not force-push, which may help.

I don't like merge commits in a feature branch, and thank you for the hint, but I have not handled the rebase via an AI agent.

[silverwind]

Ok, just avoid rewriting git history after reviews have been given because reviewers need to see how their points were adressed.

[ChristopherHX]

(this is my stale review that nobody has seen)

[ChristopherHX]

Ok, this is how you use the jobparser, this looks like a hack...

https://gitea.com/gitea/act/pulls/149#issuecomment-1079741

• The additional parsing is not something I really like...

[ZPascal]

Idea to handle the case: The evaluation of the dynamic matrix can be performed before execution starts. @ChristopherHX, what do you think about this idea? Any other ideas?

[ChristopherHX]

This looks like a design fault, parsing the whole workflow again just to set job.IsMatrixEvaluated = true

[ChristopherHX]

This answers my question, where you get the RawStrategy...

But this design looks like we parse the workflow also for this again and again.

[ZPascal]

The other option would be to analyze it once and use the raw strategy to evaluate whether a job output should be used for the subsequent matrix jobs.

[silverwind]

BTW I just noticed the title and PR contains references to "GitHub Actions" but this is for "Gitea Actions". This is a common issue with AI which likes to confuse these names. Correct that and make you actually proof-read the content.

[ZPascal]

BTW I just noticed the title and PR contains references to "GitHub Actions" but this is for "Gitea Actions". This is a common issue with AI which likes to confuse these names. Correct that and make you actually proof-read the content.

I've adapted the title and the description.

[TheFox0x7]

I have two questions for this as I also touched this topic before:

1. What's the point of those metrics?
2. Why are we inserting the job that can't be ran and won't ever be ran into the list of jobs to run and (per comment) changing it's status to skipped? For one it's just not true - it's not skipped, it can't be skipped as it's not runnable in the first place. Secondly now you have a bag of real jobs which you either ran or will run, and fake ones which do nothing.

[silverwind]

Please run make tidy to fix the license file conflict coming from b9d323c.

Also, check the test and failures.

[Hansehart]

We ran into this exact issue trying to use dynamic matrices in Gitea Actions. After tracing through the source code we confirmed the root cause: the act_runner executes one job at a time via PlanJob(jobID) and only receives the static YAML payload, so needs.<job>.outputs is never resolved when strategy.matrix is evaluated.

Is there anything blocking this from moving forward? Happy to help if that would be useful.

[ZPascal]

We ran into this exact issue trying to use dynamic matrices in Gitea Actions. After tracing through the source code we confirmed the root cause: the act_runner executes one job at a time via PlanJob(jobID) and only receives the static YAML payload, so needs..outputs is never resolved when strategy.matrix is evaluated. Is there anything blocking this from moving forward? Happy to help if that would be useful.

I don't think so. I'll continue today to adapt the code.