feat(actions): add build queue view

Add a "Queue" page to the Actions settings section at repo, org, user
and admin scopes. It lists queued jobs in the exact order runners pick
them up (status=waiting, unclaimed, non-reusable-caller, ordered by
updated,id) plus the jobs currently running, and auto-refreshes the
list in place.

Author: bircni

models/actions/run_job_list.go

@@ -88,6 +88,13 @@ func (jobs ActionJobList) LoadAttributes(ctx context.Context, withRepo bool) err
 	return jobs.LoadRuns(ctx, withRepo)
 }
 
+// QueuedJobsOrderBy mirrors the runner pickup order (see CreateTaskForRunner): waiting jobs are
+// claimed oldest-ready-first, keyed on (updated, id). Use it to render the build queue in pickup order.
+const QueuedJobsOrderBy db.SearchOrderBy = "`action_run_job`.updated ASC, `action_run_job`.id ASC"
+
+// RunningJobsOrderBy lists currently running jobs longest-running-first.
+const RunningJobsOrderBy db.SearchOrderBy = "`action_run_job`.started ASC, `action_run_job`.id ASC"
+
 type FindRunJobOptions struct {
 	db.ListOptions
 	RunID            int64
@@ -96,6 +103,8 @@ type FindRunJobOptions struct {
 	OwnerID          int64
 	CommitSHA        string
 	Statuses         []Status
+	IsReusableCaller optional.Option[bool] // use optional to filter reusable-caller rows in/out; nil means no restriction
+	HasTask          optional.Option[bool] // false: task_id = 0 (unclaimed); true: task_id != 0 (claimed); nil: no restriction
 	UpdatedBefore    timeutil.TimeStamp
 	ConcurrencyGroup string
 	OrderBy          db.SearchOrderBy
@@ -127,6 +136,16 @@ func (opts FindRunJobOptions) ToConds() builder.Cond {
 	if len(opts.Statuses) > 0 {
 		cond = cond.And(builder.In("`action_run_job`.status", opts.Statuses))
 	}
+	if opts.IsReusableCaller.Has() {
+		cond = cond.And(builder.Eq{"`action_run_job`.is_reusable_caller": opts.IsReusableCaller.Value()})
+	}
+	if opts.HasTask.Has() {
+		if opts.HasTask.Value() {
+			cond = cond.And(builder.Neq{"`action_run_job`.task_id": 0})
+		} else {
+			cond = cond.And(builder.Eq{"`action_run_job`.task_id": 0})
+		}
+	}
 	if opts.UpdatedBefore > 0 {
 		cond = cond.And(builder.Lt{"`action_run_job`.updated": opts.UpdatedBefore})
 	}

models/actions/run_job_list_test.go

@@ -6,7 +6,12 @@ package actions
 import (
 	"testing"
 
+	"gitea.dev/models/db"
+	"gitea.dev/models/unittest"
+	"gitea.dev/modules/optional"
+
 	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
 )
 
 func TestActionJobList_SortMatrixGroupsByName(t *testing.T) {
@@ -59,3 +64,61 @@ func TestActionJobList_SortMatrixGroupsByName(t *testing.T) {
 		assert.Equal(t, []string{"only"}, names(jobs))
 	})
 }
+
+// TestFindRunJobOptions_Queue verifies the build-queue query mirrors the runner pickup predicate:
+// waiting + unclaimed + non-reusable jobs, ordered by (updated ASC, id ASC).
+func TestFindRunJobOptions_Queue(t *testing.T) {
+	require.NoError(t, unittest.PrepareTestDatabase())
+	ctx := t.Context()
+
+	// A repo id no fixture or other test uses, so the counts/order below are not polluted.
+	const repoID int64 = 987654
+
+	insert := func(name string, status Status, taskID int64, reusable bool) *ActionRunJob {
+		job := &ActionRunJob{
+			RepoID:           repoID,
+			OwnerID:          1,
+			Name:             name,
+			JobID:            name,
+			Status:           status,
+			TaskID:           taskID,
+			IsReusableCaller: reusable,
+		}
+		require.NoError(t, db.Insert(ctx, job))
+		return job
+	}
+
+	// Genuinely queued jobs: waiting, unclaimed (task_id=0), not reusable callers.
+	jA := insert("a", StatusWaiting, 0, false)
+	jB := insert("b", StatusWaiting, 0, false)
+	jC := insert("c", StatusWaiting, 0, false)
+	// Rows that must be excluded from the queue.
+	insert("claimed", StatusWaiting, 999, false) // already has a task
+	insert("reusable", StatusWaiting, 0, true)   // reusable caller never runs on a runner
+	insert("running", StatusRunning, 998, false) // running, no longer queued
+
+	// Force `updated` so pickup order (updated ASC, id ASC) differs from insertion/id order: C < A < B.
+	setUpdated := func(id, ts int64) {
+		_, err := db.GetEngine(ctx).Exec("UPDATE `action_run_job` SET updated = ? WHERE id = ?", ts, id)
+		require.NoError(t, err)
+	}
+	setUpdated(jC.ID, 100)
+	setUpdated(jA.ID, 200)
+	setUpdated(jB.ID, 300)
+
+	jobs, total, err := db.FindAndCount[ActionRunJob](ctx, FindRunJobOptions{
+		RepoID:           repoID,
+		Statuses:         []Status{StatusWaiting},
+		IsReusableCaller: optional.Some(false),
+		HasTask:          optional.Some(false),
+		OrderBy:          QueuedJobsOrderBy,
+	})
+	require.NoError(t, err)
+	assert.EqualValues(t, 3, total, "only waiting, unclaimed, non-reusable jobs are queued")
+
+	gotIDs := make([]int64, len(jobs))
+	for i, j := range jobs {
+		gotIDs[i] = j.ID
+	}
+	assert.Equal(t, []int64{jC.ID, jA.ID, jB.ID}, gotIDs, "queue is ordered by (updated ASC, id ASC)")
+}

options/locale/locale_en-US.json

@@ -3872,6 +3872,17 @@
   "actions.workflow.has_no_workflow_dispatch": "Workflow '%s' has no workflow_dispatch event trigger.",
   "actions.need_approval_desc": "Need approval to run workflows for fork pull request.",
   "actions.approve_all_success": "All workflow runs are approved successfully.",
+  "actions.queue": "Queue",
+  "actions.queue.queued_jobs": "Queued jobs",
+  "actions.queue.running_jobs": "Running jobs",
+  "actions.queue.position": "#",
+  "actions.queue.job": "Job",
+  "actions.queue.runs_on": "Runs on",
+  "actions.queue.waiting_since": "Waiting since",
+  "actions.queue.started": "Started",
+  "actions.queue.duration": "Duration",
+  "actions.queue.no_queued_jobs": "No jobs are waiting to be picked up.",
+  "actions.queue.no_running_jobs": "No jobs are currently running.",
   "actions.variables": "Variables",
   "actions.variables.management": "Variables Management",
   "actions.variables.creation": "Add Variable",

routers/web/shared/actions/runners.go

@@ -12,7 +12,9 @@ import (
 
 	actions_model "gitea.dev/models/actions"
 	"gitea.dev/models/db"
+	"gitea.dev/modules/container"
 	"gitea.dev/modules/log"
+	"gitea.dev/modules/optional"
 	"gitea.dev/modules/setting"
 	"gitea.dev/modules/templates"
 	"gitea.dev/modules/util"
@@ -168,6 +170,95 @@ func Runners(ctx *context.Context) {
 	ctx.HTML(http.StatusOK, rCtx.RunnersTemplate)
 }
 
+// Queue renders the Actions build queue: waiting jobs in runner pickup order plus currently running jobs.
+func Queue(ctx *context.Context) {
+	ctx.Data["PageIsSharedSettingsQueue"] = true
+	ctx.Data["Title"] = ctx.Tr("actions.actions")
+	ctx.Data["PageType"] = "queue"
+
+	rCtx, err := getRunnersCtx(ctx)
+	if err != nil {
+		ctx.ServerError("getRunnersCtx", err)
+		return
+	}
+
+	// scope narrows the query to the current context. Admin (both 0) sees the whole instance, which is
+	// the only scope where the order is globally exact; repo/org/user scopes show the correct relative
+	// order of their own jobs, but not their absolute position within the instance-wide queue.
+	scope := func(opts *actions_model.FindRunJobOptions) {
+		if rCtx.IsRepo {
+			opts.RepoID = rCtx.RepoID
+		} else if rCtx.IsOrg || rCtx.IsUser {
+			opts.OwnerID = rCtx.OwnerID
+		}
+	}
+
+	page := max(ctx.FormInt("page"), 1)
+
+	// Mirror the runner pickup predicate (see CreateTaskForRunner): waiting, unclaimed, non-reusable-caller jobs.
+	queuedOpts := actions_model.FindRunJobOptions{
+		ListOptions:      db.ListOptions{Page: page, PageSize: 50},
+		Statuses:         []actions_model.Status{actions_model.StatusWaiting},
+		IsReusableCaller: optional.Some(false), // reusable callers never run on a runner, so they are not queued
+		HasTask:          optional.Some(false), // a claimed job already has a task and is no longer queued
+		OrderBy:          actions_model.QueuedJobsOrderBy,
+	}
+	scope(&queuedOpts)
+	queuedJobs, queuedTotal, err := db.FindAndCount[actions_model.ActionRunJob](ctx, queuedOpts)
+	if err != nil {
+		ctx.ServerError("FindQueuedJobs", err)
+		return
+	}
+	if err := actions_model.ActionJobList(queuedJobs).LoadAttributes(ctx, true); err != nil {
+		ctx.ServerError("LoadAttributes", err)
+		return
+	}
+
+	// running jobs are bounded by the number of online runners, so a single capped page is enough.
+	runningOpts := actions_model.FindRunJobOptions{
+		ListOptions: db.ListOptions{Page: 1, PageSize: 100},
+		Statuses:    []actions_model.Status{actions_model.StatusRunning},
+		OrderBy:     actions_model.RunningJobsOrderBy,
+	}
+	scope(&runningOpts)
+	runningJobs, err := db.Find[actions_model.ActionRunJob](ctx, runningOpts)
+	if err != nil {
+		ctx.ServerError("FindRunningJobs", err)
+		return
+	}
+	if err := actions_model.ActionJobList(runningJobs).LoadAttributes(ctx, true); err != nil {
+		ctx.ServerError("LoadAttributes", err)
+		return
+	}
+
+	ctx.Data["QueuedJobs"] = queuedJobs
+	ctx.Data["QueuedTotal"] = queuedTotal
+	ctx.Data["QueueOffset"] = (page - 1) * queuedOpts.PageSize // absolute position of the first row on this page
+	ctx.Data["RunningJobs"] = runningJobs
+	ctx.Data["ShowRepoColumn"] = !rCtx.IsRepo
+
+	pager := context.NewPagination(queuedTotal, queuedOpts.PageSize, page, 5)
+	pager.AddParamFromRequest(ctx.Req)
+	pager.RemoveParam(container.SetOf("refresh")) // keep the auto-refresh flag out of the page links
+	ctx.Data["Page"] = pager
+
+	// The list auto-refreshes by re-fetching just the fragment: poll faster while there is activity,
+	// slower when idle so quiet pages don't hammer the server.
+	hasActivity := len(queuedJobs) > 0 || len(runningJobs) > 0
+	refreshInterval := util.Iif[int64](hasActivity, 3000, 10000)
+	if !setting.IsProd {
+		refreshInterval = util.Iif[int64](hasActivity, 1000, 2000) // faster in dev for easier debugging
+	}
+	ctx.Data["QueueRefreshIntervalMs"] = refreshInterval
+	ctx.Data["QueueRefreshLink"] = templates.QueryBuild(setting.AppSubURL+ctx.Req.RequestURI, "refresh", "1")
+
+	if ctx.FormBool("refresh") {
+		ctx.HTML(http.StatusOK, "shared/actions/queue_list")
+		return
+	}
+	ctx.HTML(http.StatusOK, rCtx.RunnersTemplate)
+}
+
 // RunnersEdit renders runner edit page for repository level
 func RunnersEdit(ctx *context.Context) {
 	ctx.Data["PageIsSharedSettingsRunners"] = true

routers/web/web.go

@@ -509,6 +509,12 @@ func registerWebRoutes(m *web.Router, webAuth *AuthMiddleware) {
 		})
 	}
 
+	addSettingsQueueRoutes := func() {
+		m.Group("/queue", func() {
+			m.Get("", shared_actions.Queue)
+		})
+	}
+
 	// FIXME: not all routes need go through same middleware.
 	// Especially some AJAX requests, we can reduce middleware number to improve performance.
 
@@ -712,6 +718,7 @@ func registerWebRoutes(m *web.Router, webAuth *AuthMiddleware) {
 			addSettingsSecretsRoutes()
 			addSettingsVariablesRoutes()
 			addSettingsScopedWorkflowsRoutes()
+			addSettingsQueueRoutes()
 		}, actions.MustEnableActions)
 
 		m.Get("/organization", user_setting.Organization)
@@ -876,6 +883,7 @@ func registerWebRoutes(m *web.Router, webAuth *AuthMiddleware) {
 			m.Post("/runners/bulk", shared_actions.RunnerBulkActionPost)
 			addSettingsVariablesRoutes()
 			addSettingsScopedWorkflowsRoutes()
+			addSettingsQueueRoutes()
 		})
 	}, adminReq, ctxDataSet("EnableOAuth2", setting.OAuth2.Enabled, "EnablePackages", setting.Packages.Enabled))
 	// ***** END: Admin *****
