feat(actions): support owner-level and global scoped workflows (#38154)

## Summary

This PR adds **scoped workflows** to Gitea Actions. Workflows defined
centrally in a "source" repository that automatically run on every
repository in scope: an organization's repositories, or (for instance
admins) every repository on the instance. Each scoped run executes in
the consuming repository's own context (its runners, secrets, and
branch) while its content is read from the source repository, so an org
or instance can mandate shared CI across many repositories without
copying workflow files into each one.

An owner or instance admin registers source repositories on a settings
page and can mark individual workflows as **required**. A required
scoped workflow cannot be opted out by a consuming repository and gates
its pull-request merges; an optional one can be disabled per repository.
Scoped workflows live under a dedicated `SCOPED_WORKFLOW_DIRS` (default
`.gitea/scoped_workflows`), kept separate from regular `WORKFLOW_DIRS`.

## Main changes

### Configuration 
New `SCOPED_WORKFLOW_DIRS` setting, validated to not overlap with
`WORKFLOW_DIRS`. Default: `.gitea/scoped_workflows`

### Data model & migration
- New `action_scoped_workflow_source` table mapping a registering owner
(`owner_id`, where `0` = instance-level) to a source repository, with a
per-workflow `WorkflowConfigs` map.
- `ActionRun` gains `WorkflowRepoID` / `WorkflowCommitSHA` (the pinned
content source) and an `IsScopedRun` flag.

