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>
2025-12-07 14:09:47 +00:00 · 2025-12-05 17:17:37 +01:00 · 2025-12-05 17:17:37 +01:00 · 0ecc6ef632
commit 0ecc6ef632
parent 7e74d142d6
19 changed files with 497 additions and 41 deletions
--- 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)
 }
--- 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) {
--- 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
 }
--- 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)
 			}
 		})
 	}
--- 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",
--- a/services/actions/TestActions_consistencyCheckRun/action_run.yml
+++ 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
--- a/services/actions/TestActions_consistencyCheckRun/action_run_job.yml
+++ 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"]'
--- 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
--- 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"]'
--- 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.
--- 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)

--- 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
--- 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) {
--- 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
 }
--- 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{
--- 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
+}
--- 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)
+		})
+	}
+}
--- 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
 }
--- 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) {