@@ -1034,6 +1042,7 @@ func registerWebRoutes(m *web.Router, webAuth *AuthMiddleware) {
 					addSettingsSecretsRoutes()
 					addSettingsVariablesRoutes()
 					addSettingsScopedWorkflowsRoutes()
+					addSettingsQueueRoutes()
 				}, actions.MustEnableActions)
 
 				m.Post("/rename", web.Bind(forms.RenameOrgForm{}), org.SettingsRenamePost)
@@ -1245,6 +1254,7 @@ func registerWebRoutes(m *web.Router, webAuth *AuthMiddleware) {
 			addSettingsRunnersRoutes()
 			addSettingsSecretsRoutes()
 			addSettingsVariablesRoutes()
+			addSettingsQueueRoutes()
 			m.Group("/general", func() {
 				m.Group("/collaborative_owner", func() {
 					m.Post("/add", repo_setting.AddCollaborativeOwner)

templates/admin/actions.tmpl

@@ -9,5 +9,8 @@
 	{{if eq .PageType "scoped-workflows"}}
 		{{template "shared/actions/scoped_workflows" .}}
 	{{end}}
+	{{if eq .PageType "queue"}}
+		{{template "shared/actions/queue_list" .}}
+	{{end}}
 	</div>
 {{template "admin/layout_footer" .}}

templates/admin/navbar.tmpl

@@ -72,7 +72,7 @@
 			{{end}}
 		{{end}}
 		{{if .EnableActions}}
-		<details class="item" {{if or .PageIsSharedSettingsRunners .PageIsSharedSettingsVariables .PageIsSharedSettingsScopedWorkflows}}open{{end}}>
+		<details class="item" {{if or .PageIsSharedSettingsRunners .PageIsSharedSettingsVariables .PageIsSharedSettingsScopedWorkflows .PageIsSharedSettingsQueue}}open{{end}}>
 			<summary>{{ctx.Locale.Tr "actions.actions"}}</summary>
 			<div class="menu">
 				<a class="{{if .PageIsSharedSettingsRunners}}active {{end}}item" href="{{AppSubUrl}}/-/admin/actions/runners">
@@ -84,6 +84,9 @@
 				<a class="{{if .PageIsSharedSettingsScopedWorkflows}}active {{end}}item" href="{{AppSubUrl}}/-/admin/actions/scoped-workflows">
 					{{ctx.Locale.Tr "actions.scoped_workflows"}}
 				</a>
+				<a class="{{if .PageIsSharedSettingsQueue}}active {{end}}item" href="{{AppSubUrl}}/-/admin/actions/queue">
+					{{ctx.Locale.Tr "actions.queue"}}
+				</a>
 			</div>
 		</details>
 		{{end}}

templates/org/settings/actions.tmpl

@@ -8,6 +8,8 @@
 		{{template "shared/variables/variable_list" .}}
 	{{else if eq .PageType "scoped-workflows"}}
 		{{template "shared/actions/scoped_workflows" .}}
+	{{else if eq .PageType "queue"}}
+		{{template "shared/actions/queue_list" .}}
 	{{end}}
 	</div>
 {{template "org/settings/layout_footer" .}}

templates/org/settings/navbar.tmpl

@@ -26,7 +26,7 @@
 		</a>
 		{{end}}
 		{{if .EnableActions}}
-		<details class="item" {{if or .PageIsOrgSettingsActionsGeneral .PageIsSharedSettingsRunners .PageIsSharedSettingsSecrets .PageIsSharedSettingsVariables .PageIsSharedSettingsScopedWorkflows}}open{{end}}>
+		<details class="item" {{if or .PageIsOrgSettingsActionsGeneral .PageIsSharedSettingsRunners .PageIsSharedSettingsSecrets .PageIsSharedSettingsVariables .PageIsSharedSettingsScopedWorkflows .PageIsSharedSettingsQueue}}open{{end}}>
 			<summary>{{ctx.Locale.Tr "actions.actions"}}</summary>
 			<div class="menu">
 				<a class="{{if .PageIsOrgSettingsActionsGeneral}}active {{end}}item" href="{{.OrgLink}}/settings/actions">
@@ -44,6 +44,9 @@
 				<a class="{{if .PageIsSharedSettingsScopedWorkflows}}active {{end}}item" href="{{.OrgLink}}/settings/actions/scoped-workflows">
 					{{ctx.Locale.Tr "actions.scoped_workflows"}}
 				</a>
+				<a class="{{if .PageIsSharedSettingsQueue}}active {{end}}item" href="{{.OrgLink}}/settings/actions/queue">
+					{{ctx.Locale.Tr "actions.queue"}}
+				</a>
 			</div>
 		</details>
 		{{end}}

templates/repo/settings/actions.tmpl

@@ -8,6 +8,8 @@
 			{{template "shared/variables/variable_list" .}}
 		{{else if eq .PageType "general"}}
 			{{template "repo/settings/actions_general" .}}
+		{{else if eq .PageType "queue"}}
+			{{template "shared/actions/queue_list" .}}
 		{{end}}
 	</div>
 {{template "repo/settings/layout_footer" .}}