###  Detection & run creation
On consumer events, scoped workflows from the effective sources (the
owner's own sources plus instance-level ones) are matched and turned
into runs that execute in the consumer's context, with content pinned to
the source repo's default-branch commit.

`on: workflow_run` and `on: schedule` are currently not supported.

###  Opt-out
A consuming repository can disable an optional scoped workflow (tracked
separately from regular `DisabledWorkflows`); required scoped workflows
can never be disabled, opted out, or bypassed.

###  Commit status 
A scoped run's status context format is `"<source repo full name>:
<workflow display name> / <job> (<event>)"`
(for example: `my-org/scoped-workflows: db-tests / test-sqlite
(pull_request)`),
keeping it distinct from a same-named repo-level workflow and from other
sources.

###  Required status checks
Admins mark workflows required and supply status-check patterns.
`EffectiveRequiredContexts` appends those patterns to the branch
protection's required contexts and they are matched
must-present-and-pass. If the status checks from scoped workflows fail,
the PR cannot be merged.

NOTE: scoped workflows' required status checks patterns can protect any
target branch that has a protection rule, even though the rule's "Status
Check" is disabled. A target branch with no protection rule cannot be
protected.

<details>
  <summary>Screenshots</summary>

<img width="1400" alt="image"
src="https://github.com/user-attachments/assets/a5d1db33-15ec-487e-93be-2bc04b4e6643"
/>

</details>


###  Reusable workflows (`uses:`)
A scoped workflow's local `uses: ./...` resolves against the source
repository. `uses:` directory validation honors the
instance-configurable `WORKFLOW_DIRS` and `SCOPED_WORKFLOW_DIRS`
(previously hardcoded to `.gitea`/`.github/workflows`).

###  Manual dispatch
`workflow_dispatch` is supported for scoped workflows (web and API),
resolving inputs/content from the source repo.

###  Performance
A process-local LRU cache keyed by source repo ID for the per-source
workflow parse, so instance-level and owner-level sources don't open the
source repo and parse workflow files on every event.

### UI
Org / user / admin pages to register and remove sources, search
repositories, and mark workflows required with their status-check
patterns. The repository Actions sidebar groups scoped workflows by
source with owner/instance labels and required/disabled badges.

<details>
  <summary>Screenshots</summary>

Scoped workflows setting page:

<img width="1600" alt="image"
src="https://github.com/user-attachments/assets/9d19f667-97a5-4935-92b2-e53f105e3642"
/>


Consumer repo's Actions runs list:

<img width="1600" alt="image"
src="https://github.com/user-attachments/assets/a77241f9-0aa9-41aa-ba73-12a9a688cb64"
/>

- `Owner`: this is a owner-level scoped workflows source repo
- `Global`: this is a global scoped workflows source repo
- `Required`: this scoped workflow is required, repo admin cannot
disable it

</details>

---

Docs: https://gitea.com/gitea/docs/pulls/447

---------

Co-authored-by: bircni <bircni@icloud.com>

modules/actions/jobparser/uses.go

@@ -15,9 +15,11 @@ import (
 type UsesKind int
 
 const (
-	// UsesKindLocalSameRepo is "./.gitea/workflows/foo.yml" - a path inside the calling repository.
+	// UsesKindLocalSameRepo is "./<dir>/foo.yml" - a path inside the calling repository.
+	// For example: "./.gitea/workflows/foo.yml"
 	UsesKindLocalSameRepo UsesKind = iota + 1
-	// UsesKindLocalCrossRepo is "owner/repo/.gitea/workflows/foo.yml@ref" - a workflow in another repo on the same instance.
+	// UsesKindLocalCrossRepo is "owner/repo/<dir>/foo.yml@ref" - a workflow in another repo on the same instance.
+	// For example: "owner/repo/.gitea/workflows/foo.yml@ref"
 	UsesKindLocalCrossRepo
 )
 
@@ -31,14 +33,16 @@ type UsesRef struct {
 }
 
 var (
-	reLocalSameRepo  = regexp.MustCompile(`^\./\.(gitea|github)/workflows/([^@]+\.ya?ml)$`)
-	reLocalCrossRepo = regexp.MustCompile(`^([-.\w]+)/([-.\w]+)/\.(gitea|github)/workflows/([^@]+\.ya?ml)@(.+)$`)
+	reLocalSameRepo  = regexp.MustCompile(`^\./([^@]+\.ya?ml)$`)
+	reLocalCrossRepo = regexp.MustCompile(`^([-.\w]+)/([-.\w]+)/([^@]+\.ya?ml)@(.+)$`)
 )
 
-// ParseUses parses a reusable workflow "uses:" value.
-// Only two forms are supported:
-//   - "./.gitea/workflows/foo.yml"              (UsesKindLocalSameRepo, no @ref)
-//   - "OWNER/REPO/.gitea/workflows/foo.yml@REF" (UsesKindLocalCrossRepo)
+// ParseUses parses the SYNTAX of a reusable workflow "uses:" value into a UsesRef. Two forms are supported:
+//   - "./<dir>/foo.yml"               (UsesKindLocalSameRepo, no @ref)
+//   - "OWNER/REPO/<dir>/foo.yml@REF"  (UsesKindLocalCrossRepo)
+//
+// It deliberately does NOT validate that <dir> is an allowed workflow directory: the allowed directories are instance-configurable (WORKFLOW_DIRS / SCOPED_WORKFLOW_DIRS).
+// The caller (services/actions.ResolveUses) enforces the directory allowlist. The returned Path is the cleaned, repo-relative file path.
 func ParseUses(s string) (*UsesRef, error) {
 	s = strings.TrimSpace(s)
 	if s == "" {
@@ -48,9 +52,9 @@ func ParseUses(s string) (*UsesRef, error) {
 	if strings.HasPrefix(s, "./") {
 		m := reLocalSameRepo.FindStringSubmatch(s)
 		if m == nil {
-			return nil, fmt.Errorf(`invalid local "uses:" %q (expect ./.gitea/workflows/<file>.yml)`, s)
+			return nil, fmt.Errorf(`invalid local "uses:" %q (expect ./<dir>/<file>.yml)`, s)
 		}
-		p := fmt.Sprintf(".%s/workflows/%s", m[1], m[2])
+		p := m[1]
 		if path.Clean(p) != p {
 			return nil, fmt.Errorf("invalid workflow path %q", s)
 		}
@@ -59,9 +63,9 @@ func ParseUses(s string) (*UsesRef, error) {
 
 	m := reLocalCrossRepo.FindStringSubmatch(s)
 	if m == nil {
-		return nil, fmt.Errorf(`invalid cross-repo "uses:" %q (expect owner/repo/.gitea/workflows/<file>.yml@ref)`, s)
+		return nil, fmt.Errorf(`invalid cross-repo "uses:" %q (expect owner/repo/<dir>/<file>.yml@ref)`, s)
 	}
-	p := fmt.Sprintf(".%s/workflows/%s", m[3], m[4])
+	p := m[3]
 	if path.Clean(p) != p {
 		return nil, fmt.Errorf("invalid workflow path %q", s)
 	}
@@ -70,6 +74,6 @@ func ParseUses(s string) (*UsesRef, error) {
 		Owner: m[1],
 		Repo:  m[2],
 		Path:  p,
-		Ref:   m[5],
+		Ref:   m[4],
 	}, nil
 }

modules/actions/jobparser/uses_test.go

@@ -42,6 +42,17 @@ func TestParseUses(t *testing.T) {
 				in:   "./.gitea/workflows/sub/build.yml",
 				want: UsesRef{Kind: UsesKindLocalSameRepo, Path: ".gitea/workflows/sub/build.yml"},
 			},
+			{
+				// ParseUses is dir-agnostic; the allowed directories (WORKFLOW_DIRS / SCOPED_WORKFLOW_DIRS) are enforced by ResolveUses.
+				name: "scoped workflows dir parses",
+				in:   "./.gitea/scoped_workflows/lib.yml",
+				want: UsesRef{Kind: UsesKindLocalSameRepo, Path: ".gitea/scoped_workflows/lib.yml"},
+			},
+			{
+				name: "non-default dir parses (allowlist enforced downstream)",
+				in:   "./.gitea/custom_workflows/x.yaml",
+				want: UsesRef{Kind: UsesKindLocalSameRepo, Path: ".gitea/custom_workflows/x.yaml"},
+			},
 			{
 				name: "leading/trailing whitespace is trimmed",
 				in:   "  ./.gitea/workflows/build.yml  ",
@@ -118,6 +129,17 @@ func TestParseUses(t *testing.T) {
 					Ref:   "v1",
 				},
 			},
+			{
+				name: "scoped workflows dir parses (allowlist enforced by ResolveUses)",
+				in:   "owner/repo/.gitea/scoped_workflows/lib.yml@v1",
+				want: UsesRef{
+					Kind:  UsesKindLocalCrossRepo,
+					Owner: "owner",
+					Repo:  "repo",
+					Path:  ".gitea/scoped_workflows/lib.yml",
+					Ref:   "v1",
+				},
+			},
 		}
 		for _, c := range cases {
 			t.Run(c.name, func(t *testing.T) {
@@ -136,23 +158,20 @@ func TestParseUses(t *testing.T) {
 			{name: "empty string", in: ""},
 			{name: "whitespace only", in: "   "},
 
-			// Same-repo malformed
+			// Same-repo malformed (note: a wrong *directory* parses and should be rejected by the caller)
 			{name: "same-repo with @ref", in: "./.gitea/workflows/build.yml@v1"},
-			{name: "same-repo wrong directory", in: "./not-workflows/build.yml"},
 			{name: "same-repo wrong extension", in: "./.gitea/workflows/build.txt"},
 			{name: "same-repo missing extension", in: "./.gitea/workflows/build"},
 			{name: "same-repo absolute path", in: "/.gitea/workflows/build.yml"},
 			{name: "same-repo path traversal", in: "./.gitea/workflows/../escape.yml"},
 			{name: "same-repo double slash", in: "./.gitea/workflows//build.yml"},
 			{name: "same-repo redundant ./", in: "./.gitea/workflows/./build.yml"},
-			{name: "same-repo no filename", in: "./.gitea/workflows/.yml"},
 
 			// Cross-repo malformed
 			{name: "cross-repo missing @ref", in: "owner/repo/.gitea/workflows/build.yml"},
 			{name: "cross-repo empty ref", in: "owner/repo/.gitea/workflows/build.yml@"},
 			{name: "cross-repo missing owner", in: "/repo/.gitea/workflows/build.yml@v1"},
 			{name: "cross-repo missing repo", in: "owner//.gitea/workflows/build.yml@v1"},
-			{name: "cross-repo wrong workflows dir", in: "owner/repo/workflows/build.yml@v1"},
 			{name: "cross-repo wrong extension", in: "owner/repo/.gitea/workflows/build.txt@v1"},
 			{name: "cross-repo path traversal", in: "owner/repo/.gitea/workflows/../escape.yml@v1"},
 			{name: "cross-repo double slash in path", in: "owner/repo/.gitea/workflows//build.yml@v1"},

modules/actions/scoped_workflows.go

@@ -0,0 +1,83 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package actions
+
+import (
+	"gitea.dev/modules/actions/jobparser"
+	"gitea.dev/modules/git"
+	"gitea.dev/modules/log"
+	"gitea.dev/modules/setting"
+	api "gitea.dev/modules/structs"
+	webhook_module "gitea.dev/modules/webhook"
+)
+
+// ListScopedWorkflows lists scoped workflow files (under SCOPED_WORKFLOW_DIRS) at the given commit.
+func ListScopedWorkflows(commit *git.Commit) (string, git.Entries, error) {
+	return listWorkflowsInDirs(commit, setting.Actions.ScopedWorkflowDirs)
+}
+
+// ParsedScopedWorkflow is one scoped workflow's source-side parse result
+type ParsedScopedWorkflow struct {
+	EntryName   string
+	DisplayName string             // the workflow `name:` or base file name
+	Content     []byte             // raw content of the workflow file
+	Events      []*jobparser.Event // decoded `on:` events
+}
+
+// ParseScopedWorkflows lists and parses the scoped workflow files at sourceCommit (under SCOPED_WORKFLOW_DIRS).
+func ParseScopedWorkflows(sourceCommit *git.Commit) ([]*ParsedScopedWorkflow, error) {
+	_, entries, err := ListScopedWorkflows(sourceCommit)
+	if err != nil {
+		return nil, err
+	}
+
+	parsed := make([]*ParsedScopedWorkflow, 0, len(entries))
+	for _, entry := range entries {
+		content, err := GetContentFromEntry(entry)
+		if err != nil {
+			return nil, err
+		}
+
+		// one workflow may have multiple events
+		events, err := GetEventsFromContent(content)
+		if err != nil {
+			log.Warn("ignore invalid scoped workflow %q: %v", entry.Name(), err)
+			continue
+		}
+		parsed = append(parsed, &ParsedScopedWorkflow{
+			EntryName:   entry.Name(),
+			DisplayName: WorkflowDisplayName(entry.Name(), content),
+			Content:     content,
+			Events:      events,
+		})
+	}
+	return parsed, nil
+}
+
+// MatchScopedWorkflows evaluates already-parsed scoped workflows against one consuming event, returning those whose `on:` matches.
+func MatchScopedWorkflows(
+	parsed []*ParsedScopedWorkflow,
+	consumerGitRepo *git.Repository,
+	consumerCommit *git.Commit,
+	triggedEvent webhook_module.HookEventType,
+	payload api.Payloader,
+) []*DetectedWorkflow {
+	workflows := make([]*DetectedWorkflow, 0, len(parsed))
+	for _, p := range parsed {
+		for _, evt := range p.Events {
+			if evt.IsSchedule() {
+				// schedule is a non-target for scoped workflows
+				continue
+			}
+			if detectMatched(consumerGitRepo, consumerCommit, triggedEvent, payload, evt) {
+				workflows = append(workflows, &DetectedWorkflow{
+					EntryName:    p.EntryName,
+					TriggerEvent: evt,
+					Content:      p.Content,
+				})
+			}
+		}
+	}
+	return workflows
+}

modules/actions/scoped_workflows_test.go

@@ -0,0 +1,62 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package actions
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestIsWorkflowInDirs(t *testing.T) {
+	tests := []struct {
+		name     string
+		dirs     []string
+		path     string
+		expected bool
+	}{
+		{
+			name:     "default scoped dir with yml",
+			dirs:     []string{".gitea/scoped_workflows", ".github/scoped_workflows"},
+			path:     ".gitea/scoped_workflows/security.yml",
+			expected: true,
+		},
+		{
+			name:     "default scoped dir with yaml",
+			dirs:     []string{".gitea/scoped_workflows", ".github/scoped_workflows"},
+			path:     ".github/scoped_workflows/lint.yaml",
+			expected: true,
+		},
+		{
+			name:     "normal workflow path is not a scoped workflow",
+			dirs:     []string{".gitea/scoped_workflows"},
+			path:     ".gitea/workflows/ci.yml",
+			expected: false,
+		},
+		{
+			name:     "non-yaml file",
+			dirs:     []string{".gitea/scoped_workflows"},
+			path:     ".gitea/scoped_workflows/readme.md",
+			expected: false,
+		},
+		{
+			name:     "feature disabled (no scoped dirs)",
+			dirs:     []string{},
+			path:     ".gitea/scoped_workflows/security.yml",
+			expected: false,
+		},
+		{
+			name:     "directory boundary",
+			dirs:     []string{".gitea/scoped_workflows"},
+			path:     ".gitea/scoped_workflows2/security.yml",
+			expected: false,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			assert.Equal(t, tt.expected, isWorkflowInDirs(tt.path, tt.dirs))
+		})
+	}
+}

modules/actions/workflows.go

@@ -5,6 +5,8 @@ package actions
 
 import (
 	"bytes"
+	"fmt"
+	"path"
 	"slices"
 	"strings"
 
@@ -38,11 +40,20 @@ func init() {
 }
 
 func IsWorkflow(path string) bool {
+	return isWorkflowInDirs(path, setting.Actions.WorkflowDirs)
+}
+
+// IsWorkflowOrScopedWorkflow reports whether path is a workflow file under WORKFLOW_DIRS or SCOPED_WORKFLOW_DIRS.
+func IsWorkflowOrScopedWorkflow(path string) bool {
+	return isWorkflowInDirs(path, setting.Actions.WorkflowDirs) || isWorkflowInDirs(path, setting.Actions.ScopedWorkflowDirs)
+}
+
+func isWorkflowInDirs(path string, dirs []string) bool {
 	if (!strings.HasSuffix(path, ".yaml")) && (!strings.HasSuffix(path, ".yml")) {
 		return false
 	}
 
-	for _, workflowDir := range setting.Actions.WorkflowDirs {
+	for _, workflowDir := range dirs {
 		if strings.HasPrefix(path, workflowDir+"/") {
 			return true
 		}
@@ -51,10 +62,14 @@ func IsWorkflow(path string) bool {
 }
 
 func ListWorkflows(commit *git.Commit) (string, git.Entries, error) {
+	return listWorkflowsInDirs(commit, setting.Actions.WorkflowDirs)
+}
+
+func listWorkflowsInDirs(commit *git.Commit, dirs []string) (string, git.Entries, error) {
 	var tree *git.Tree
 	var err error
 	var workflowDir string
-	for _, workflowDir = range setting.Actions.WorkflowDirs {
+	for _, workflowDir = range dirs {
 		tree, err = commit.SubTree(workflowDir)
 		if err == nil {
 			break
@@ -117,6 +132,40 @@ func ValidateWorkflowContent(content []byte) error {
 	return err
 }
 
+// WorkflowDisplayName returns a workflow's display name: its `name:` if non-blank, otherwise the base file name.
+// This is the value used as the workflow segment of its commit-status context.
+func WorkflowDisplayName(file string, content []byte) string {
+	displayName := path.Base(file)
+	if wfs, err := jobparser.Parse(content); err == nil && len(wfs) > 0 {
+		if name := strings.TrimSpace(wfs[0].Name); name != "" {
+			displayName = name
+		}
+	}
+	return displayName
+}
+
+// WorkflowStatusContextName builds a workflow job's commit-status context name: "<display> / <job> (<event>)".
+func WorkflowStatusContextName(displayName, jobName, event string) string {
+	return strings.TrimSpace(fmt.Sprintf("%s / %s (%s)", displayName, jobName, event))
+}
+
+// ScopedWorkflowStatusContextName prefixes a scoped run's status-check context with its source repo, set off by a colon: "<prefix>: <display> / <job> (<event>)".
+func ScopedWorkflowStatusContextName(prefix, displayName, jobName, event string) string {
+	return strings.TrimSpace(fmt.Sprintf("%s: %s", prefix, WorkflowStatusContextName(displayName, jobName, event)))
+}
+
+// ShouldEventCreateCommitStatus reports whether a run triggered by the given workflow `on:` event posts a commit status,
+// so its context can serve as a required status check.
+// TODO: this allowlist duplicates the truth in services/actions.getCommitStatusEventNameAndCommitID, which decides the actual event string and whether a status is posted.
+// The two are kept in sync by hand and can drift; unify them into a single source so adding a status-producing event in one place automatically updates the other.
+func ShouldEventCreateCommitStatus(event string) bool {
+	switch event {
+	case "push", "pull_request", "pull_request_target", "pull_request_review", "pull_request_review_comment", "release":
+		return true
+	}
+	return false
+}
+
 func DetectWorkflows(
 	gitRepo *git.Repository,
 	commit *git.Commit,