From 0ecc6ef632417de8b492134adac1e91d32c5ce9a Mon Sep 17 00:00:00 2001
From: Mathieu Fenniak <mathieu@fenniak.net>
Date: Fri, 5 Dec 2025 17:17:37 +0100
Subject: [PATCH] fix(actions): improve errors when `${{ needs... }}` is used
 in `strategy.matrix` incorrectly (#10298)

Three fixes are presented together in this PR:
- When a `strategy.matrix` entry in an Action job contains `${{ needs.some-job.outputs.some-output }}`, if that output *never* becomes available, different error messages will be presented if `some-job` isn't found or if `some-output` isn't found.  This clarifies an error message that was previously "it could be this, or it could be this".
- In the error case described in the previous point, other jobs in the workflow could continue running or could be left "blocked" forever.  A centralized `FailRunPreExecutionError` function ensures that all incomplete jobs in the run are failed in this case.
- In a rare error case when a job referenced another job in `strategy.matrix` but no other jobs were defined in the workflow, the job would be marked as blocked forever because the `job_emitter` code would never be invoked to detect this case.  A new `consistencyCheckRun` function for a newly created `ActionRun` adds a location to perform a pre-execution check for this case so that the run can be failed.

These fixes are all interconnected around the refactor for the `FailRunPreExecutionError`, causing them to be bundled rather than individual PRs.

## Checklist

The [contributor guide](https://forgejo.org/docs/next/contributor/) contains information that will be helpful to first time contributors. There also are a few [conditions for merging Pull Requests in Forgejo repositories](https://codeberg.org/forgejo/governance/src/branch/main/PullRequestsAgreement.md). You are also welcome to join the [Forgejo development chatroom](https://matrix.to/#/#forgejo-development:matrix.org).

### Tests

- I added test coverage for Go changes...
  - [x] in their respective `*_test.go` for unit tests.
  - [ ] in the `tests/integration` directory if it involves interactions with a live Forgejo server.
- I added test coverage for JavaScript changes...
  - [ ] in `web_src/js/*.test.js` if it can be unit tested.
  - [ ] in `tests/e2e/*.test.e2e.js` if it requires interactions with a live Forgejo server (see also the [developer guide for JavaScript testing](https://codeberg.org/forgejo/forgejo/src/branch/forgejo/tests/e2e/README.md#end-to-end-tests)).

### Documentation

- [ ] I created a pull request [to the documentation](https://codeberg.org/forgejo/docs) to explain to Forgejo users how to use this change.
- [x] I did not document these changes and I do not expect someone else to do it.

### Release notes

- [x] I do not want this change to show in the release notes.
    - These are fixes to an unreleased feature and don't require release notes.
- [ ] I want the title to show in the release notes with a link to this pull request.
- [ ] I want the content of the `release-notes/<pull request number>.md` to be be used for the release notes instead of the title.

Reviewed-on: https://codeberg.org/forgejo/forgejo/pulls/10298
Reviewed-by: Earl Warren <earl-warren@noreply.codeberg.org>
Co-authored-by: Mathieu Fenniak <mathieu@fenniak.net>
Co-committed-by: Mathieu Fenniak <mathieu@fenniak.net>
---
 models/actions/pre_execution_errors.go        |   6 +
 models/actions/pre_execution_errors_test.go   |  16 +++
 models/actions/run_job.go                     |  33 ++++-
 models/actions/run_job_test.go                |   8 +-
 options/locale_next/locale_en-US.json         |   2 +
 .../action_run.yml                            |  54 +++++++++
 .../action_run_job.yml                        | 113 ++++++++++++++++++
 .../action_run.yml                            |  19 +++
 .../action_run_job.yml                        |  41 +++++++
 services/actions/commit_status.go             |   2 +-
 services/actions/commit_status_test.go        |   5 +-
 services/actions/job_emitter.go               |  50 +++++---
 services/actions/job_emitter_test.go          |  10 +-
 services/actions/notifier_helper.go           |  28 ++++-
 services/actions/notifier_helper_test.go      |   1 +
 services/actions/run.go                       |  98 ++++++++++++++-
 services/actions/run_test.go                  |  42 +++++++
 services/actions/schedule_tasks.go            |   4 +
 services/actions/workflows.go                 |   6 +-
 19 files changed, 497 insertions(+), 41 deletions(-)
 create mode 100644 services/actions/TestActions_consistencyCheckRun/action_run.yml
 create mode 100644 services/actions/TestActions_consistencyCheckRun/action_run_job.yml

diff --git a/models/actions/pre_execution_errors.go b/models/actions/pre_execution_errors.go
index 0ba8f8f362..59976cde6e 100644
--- a/models/actions/pre_execution_errors.go
+++ b/models/actions/pre_execution_errors.go
@@ -19,6 +19,8 @@ const (
 	ErrorCodeEventDetectionError PreExecutionError = iota + 1
 	ErrorCodeJobParsingError
 	ErrorCodePersistentIncompleteMatrix
+	ErrorCodeIncompleteMatrixMissingJob
+	ErrorCodeIncompleteMatrixMissingOutput
 )
 
 func TranslatePreExecutionError(lang translation.Locale, run *ActionRun) string {
@@ -36,6 +38,10 @@ func TranslatePreExecutionError(lang translation.Locale, run *ActionRun) string
 		return lang.TrString("actions.workflow.job_parsing_error", run.PreExecutionErrorDetails...)
 	case ErrorCodePersistentIncompleteMatrix:
 		return lang.TrString("actions.workflow.persistent_incomplete_matrix", run.PreExecutionErrorDetails...)
+	case ErrorCodeIncompleteMatrixMissingJob:
+		return lang.TrString("actions.workflow.incomplete_matrix_missing_job", run.PreExecutionErrorDetails...)
+	case ErrorCodeIncompleteMatrixMissingOutput:
+		return lang.TrString("actions.workflow.incomplete_matrix_missing_output", run.PreExecutionErrorDetails...)
 	}
 	return fmt.Sprintf("<unsupported error: code=%v details=%#v", run.PreExecutionErrorCode, run.PreExecutionErrorDetails)
 }
diff --git a/models/actions/pre_execution_errors_test.go b/models/actions/pre_execution_errors_test.go
index 72b95a90fc..51b6badfb4 100644
--- a/models/actions/pre_execution_errors_test.go
+++ b/models/actions/pre_execution_errors_test.go
@@ -54,6 +54,22 @@ func TestTranslatePreExecutionError(t *testing.T) {
 			},
 			expected: "Unable to evaluate `strategy.matrix` of job blocked_job due to a `needs` expression that was invalid. It may reference a job that is not in it's 'needs' list (needs-1, needs-2), or an output that doesn't exist on one of those jobs.",
 		},
+		{
+			name: "ErrorCodeIncompleteMatrixMissingOutput",
+			run: &ActionRun{
+				PreExecutionErrorCode:    ErrorCodeIncompleteMatrixMissingOutput,
+				PreExecutionErrorDetails: []any{"blocked_job", "other_job", "some_output"},
+			},
+			expected: "Unable to evaluate `strategy.matrix` of job blocked_job: job other_job does not have an output some_output.",
+		},
+		{
+			name: "ErrorCodeIncompleteMatrixMissingJob",
+			run: &ActionRun{
+				PreExecutionErrorCode:    ErrorCodeIncompleteMatrixMissingJob,
+				PreExecutionErrorDetails: []any{"blocked_job", "other_job", "needs-1, needs-2"},
+			},
+			expected: "Unable to evaluate `strategy.matrix` of job blocked_job: job other_job is not in the `needs` list of job blocked_job (needs-1, needs-2).",
+		},
 	}
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
diff --git a/models/actions/run_job.go b/models/actions/run_job.go
index 0b5e0f427a..8a926e7577 100644
--- a/models/actions/run_job.go
+++ b/models/actions/run_job.go
@@ -43,6 +43,8 @@ type ActionRunJob struct {
 	Stopped           timeutil.TimeStamp
 	Created           timeutil.TimeStamp `xorm:"created"`
 	Updated           timeutil.TimeStamp `xorm:"updated index"`
+
+	workflowPayloadDecoded *jobparser.SingleWorkflow `xorm:"-"`
 }
 
 func init() {
@@ -256,13 +258,34 @@ func (job *ActionRunJob) StatusDiagnostics(lang translation.Locale) []template.H
 	return diagnostics
 }
 
-// Checks whether the target job is an `(incomplete matrix)` job that will be blocked until the matrix is complete, and
-// then regenerated and deleted.
-func (job *ActionRunJob) IsIncompleteMatrix() (bool, error) {
+func (job *ActionRunJob) decodeWorkflowPayload() (*jobparser.SingleWorkflow, error) {
+	if job.workflowPayloadDecoded != nil {
+		return job.workflowPayloadDecoded, nil
+	}
+
 	var jobWorkflow jobparser.SingleWorkflow
 	err := yaml.Unmarshal(job.WorkflowPayload, &jobWorkflow)
 	if err != nil {
-		return false, fmt.Errorf("failure unmarshaling WorkflowPayload to SingleWorkflow: %w", err)
+		return nil, fmt.Errorf("failure unmarshaling WorkflowPayload to SingleWorkflow: %w", err)
 	}
-	return jobWorkflow.IncompleteMatrix, nil
+
+	job.workflowPayloadDecoded = &jobWorkflow
+	return job.workflowPayloadDecoded, nil
+}
+
+// If `WorkflowPayload` is changed on an `ActionRunJob`, clear any cached decoded version of the payload.  Typically
+// only used for unit tests.
+func (job *ActionRunJob) ClearCachedWorkflowPayload() {
+	job.workflowPayloadDecoded = nil
+}
+
+// Checks whether the target job is an `(incomplete matrix)` job that will be blocked until the matrix is complete, and
+// then regenerated and deleted.  If it is incomplete, and if the information is available, the specific job and/or
+// output that causes it to be incomplete will be returned as well.
+func (job *ActionRunJob) IsIncompleteMatrix() (bool, *jobparser.IncompleteNeeds, error) {
+	jobWorkflow, err := job.decodeWorkflowPayload()
+	if err != nil {
+		return false, nil, fmt.Errorf("failure decoding workflow payload: %w", err)
+	}
+	return jobWorkflow.IncompleteMatrix, jobWorkflow.IncompleteMatrixNeeds, nil
 }
diff --git a/models/actions/run_job_test.go b/models/actions/run_job_test.go
index a73381f34a..9988e4f621 100644
--- a/models/actions/run_job_test.go
+++ b/models/actions/run_job_test.go
@@ -11,6 +11,7 @@ import (
 	"forgejo.org/models/unittest"
 	"forgejo.org/modules/translation"
 
+	"code.forgejo.org/forgejo/runner/v12/act/jobparser"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 )
@@ -154,6 +155,7 @@ func TestActionRunJob_IsIncompleteMatrix(t *testing.T) {
 		name         string
 		job          ActionRunJob
 		isIncomplete bool
+		needs        *jobparser.IncompleteNeeds
 		errContains  string
 	}{
 		{
@@ -163,7 +165,8 @@ func TestActionRunJob_IsIncompleteMatrix(t *testing.T) {
 		},
 		{
 			name:         "incomplete_matrix workflow",
-			job:          ActionRunJob{WorkflowPayload: []byte("name: workflow\nincomplete_matrix: true")},
+			job:          ActionRunJob{WorkflowPayload: []byte("name: workflow\nincomplete_matrix: true\nincomplete_matrix_needs: { job: abc }")},
+			needs:        &jobparser.IncompleteNeeds{Job: "abc"},
 			isIncomplete: true,
 		},
 		{
@@ -175,12 +178,13 @@ func TestActionRunJob_IsIncompleteMatrix(t *testing.T) {
 
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
-			isIncomplete, err := tt.job.IsIncompleteMatrix()
+			isIncomplete, needs, err := tt.job.IsIncompleteMatrix()
 			if tt.errContains != "" {
 				assert.ErrorContains(t, err, tt.errContains)
 			} else {
 				require.NoError(t, err)
 				assert.Equal(t, tt.isIncomplete, isIncomplete)
+				assert.Equal(t, tt.needs, needs)
 			}
 		})
 	}
diff --git a/options/locale_next/locale_en-US.json b/options/locale_next/locale_en-US.json
index b8337095e6..4b535077cd 100644
--- a/options/locale_next/locale_en-US.json
+++ b/options/locale_next/locale_en-US.json
@@ -215,6 +215,8 @@
     "actions.workflow.job_parsing_error": "Unable to parse jobs in workflow: %v",
     "actions.workflow.event_detection_error": "Unable to parse supported events in workflow: %v",
     "actions.workflow.persistent_incomplete_matrix": "Unable to evaluate `strategy.matrix` of job %[1]s due to a `needs` expression that was invalid. It may reference a job that is not in it's 'needs' list (%[2]s), or an output that doesn't exist on one of those jobs.",
+    "actions.workflow.incomplete_matrix_missing_job": "Unable to evaluate `strategy.matrix` of job %[1]s: job %[2]s is not in the `needs` list of job %[1]s (%[3]s).",
+    "actions.workflow.incomplete_matrix_missing_output": "Unable to evaluate `strategy.matrix` of job %[1]s: job %[2]s does not have an output %[3]s.",
     "actions.workflow.pre_execution_error": "Workflow was not executed due to an error that blocked the execution attempt.",
     "pulse.n_active_issues": {
         "one": "%s active issue",
diff --git a/services/actions/TestActions_consistencyCheckRun/action_run.yml b/services/actions/TestActions_consistencyCheckRun/action_run.yml
new file mode 100644
index 0000000000..5762595905
--- /dev/null
+++ b/services/actions/TestActions_consistencyCheckRun/action_run.yml
@@ -0,0 +1,54 @@
+-
+  id: 900
+  title: "running workflow_dispatch run"
+  repo_id: 63
+  owner_id: 2
+  workflow_id: "running.yaml"
+  index: 4
+  trigger_user_id: 2
+  ref: "refs/heads/main"
+  commit_sha: "97f29ee599c373c729132a5c46a046978311e0ee"
+  trigger_event: "workflow_dispatch"
+  is_fork_pull_request: 0
+  status: 6 # running
+  started: 1683636528
+  created: 1683636108
+  updated: 1683636626
+  need_approval: 0
+  approved_by: 0
+-
+  id: 901
+  title: "running workflow_dispatch run"
+  repo_id: 63
+  owner_id: 2
+  workflow_id: "running.yaml"
+  index: 5
+  trigger_user_id: 2
+  ref: "refs/heads/main"
+  commit_sha: "97f29ee599c373c729132a5c46a046978311e0ee"
+  trigger_event: "workflow_dispatch"
+  is_fork_pull_request: 0
+  status: 6 # running
+  started: 1683636528
+  created: 1683636108
+  updated: 1683636626
+  need_approval: 0
+  approved_by: 0
+-
+  id: 902
+  title: "running workflow_dispatch run"
+  repo_id: 63
+  owner_id: 2
+  workflow_id: "running.yaml"
+  index: 6
+  trigger_user_id: 2
+  ref: "refs/heads/main"
+  commit_sha: "97f29ee599c373c729132a5c46a046978311e0ee"
+  trigger_event: "workflow_dispatch"
+  is_fork_pull_request: 0
+  status: 6 # running
+  started: 1683636528
+  created: 1683636108
+  updated: 1683636626
+  need_approval: 0
+  approved_by: 0
diff --git a/services/actions/TestActions_consistencyCheckRun/action_run_job.yml b/services/actions/TestActions_consistencyCheckRun/action_run_job.yml
new file mode 100644
index 0000000000..ffef2816be
--- /dev/null
+++ b/services/actions/TestActions_consistencyCheckRun/action_run_job.yml
@@ -0,0 +1,113 @@
+-
+  id: 600
+  run_id: 900
+  repo_id: 63
+  owner_id: 2
+  commit_sha: 97f29ee599c373c729132a5c46a046978311e0ee
+  is_fork_pull_request: 0
+  name: job_1
+  attempt: 0
+  job_id: job_1
+  task_id: 0
+  status: 7 # blocked
+  runs_on: '["fedora"]'
+  started: 1683636528
+  needs: '[]'
+  workflow_payload: |
+    "on":
+      push:
+    jobs:
+      produce-artifacts:
+        name: produce-artifacts
+        runs-on: docker
+        steps:
+          - run: echo "OK!"
+        strategy:
+          matrix:
+            color: red
+
+-
+  id: 601
+  run_id: 901
+  repo_id: 63
+  owner_id: 2
+  commit_sha: 97f29ee599c373c729132a5c46a046978311e0ee
+  is_fork_pull_request: 0
+  name: job_1
+  attempt: 0
+  job_id: job_1
+  task_id: 0
+  status: 7 # blocked
+  runs_on: '["fedora"]'
+  needs: '["define-matrix"]'
+  workflow_payload: |
+    "on":
+      push:
+    jobs:
+      produce-artifacts:
+        name: produce-artifacts (incomplete matrix)
+        runs-on: docker
+        steps:
+          - run: echo "OK!"
+        strategy:
+          matrix:
+            color: ${{ fromJSON(needs.define-matrix.outputs.colors) }}
+    incomplete_matrix: true
+    incomplete_matrix_needs:
+      job: define-matrix
+-
+  id: 602
+  run_id: 901
+  repo_id: 63
+  owner_id: 2
+  commit_sha: 97f29ee599c373c729132a5c46a046978311e0ee
+  is_fork_pull_request: 0
+  name: define-matrix
+  attempt: 0
+  job_id: define-matrix
+  task_id: 100
+  status: 1 # success
+  runs_on: '["fedora"]'
+
+-
+  id: 603
+  run_id: 902
+  repo_id: 63
+  owner_id: 2
+  commit_sha: 97f29ee599c373c729132a5c46a046978311e0ee
+  is_fork_pull_request: 0
+  name: job_1
+  attempt: 0
+  job_id: job_1
+  task_id: 0
+  status: 7 # blocked
+  runs_on: '["fedora"]'
+  needs: '["define-matrix"]'
+  workflow_payload: |
+    "on":
+      push:
+    jobs:
+      produce-artifacts:
+        name: produce-artifacts (incomplete matrix)
+        runs-on: docker
+        steps:
+          - run: echo "OK!"
+        strategy:
+          matrix:
+            color: ${{ fromJSON(needs.oops-something-wrong-here.outputs.colors) }}
+    incomplete_matrix: true
+    incomplete_matrix_needs:
+      job: oops-something-wrong-here
+-
+  id: 604
+  run_id: 902
+  repo_id: 63
+  owner_id: 2
+  commit_sha: 97f29ee599c373c729132a5c46a046978311e0ee
+  is_fork_pull_request: 0
+  name: define-matrix
+  attempt: 0
+  job_id: define-matrix
+  task_id: 100
+  status: 1 # success
+  runs_on: '["fedora"]'
diff --git a/services/actions/Test_tryHandleIncompleteMatrix/action_run.yml b/services/actions/Test_tryHandleIncompleteMatrix/action_run.yml
index 701082945e..8ed7d27714 100644
--- a/services/actions/Test_tryHandleIncompleteMatrix/action_run.yml
+++ b/services/actions/Test_tryHandleIncompleteMatrix/action_run.yml
@@ -150,3 +150,22 @@
   need_approval: 0
   approved_by: 0
   concurrency_group: abc123
+-
+  id: 908
+  title: "running workflow_dispatch run"
+  repo_id: 63
+  owner_id: 2
+  workflow_id: "running.yaml"
+  index: 12
+  trigger_user_id: 2
+  ref: "refs/heads/main"
+  commit_sha: "97f29ee599c373c729132a5c46a046978311e0ee"
+  trigger_event: "workflow_dispatch"
+  is_fork_pull_request: 0
+  status: 6 # running
+  started: 1683636528
+  created: 1683636108
+  updated: 1683636626
+  need_approval: 0
+  approved_by: 0
+  concurrency_group: abc123
diff --git a/services/actions/Test_tryHandleIncompleteMatrix/action_run_job.yml b/services/actions/Test_tryHandleIncompleteMatrix/action_run_job.yml
index 296d2d84e3..8334b47002 100644
--- a/services/actions/Test_tryHandleIncompleteMatrix/action_run_job.yml
+++ b/services/actions/Test_tryHandleIncompleteMatrix/action_run_job.yml
@@ -318,3 +318,44 @@
   task_id: 104
   status: 1 # success
   runs_on: '["fedora"]'
+
+-
+  id: 615
+  run_id: 908
+  repo_id: 63
+  owner_id: 2
+  commit_sha: 97f29ee599c373c729132a5c46a046978311e0ee
+  is_fork_pull_request: 0
+  name: job_1
+  attempt: 0
+  job_id: job_1
+  task_id: 0
+  status: 7 # blocked
+  runs_on: '["fedora"]'
+  needs: '["define-matrix-1"]'
+  workflow_payload: |
+    "on":
+      push:
+    jobs:
+      produce-artifacts:
+        name: produce-artifacts (incomplete matrix)
+        runs-on: docker
+        steps:
+          - run: echo "OK!"
+        strategy:
+          matrix:
+            color: ${{ fromJSON(needs.define-matrix-1.outputs.colours-intentional-mistake) }}
+    incomplete_matrix: true
+-
+  id: 616
+  run_id: 908
+  repo_id: 63
+  owner_id: 2
+  commit_sha: 97f29ee599c373c729132a5c46a046978311e0ee
+  is_fork_pull_request: 0
+  name: define-matrix-1
+  attempt: 0
+  job_id: define-matrix-1
+  task_id: 100
+  status: 1 # success
+  runs_on: '["fedora"]'
diff --git a/services/actions/commit_status.go b/services/actions/commit_status.go
index e72f3529e4..e5093301ea 100644
--- a/services/actions/commit_status.go
+++ b/services/actions/commit_status.go
@@ -33,7 +33,7 @@ func CreateCommitStatus(ctx context.Context, jobs ...*actions_model.ActionRunJob
 }
 
 func createCommitStatus(ctx context.Context, job *actions_model.ActionRunJob) error {
-	if incompleteMatrix, err := job.IsIncompleteMatrix(); err != nil {
+	if incompleteMatrix, _, err := job.IsIncompleteMatrix(); err != nil {
 		return fmt.Errorf("job IsIncompleteMatrix: %w", err)
 	} else if incompleteMatrix {
 		// Don't create commit statuses for incomplete matrix jobs because they are never completed.
diff --git a/services/actions/commit_status_test.go b/services/actions/commit_status_test.go
index 3e99932d5e..0872a9d7df 100644
--- a/services/actions/commit_status_test.go
+++ b/services/actions/commit_status_test.go
@@ -23,11 +23,12 @@ func TestCreateCommitStatus_IncompleteMatrix(t *testing.T) {
 	require.ErrorContains(t, err, "object does not exist [id: 7a3858dc7f059543a8807a8b551304b7e362a7ef")
 
 	// Transition from IsIncompleteMatrix()=false to true...
-	isIncomplete, err := job.IsIncompleteMatrix()
+	isIncomplete, _, err := job.IsIncompleteMatrix()
 	require.NoError(t, err)
 	require.False(t, isIncomplete)
 	job.WorkflowPayload = append(job.WorkflowPayload, "\nincomplete_matrix: true\n"...)
-	isIncomplete, err = job.IsIncompleteMatrix()
+	job.ClearCachedWorkflowPayload()
+	isIncomplete, _, err = job.IsIncompleteMatrix()
 	require.NoError(t, err)
 	require.True(t, isIncomplete)
 
diff --git a/services/actions/job_emitter.go b/services/actions/job_emitter.go
index 1282cb7bf9..616632f9aa 100644
--- a/services/actions/job_emitter.go
+++ b/services/actions/job_emitter.go
@@ -182,7 +182,7 @@ func (r *jobStatusResolver) resolve() map[int64]actions_model.Status {
 // Invoked once a job has all its `needs` parameters met and is ready to transition to waiting, this may expand the
 // job's `strategy.matrix` into multiple new jobs.
 func tryHandleIncompleteMatrix(ctx context.Context, blockedJob *actions_model.ActionRunJob, jobsInRun []*actions_model.ActionRunJob) (bool, error) {
-	if incompleteMatrix, err := blockedJob.IsIncompleteMatrix(); err != nil {
+	if incompleteMatrix, _, err := blockedJob.IsIncompleteMatrix(); err != nil {
 		return false, fmt.Errorf("job IsIncompleteMatrix: %w", err)
 	} else if !incompleteMatrix {
 		// Not relevant to attempt expansion if it wasn't marked IncompleteMatrix previously.
@@ -240,25 +240,39 @@ func tryHandleIncompleteMatrix(ctx context.Context, blockedJob *actions_model.Ac
 			// slip this notification into PreExecutionError.
 
 			run := blockedJob.Run
-			run.PreExecutionErrorCode = actions_model.ErrorCodePersistentIncompleteMatrix
-			run.PreExecutionErrorDetails = []any{
-				blockedJob.JobID,
-				strings.Join(blockedJob.Needs, ", "),
-			}
-			run.Status = actions_model.StatusFailure
-			err = actions_model.UpdateRunWithoutNotification(ctx, run,
-				"pre_execution_error_code", "pre_execution_error_details", "status")
-			if err != nil {
-				return false, fmt.Errorf("failure updating PreExecutionError: %w", err)
+
+			var errorCode actions_model.PreExecutionError
+			var errorDetails []any
+
+			// `IncompleteMatrixNeeds` tells us which output was accessed that was missing
+			if swf.IncompleteMatrixNeeds != nil {
+				jobRef := swf.IncompleteMatrixNeeds.Job       // always provided
+				outputRef := swf.IncompleteMatrixNeeds.Output // missing if the entire job wasn't present
+				if outputRef != "" {
+					errorCode = actions_model.ErrorCodeIncompleteMatrixMissingOutput
+					errorDetails = []any{
+						blockedJob.JobID,
+						jobRef,
+						outputRef,
+					}
+				} else {
+					errorCode = actions_model.ErrorCodeIncompleteMatrixMissingJob
+					errorDetails = []any{
+						blockedJob.JobID,
+						jobRef,
+						strings.Join(blockedJob.Needs, ", "),
+					}
+				}
+			} else {
+				errorCode = actions_model.ErrorCodePersistentIncompleteMatrix
+				errorDetails = []any{
+					blockedJob.JobID,
+					strings.Join(blockedJob.Needs, ", "),
+				}
 			}
 
-			// Mark the job as failed as well so that it doesn't remain sitting "blocked" in the UI
-			blockedJob.Status = actions_model.StatusFailure
-			affected, err := UpdateRunJob(ctx, blockedJob, nil, "status")
-			if err != nil {
-				return false, fmt.Errorf("failure updating blockedJob.Status=StatusFailure: %w", err)
-			} else if affected != 1 {
-				return false, fmt.Errorf("expected 1 row to be updated setting blockedJob.Status=StatusFailure, but was %d", affected)
+			if err := FailRunPreExecutionError(ctx, run, errorCode, errorDetails); err != nil {
+				return false, fmt.Errorf("failure when marking run with error: %w", err)
 			}
 
 			// Return `true` to skip running this job in this invalid state
diff --git a/services/actions/job_emitter_test.go b/services/actions/job_emitter_test.go
index c6a9763cc5..93ed3d5158 100644
--- a/services/actions/job_emitter_test.go
+++ b/services/actions/job_emitter_test.go
@@ -167,8 +167,8 @@ func Test_tryHandleIncompleteMatrix(t *testing.T) {
 		{
 			name:                     "missing needs for strategy.matrix evaluation",
 			runJobID:                 605,
-			preExecutionError:        actions_model.ErrorCodePersistentIncompleteMatrix,
-			preExecutionErrorDetails: []any{"job_1", "define-matrix-1"},
+			preExecutionError:        actions_model.ErrorCodeIncompleteMatrixMissingJob,
+			preExecutionErrorDetails: []any{"job_1", "define-matrix-2", "define-matrix-1"},
 		},
 		{
 			name:        "matrix expanded to 0 jobs",
@@ -224,6 +224,12 @@ func Test_tryHandleIncompleteMatrix(t *testing.T) {
 				"scalar-job (just some value)",
 			},
 		},
+		{
+			name:                     "missing needs for strategy.matrix evaluation",
+			runJobID:                 615,
+			preExecutionError:        actions_model.ErrorCodeIncompleteMatrixMissingOutput,
+			preExecutionErrorDetails: []any{"job_1", "define-matrix-1", "colours-intentional-mistake"},
+		},
 	}
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
diff --git a/services/actions/notifier_helper.go b/services/actions/notifier_helper.go
index fb2b2007d8..38970ef86c 100644
--- a/services/actions/notifier_helper.go
+++ b/services/actions/notifier_helper.go
@@ -403,9 +403,11 @@ func handleWorkflows(
 		}
 
 		var jobs []*jobparser.SingleWorkflow
+		var errorCode actions_model.PreExecutionError
+		var errorDetails []any
 		if dwf.EventDetectionError != nil { // don't even bother trying to parse jobs due to event detection error
-			run.PreExecutionErrorCode = actions_model.ErrorCodeEventDetectionError
-			run.PreExecutionErrorDetails = []any{dwf.EventDetectionError.Error()}
+			errorCode = actions_model.ErrorCodeEventDetectionError
+			errorDetails = []any{dwf.EventDetectionError.Error()}
 			run.Status = actions_model.StatusFailure
 			jobs = []*jobparser.SingleWorkflow{{
 				Name: dwf.EntryName,
@@ -419,8 +421,8 @@ func handleWorkflows(
 			)
 			if err != nil {
 				log.Info("jobparser.Parse: invalid workflow, setting job status to failed: %v", err)
-				run.PreExecutionErrorCode = actions_model.ErrorCodeJobParsingError
-				run.PreExecutionErrorDetails = []any{err.Error()}
+				errorCode = actions_model.ErrorCodeJobParsingError
+				errorDetails = []any{err.Error()}
 				run.Status = actions_model.StatusFailure
 				jobs = []*jobparser.SingleWorkflow{{
 					Name: dwf.EntryName,
@@ -438,7 +440,18 @@ func handleWorkflows(
 			}
 		}
 
-		if err := actions_model.InsertRun(ctx, run, jobs); err != nil {
+		err = db.WithTx(ctx, func(ctx context.Context) error {
+			// Transaction avoids any chance of a run being picked up in a Waiting state when we're about to put it into
+			// a PreExecutionError a millisecond later.
+			if err := actions_model.InsertRun(ctx, run, jobs); err != nil {
+				return err
+			}
+			if errorCode != 0 {
+				return FailRunPreExecutionError(ctx, run, errorCode, errorDetails)
+			}
+			return nil
+		})
+		if err != nil {
 			log.Error("InsertRun: %v", err)
 			continue
 		}
@@ -449,6 +462,11 @@ func handleWorkflows(
 			continue
 		}
 		CreateCommitStatus(ctx, alljobs...)
+
+		if err := consistencyCheckRun(ctx, run); err != nil {
+			log.Error("SanityCheckRun: %v", err)
+			continue
+		}
 	}
 	return nil
 }
diff --git a/services/actions/notifier_helper_test.go b/services/actions/notifier_helper_test.go
index 2dfc0108b1..d9e0847056 100644
--- a/services/actions/notifier_helper_test.go
+++ b/services/actions/notifier_helper_test.go
@@ -255,6 +255,7 @@ func TestActionsNotifier_handleWorkflows_setRunTrustForPullRequest(t *testing.T)
 
 	testActionsNotifierPullRequest(t, repo, pr, &actions_module.DetectedWorkflow{
 		NeedApproval: true,
+		Content:      []byte("on: pull_request\njobs: { job_a: {} }"),
 	}, webhook_module.HookEventPullRequest)
 
 	runs, err := db.Find[actions_model.ActionRun](db.DefaultContext, actions_model.FindRunOptions{
diff --git a/services/actions/run.go b/services/actions/run.go
index 7f64e00b92..55f1e0b4c6 100644
--- a/services/actions/run.go
+++ b/services/actions/run.go
@@ -5,25 +5,27 @@ package actions
 
 import (
 	"context"
+	"slices"
+	"strings"
 
 	actions_model "forgejo.org/models/actions"
 	"forgejo.org/models/db"
 	"forgejo.org/modules/timeutil"
 )
 
-func CancelRun(ctx context.Context, run *actions_model.ActionRun) error {
+func killRun(ctx context.Context, run *actions_model.ActionRun, newStatus actions_model.Status) error {
 	return db.WithTx(ctx, func(ctx context.Context) error {
 		jobs, err := actions_model.GetRunJobsByRunID(ctx, run.ID)
 		if err != nil {
 			return err
 		}
 		for _, job := range jobs {
-			status := job.Status
-			if status.IsDone() {
+			oldStatus := job.Status
+			if oldStatus.IsDone() {
 				continue
 			}
 			if job.TaskID == 0 {
-				job.Status = actions_model.StatusCancelled
+				job.Status = newStatus
 				job.Stopped = timeutil.TimeStampNow()
 				_, err := actions_model.UpdateRunJobWithoutNotification(ctx, job, nil, "status", "stopped")
 				if err != nil {
@@ -31,7 +33,7 @@ func CancelRun(ctx context.Context, run *actions_model.ActionRun) error {
 				}
 				continue
 			}
-			if err := StopTask(ctx, job.TaskID, actions_model.StatusCancelled); err != nil {
+			if err := StopTask(ctx, job.TaskID, newStatus); err != nil {
 				return err
 			}
 		}
@@ -48,6 +50,10 @@ func CancelRun(ctx context.Context, run *actions_model.ActionRun) error {
 	})
 }
 
+func CancelRun(ctx context.Context, run *actions_model.ActionRun) error {
+	return killRun(ctx, run, actions_model.StatusCancelled)
+}
+
 func ApproveRun(ctx context.Context, run *actions_model.ActionRun, doerID int64) error {
 	return db.WithTx(ctx, func(ctx context.Context) error {
 		jobs, err := actions_model.GetRunJobsByRunID(ctx, run.ID)
@@ -68,3 +74,85 @@ func ApproveRun(ctx context.Context, run *actions_model.ActionRun, doerID int64)
 		return actions_model.UpdateRunApprovalByID(ctx, run.ID, actions_model.DoesNotNeedApproval, doerID)
 	})
 }
+
+func FailRunPreExecutionError(ctx context.Context, run *actions_model.ActionRun, errorCode actions_model.PreExecutionError, details []any) error {
+	if run.PreExecutionErrorCode != 0 {
+		// Already have one error; keep it.
+		return nil
+	}
+
+	return db.WithTx(ctx, func(ctx context.Context) error {
+		run.Status = actions_model.StatusFailure
+		run.PreExecutionErrorCode = errorCode
+		run.PreExecutionErrorDetails = details
+		if err := actions_model.UpdateRunWithoutNotification(ctx, run,
+			"pre_execution_error_code", "pre_execution_error_details", "status"); err != nil {
+			return err
+		}
+
+		// Also mark every pending job as Failed so nothing remains in a waiting/blocked state.
+		return killRun(ctx, run, actions_model.StatusFailure)
+	})
+}
+
+// Perform pre-execution checks that would affect the ability for a job to reach an executing stage.
+func consistencyCheckRun(ctx context.Context, run *actions_model.ActionRun) error {
+	jobs, err := actions_model.GetRunJobsByRunID(ctx, run.ID)
+	if err != nil {
+		return err
+	}
+	for _, job := range jobs {
+		if stop, err := checkJobWillRevisit(ctx, job); err != nil {
+			return err
+		} else if stop {
+			break
+		}
+	}
+	return nil
+}
+
+func checkJobWillRevisit(ctx context.Context, job *actions_model.ActionRunJob) (bool, error) {
+	// If a job has a matrix like `${{ needs.other-job.outputs.some-output }}`, it will be marked as an
+	// `IncompleteMatrix` job until the `other-job` is completed, and it will be marked as StatusBlocked; then when
+	// `other-job` is completed, the job_emitter will check dependent jobs and revisit them.  But, it's possible that
+	// the job didn't list `other-job` in its `needs: [...]` list -- in this case, a job will be marked as StatusBlocked
+	// forever.
+	//
+	// Check to ensure that a job marked with `IncompleteMatrix` doesn't refer to a job that it doesn't have listed in
+	// `needs`.  If that state is discovered, fail the job and mark a PreExecutionError on the run.
+
+	isIncompleteMatrix, matrixNeeds, err := job.IsIncompleteMatrix()
+	if err != nil {
+		return false, err
+	}
+
+	if !isIncompleteMatrix || matrixNeeds == nil {
+		// Not actually IncompleteMatrix, or has no information about the `${{ needs... }}` reference, nothing we can do
+		// here.
+		return false, nil
+	}
+
+	requiredJob := matrixNeeds.Job
+	needs := job.Needs
+	if slices.Contains(needs, requiredJob) {
+		// Looks good, the needed job is listed in `needs`.  It's possible that the matrix may be incomplete by
+		// referencing multiple different outputs, and not *all* outputs are in the job's `needs`... `requiredJob` will
+		// only be the first one that was found while evaluating the matrix.  But as long as at least one job is listed
+		// in `needs`, the job should be revisited by job_emitter and end up at a final resolution.
+		return false, nil
+	}
+
+	// Job doesn't seem like it can proceed; mark the run with an error.
+	if err := job.LoadRun(ctx); err != nil {
+		return false, err
+	}
+	if err := FailRunPreExecutionError(ctx, job.Run, actions_model.ErrorCodeIncompleteMatrixMissingJob, []any{
+		job.JobID,
+		requiredJob,
+		strings.Join(needs, ", "),
+	}); err != nil {
+		return false, err
+	}
+
+	return true, nil
+}
diff --git a/services/actions/run_test.go b/services/actions/run_test.go
index 15d64a9346..b6d8b36a8c 100644
--- a/services/actions/run_test.go
+++ b/services/actions/run_test.go
@@ -102,3 +102,45 @@ func TestActions_CancelOrApproveRun(t *testing.T) {
 		assert.Equal(t, actions_model.StatusWaiting, job.Status)
 	})
 }
+
+func TestActions_consistencyCheckRun(t *testing.T) {
+	tests := []struct {
+		name                     string
+		runID                    int64
+		errContains              string
+		consumed                 bool
+		runJobNames              []string
+		preExecutionError        actions_model.PreExecutionError
+		preExecutionErrorDetails []any
+	}{
+		{
+			name:  "consistent: not incomplete_matrix",
+			runID: 900,
+		},
+		{
+			name:  "consistent: incomplete_matrix all needs exist",
+			runID: 901,
+		},
+		{
+			name:                     "inconsistent: incomplete_matrix all needs exist",
+			runID:                    902,
+			preExecutionError:        actions_model.ErrorCodeIncompleteMatrixMissingJob,
+			preExecutionErrorDetails: []any{"job_1", "oops-something-wrong-here", "define-matrix"},
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			defer unittest.OverrideFixtures("services/actions/TestActions_consistencyCheckRun")()
+			require.NoError(t, unittest.PrepareTestDatabase())
+
+			run := unittest.AssertExistsAndLoadBean(t, &actions_model.ActionRun{ID: tt.runID})
+
+			err := consistencyCheckRun(t.Context(), run)
+			require.NoError(t, err)
+
+			run = unittest.AssertExistsAndLoadBean(t, &actions_model.ActionRun{ID: tt.runID})
+			assert.Equal(t, tt.preExecutionError, run.PreExecutionErrorCode)
+			assert.Equal(t, tt.preExecutionErrorDetails, run.PreExecutionErrorDetails)
+		})
+	}
+}
diff --git a/services/actions/schedule_tasks.go b/services/actions/schedule_tasks.go
index bcf3b569d0..480897750b 100644
--- a/services/actions/schedule_tasks.go
+++ b/services/actions/schedule_tasks.go
@@ -184,6 +184,10 @@ func CreateScheduleTask(ctx context.Context, cron *actions_model.ActionSchedule)
 		return err
 	}
 
+	if err := consistencyCheckRun(ctx, run); err != nil {
+		return err
+	}
+
 	// Return nil if no errors occurred
 	return nil
 }
diff --git a/services/actions/workflows.go b/services/actions/workflows.go
index fabe9c468c..2c2e439373 100644
--- a/services/actions/workflows.go
+++ b/services/actions/workflows.go
@@ -179,7 +179,11 @@ func (entry *Workflow) Dispatch(ctx context.Context, inputGetter InputValueGette
 		return nil, nil, err
 	}
 
-	return run, jobNames, actions_model.InsertRun(ctx, run, jobs)
+	if err := actions_model.InsertRun(ctx, run, jobs); err != nil {
+		return run, jobNames, err
+	}
+
+	return run, jobNames, consistencyCheckRun(ctx, run)
 }
 
 func GetWorkflowFromCommit(gitRepo *git.Repository, ref, workflowID string) (*Workflow, error) {