feat: Add max-parallel implementation inside the GItea server

Author: ZPascal

models/actions/run_job.go

@@ -51,6 +51,10 @@ type ActionRunJob struct {
 	ConcurrencyGroup  string `xorm:"index(repo_concurrency) NOT NULL DEFAULT ''"` // evaluated concurrency.group
 	ConcurrencyCancel bool   `xorm:"NOT NULL DEFAULT FALSE"`                      // evaluated concurrency.cancel-in-progress
 
+	// Matrix job support
+	MatrixID    string `xorm:"VARCHAR(255) index"` // Unique identifier for matrix combination (e.g., "os:ubuntu,node:16")
+	MaxParallel int    // Max parallel jobs from strategy.max-parallel (0 = unlimited)
+
 	Started timeutil.TimeStamp
 	Stopped timeutil.TimeStamp
 	Created timeutil.TimeStamp `xorm:"created"`

models/actions/run_job_maxparallel_test.go

@@ -0,0 +1,141 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package actions
+
+import (
+	"testing"
+
+	"code.gitea.io/gitea/models/db"
+	"code.gitea.io/gitea/models/unittest"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestActionRunJob_MaxParallel(t *testing.T) {
+	assert.NoError(t, unittest.PrepareTestDatabase())
+	ctx := db.DefaultContext
+
+	t.Run("NoMaxParallel", func(t *testing.T) {
+		job := &ActionRunJob{
+			RunID:       1,
+			RepoID:      1,
+			OwnerID:     1,
+			JobID:       "test-job-1",
+			Name:        "Test Job",
+			Status:      StatusWaiting,
+			MaxParallel: 0, // No limit
+		}
+		assert.NoError(t, db.Insert(ctx, job))
+
+		retrieved, err := GetRunJobByID(ctx, job.ID)
+		assert.NoError(t, err)
+		assert.Equal(t, 0, retrieved.MaxParallel)
+	})
+
+	t.Run("WithMaxParallel", func(t *testing.T) {
+		job := &ActionRunJob{
+			RunID:       1,
+			RepoID:      1,
+			OwnerID:     1,
+			JobID:       "test-job-2",
+			Name:        "Matrix Job",
+			Status:      StatusWaiting,
+			MaxParallel: 3,
+		}
+		assert.NoError(t, db.Insert(ctx, job))
+
+		retrieved, err := GetRunJobByID(ctx, job.ID)
+		assert.NoError(t, err)
+		assert.Equal(t, 3, retrieved.MaxParallel)
+	})
+
+	t.Run("MatrixID", func(t *testing.T) {
+		job := &ActionRunJob{
+			RunID:       1,
+			RepoID:      1,
+			OwnerID:     1,
+			JobID:       "test-job-3",
+			Name:        "Matrix Job with ID",
+			Status:      StatusWaiting,
+			MaxParallel: 2,
+			MatrixID:    "os:ubuntu,node:16",
+		}
+		assert.NoError(t, db.Insert(ctx, job))
+
+		retrieved, err := GetRunJobByID(ctx, job.ID)
+		assert.NoError(t, err)
+		assert.Equal(t, 2, retrieved.MaxParallel)
+		assert.Equal(t, "os:ubuntu,node:16", retrieved.MatrixID)
+	})
+
+	t.Run("UpdateMaxParallel", func(t *testing.T) {
+		job := &ActionRunJob{
+			RunID:       1,
+			RepoID:      1,
+			OwnerID:     1,
+			JobID:       "test-job-4",
+			Name:        "Updatable Job",
+			Status:      StatusWaiting,
+			MaxParallel: 5,
+		}
+		assert.NoError(t, db.Insert(ctx, job))
+
+		// Update max parallel
+		job.MaxParallel = 10
+		_, err := UpdateRunJob(ctx, job, nil, "max_parallel")
+		assert.NoError(t, err)
+
+		retrieved, err := GetRunJobByID(ctx, job.ID)
+		assert.NoError(t, err)
+		assert.Equal(t, 10, retrieved.MaxParallel)
+	})
+}
+
+func TestActionRunJob_MaxParallelEnforcement(t *testing.T) {
+	assert.NoError(t, unittest.PrepareTestDatabase())
+	ctx := db.DefaultContext
+
+	t.Run("EnforceMaxParallel", func(t *testing.T) {
+		runID := int64(5000)
+		jobID := "parallel-enforced-job"
+		maxParallel := 2
+
+		// Create jobs simulating matrix execution
+		jobs := []*ActionRunJob{
+			{RunID: runID, RepoID: 1, OwnerID: 1, JobID: jobID, Name: "Job 1", Status: StatusRunning, MaxParallel: maxParallel, MatrixID: "version:1"},
+			{RunID: runID, RepoID: 1, OwnerID: 1, JobID: jobID, Name: "Job 2", Status: StatusRunning, MaxParallel: maxParallel, MatrixID: "version:2"},
+			{RunID: runID, RepoID: 1, OwnerID: 1, JobID: jobID, Name: "Job 3", Status: StatusWaiting, MaxParallel: maxParallel, MatrixID: "version:3"},
+			{RunID: runID, RepoID: 1, OwnerID: 1, JobID: jobID, Name: "Job 4", Status: StatusWaiting, MaxParallel: maxParallel, MatrixID: "version:4"},
+		}
+
+		for _, job := range jobs {
+			assert.NoError(t, db.Insert(ctx, job))
+		}
+
+		// Verify running count
+		runningCount, err := CountRunningJobsByWorkflowAndRun(ctx, runID, jobID)
+		assert.NoError(t, err)
+		assert.Equal(t, maxParallel, runningCount, "Should have exactly max-parallel jobs running")
+
+		// Simulate job completion
+		jobs[0].Status = StatusSuccess
+		_, err = UpdateRunJob(ctx, jobs[0], nil, "status")
+		assert.NoError(t, err)
+
+		// Now running count should be 1
+		runningCount, err = CountRunningJobsByWorkflowAndRun(ctx, runID, jobID)
+		assert.NoError(t, err)
+		assert.Equal(t, 1, runningCount)
+
+		// Simulate next job starting
+		jobs[2].Status = StatusRunning
+		_, err = UpdateRunJob(ctx, jobs[2], nil, "status")
+		assert.NoError(t, err)
+
+		// Back to max-parallel
+		runningCount, err = CountRunningJobsByWorkflowAndRun(ctx, runID, jobID)
+		assert.NoError(t, err)
+		assert.Equal(t, maxParallel, runningCount)
+	})
+}

models/actions/runner.go

@@ -62,6 +62,8 @@ type ActionRunner struct {
 	AgentLabels []string `xorm:"TEXT"`
 	// Store if this is a runner that only ever get one single job assigned
 	Ephemeral bool `xorm:"ephemeral NOT NULL DEFAULT false"`
+	// Maximum number of parallel tasks this runner can execute (0 = unlimited, defaults to 1)
+	Capacity int `xorm:"NOT NULL DEFAULT 1"`
 
 	Created timeutil.TimeStamp `xorm:"created"`
 	Updated timeutil.TimeStamp `xorm:"updated"`

models/actions/runner_capacity_test.go

@@ -0,0 +1,91 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package actions
+
+import (
+	"testing"
+
+	"code.gitea.io/gitea/models/db"
+	"code.gitea.io/gitea/models/unittest"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestActionRunner_Capacity(t *testing.T) {
+	assert.NoError(t, unittest.PrepareTestDatabase())
+	ctx := db.DefaultContext
+
+	t.Run("DefaultCapacity", func(t *testing.T) {
+		runner := &ActionRunner{
+			UUID:    "test-uuid-1",
+			Name:    "test-runner",
+			OwnerID: 0,
+			RepoID:  0,
+		}
+		assert.NoError(t, db.Insert(ctx, runner))
+
+		// Default capacity should be 1
+		assert.Equal(t, 1, runner.Capacity)
+
+		// Verify in database
+		retrieved, err := GetRunnerByID(ctx, runner.ID)
+		assert.NoError(t, err)
+		assert.Equal(t, 1, retrieved.Capacity)
+	})
+
+	t.Run("CustomCapacity", func(t *testing.T) {
+		runner := &ActionRunner{
+			UUID:     "test-uuid-2",
+			Name:     "test-runner-2",
+			OwnerID:  0,
+			RepoID:   0,
+			Capacity: 5,
+		}
+		assert.NoError(t, db.Insert(ctx, runner))
+
+		assert.Equal(t, 5, runner.Capacity)
+
+		// Verify in database
+		retrieved, err := GetRunnerByID(ctx, runner.ID)
+		assert.NoError(t, err)
+		assert.Equal(t, 5, retrieved.Capacity)
+	})
+
+	t.Run("UpdateCapacity", func(t *testing.T) {
+		runner := &ActionRunner{
+			UUID:     "test-uuid-3",
+			Name:     "test-runner-3",
+			OwnerID:  0,
+			RepoID:   0,
+			Capacity: 1,
+		}
+		assert.NoError(t, db.Insert(ctx, runner))
+
+		// Update capacity
+		runner.Capacity = 10
+		assert.NoError(t, UpdateRunner(ctx, runner, "capacity"))
+
+		// Verify update
+		retrieved, err := GetRunnerByID(ctx, runner.ID)
+		assert.NoError(t, err)
+		assert.Equal(t, 10, retrieved.Capacity)
+	})
+
+	t.Run("ZeroCapacity", func(t *testing.T) {
+		runner := &ActionRunner{
+			UUID:     "test-uuid-4",
+			Name:     "test-runner-4",
+			OwnerID:  0,
+			RepoID:   0,
+			Capacity: 0, // Unlimited
+		}
+		assert.NoError(t, db.Insert(ctx, runner))
+
+		assert.Equal(t, 0, runner.Capacity)
+
+		retrieved, err := GetRunnerByID(ctx, runner.ID)
+		assert.NoError(t, err)
+		assert.Equal(t, 0, retrieved.Capacity)
+	})
+}

models/actions/task.go

@@ -244,10 +244,26 @@ func CreateTaskForRunner(ctx context.Context, runner *ActionRunner) (*ActionTask
 	var job *ActionRunJob
 	log.Trace("runner labels: %v", runner.AgentLabels)
 	for _, v := range jobs {
-		if runner.CanMatchLabels(v.RunsOn) {
-			job = v
-			break
+		if !runner.CanMatchLabels(v.RunsOn) {
+			continue
 		}
+
+		// Check max-parallel constraint for matrix jobs
+		if v.MaxParallel > 0 {
+			runningCount, err := CountRunningJobsByWorkflowAndRun(ctx, v.RunID, v.JobID)
+			if err != nil {
+				log.Error("Failed to count running jobs for max-parallel check: %v", err)
+				continue
+			}
+			if runningCount >= v.MaxParallel {
+				log.Debug("Job %s (run %d) skipped: %d/%d jobs already running (max-parallel)",
+					v.JobID, v.RunID, runningCount, v.MaxParallel)
+				continue
+			}
+		}
+
+		job = v
+		break
 	}
 	if job == nil {
 		return nil, false, nil
@@ -505,3 +521,23 @@ func getTaskIDFromCache(token string) int64 {
 	}
 	return t
 }
+
+// CountRunningTasksByRunner counts the number of running tasks assigned to a specific runner
+func CountRunningTasksByRunner(ctx context.Context, runnerID int64) (int, error) {
+	count, err := db.GetEngine(ctx).
+		Where("runner_id = ?", runnerID).
+		And("status = ?", StatusRunning).
+		Count(new(ActionTask))
+	return int(count), err
+}
+
+// CountRunningJobsByWorkflowAndRun counts running jobs for a specific workflow/run combo
+// Used to enforce max-parallel limits on matrix jobs
+func CountRunningJobsByWorkflowAndRun(ctx context.Context, runID int64, jobID string) (int, error) {
+	count, err := db.GetEngine(ctx).
+		Where("run_id = ?", runID).
+		And("job_id = ?", jobID).
+		And("status = ?", StatusRunning).
+		Count(new(ActionRunJob))
+	return int(count), err
+}