feat: Add configurable permissions for Actions automatic tokens (#36173)

## Overview

This PR introduces granular permission controls for Gitea Actions tokens
(`GITEA_TOKEN`), aligning Gitea's security model with GitHub Actions
standards while maintaining compatibility with Gitea's unique repository
unit system.

It addresses the need for finer access control by allowing
administrators and repository owners to define default token
permissions, set maximum permission ceilings, and control
cross-repository access within organizations.

## Key Features

### 1. Granular Token Permissions

- **Standard Keyword Support**: Implements support for the
`permissions:` keyword in workflow and job YAML files (e.g., `contents:
read`, `issues: write`).
- **Permission Modes**:
- **Permissive**: Default write access for most units (backwards
compatible).
- **Restricted**: Default read-only access for `contents` and
`packages`, with no access to other units.
- ~~**Custom**: Allows defining specific default levels for each unit
type (Code, Issues, PRs, Packages, etc.).~~**EDIT removed UI was
confusing**
- **Clamping Logic**: Workflow-defined permissions are automatically
"clamped" by repository or organization-level maximum settings.
Workflows cannot escalate their own permissions beyond these limits.

### 2. Organization & Repository Settings

- **Settings UI**: Added new settings pages at both Organization and
Repository levels to manage Actions token defaults and maximums.
- **Inheritance**: Repositories can be configured to "Follow
organization-level configuration," simplifying management across large
organizations.
- **Cross-Repository Access**: Added a policy to control whether Actions
workflows can access other repositories or packages within the same
organization. This can be set to "None," "All," or restricted to a
"Selected" list of repositories.

### 3. Security Hardening

- **Fork Pull Request Protection**: Tokens for workflows triggered by
pull requests from forks are strictly enforced as read-only, regardless
of repository settings.
- ~~**Package Access**: Actions tokens can now only access packages
explicitly linked to a repository, with cross-repo access governed by
the organization's security policy.~~ **EDIT removed
https://github.com/go-gitea/gitea/pull/36173#issuecomment-3873675346**
- **Git Hook Integration**: Propagates Actions Task IDs to git hooks to
ensure that pushes performed by Actions tokens respect the specific
permissions granted at runtime.

### 4. Technical Implementation

- **Permission Persistence**: Parsed permissions are calculated at job
creation and stored in the `action_run_job` table. This ensures the
token's authority is deterministic throughout the job's lifecycle.
- **Parsing Priority**: Implemented a priority system in the YAML parser
where the broad `contents` scope is applied first, allowing granular
scopes like `code` or `releases` to override it for precise control.
- **Re-runs**: Permissions are re-evaluated during a job re-run to
incorporate any changes made to repository settings in the interim.

### How to Test

1. **Unit Tests**: Run `go test ./services/actions/...` and `go test
./models/repo/...` to verify parsing logic and permission clamping.
2. **Integration Tests**: Comprehensive tests have been added to
`tests/integration/actions_job_token_test.go` covering:
   - Permissive vs. Restricted mode behavior.
   - YAML `permissions:` keyword evaluation.
   - Organization cross-repo access policies.
- Resource access (Git, API, and Packages) under various permission
configs.
3. **Manual Verification**: 
   - Navigate to **Site/Org/Repo Settings -> Actions -> General**.
- Change "Default Token Permissions" and verify that newly triggered
workflows reflect these changes in their `GITEA_TOKEN` capabilities.
- Attempt a cross-repo API call from an Action and verify the Org policy
is enforced.

## Documentation

Added a PR in gitea's docs for this :
https://gitea.com/gitea/docs/pulls/318

## UI:

<img width="1366" height="619" alt="Screenshot 2026-01-24 174112"
src="https://github.com/user-attachments/assets/bfa29c9a-4ea5-4346-9410-16d491ef3d44"
/>

<img width="1360" height="621" alt="Screenshot 2026-01-24 174048"
src="https://github.com/user-attachments/assets/d5ec46c8-9a13-4874-a6a4-fb379936cef5"
/>

/fixes #24635
/claim #24635

---------

Signed-off-by: Excellencedev <ademiluyisuccessandexcellence@gmail.com>
Signed-off-by: ChristopherHX <christopher.homberger@web.de>
Signed-off-by: silverwind <me@silverwind.io>
Signed-off-by: wxiaoguang <wxiaoguang@gmail.com>
Co-authored-by: ChristopherHX <christopher.homberger@web.de>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: silverwind <me@silverwind.io>
Co-authored-by: Zettat123 <zettat123@gmail.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: wxiaoguang <wxiaoguang@gmail.com>

models/actions/config.go

@@ -0,0 +1,74 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package actions
+
+import (
+	"context"
+
+	"code.gitea.io/gitea/models/perm"
+	repo_model "code.gitea.io/gitea/models/repo"
+	user_model "code.gitea.io/gitea/models/user"
+	"code.gitea.io/gitea/modules/json"
+	"code.gitea.io/gitea/modules/util"
+
+	"xorm.io/xorm/convert"
+)
+
+// OwnerActionsConfig defines the Actions configuration for a user or organization
+type OwnerActionsConfig struct {
+	// TokenPermissionMode defines the default permission mode (permissive, restricted)
+	TokenPermissionMode repo_model.ActionsTokenPermissionMode `json:"token_permission_mode,omitempty"`
+
+	// MaxTokenPermissions defines the absolute maximum permissions any token can have in this context.
+	MaxTokenPermissions *repo_model.ActionsTokenPermissions `json:"max_token_permissions,omitempty"`
+
+	// AllowedCrossRepoIDs is a list of specific repo IDs that can be accessed cross-repo
+	AllowedCrossRepoIDs []int64 `json:"allowed_cross_repo_ids,omitempty"`
+}
+
+var _ convert.ConversionFrom = (*OwnerActionsConfig)(nil)
+
+func (cfg *OwnerActionsConfig) FromDB(bytes []byte) error {
+	_ = json.Unmarshal(bytes, cfg)
+	cfg.TokenPermissionMode, _ = util.EnumValue(cfg.TokenPermissionMode)
+	return nil
+}
+
+// GetOwnerActionsConfig loads the OwnerActionsConfig for a user or organization from user settings
+// It returns a default config if no setting is found
+func GetOwnerActionsConfig(ctx context.Context, userID int64) (ret OwnerActionsConfig, err error) {
+	return user_model.GetUserSettingJSON(ctx, userID, user_model.SettingsKeyActionsConfig, ret)
+}
+
+// SetOwnerActionsConfig saves the OwnerActionsConfig for a user or organization to user settings
+func SetOwnerActionsConfig(ctx context.Context, userID int64, cfg OwnerActionsConfig) error {
+	return user_model.SetUserSettingJSON(ctx, userID, user_model.SettingsKeyActionsConfig, cfg)
+}
+
+// GetDefaultTokenPermissions returns the default token permissions by its TokenPermissionMode.
+func (cfg *OwnerActionsConfig) GetDefaultTokenPermissions() repo_model.ActionsTokenPermissions {
+	switch cfg.TokenPermissionMode {
+	case repo_model.ActionsTokenPermissionModeRestricted:
+		return repo_model.MakeRestrictedPermissions()
+	case repo_model.ActionsTokenPermissionModePermissive:
+		return repo_model.MakeActionsTokenPermissions(perm.AccessModeWrite)
+	default:
+		return repo_model.MakeActionsTokenPermissions(perm.AccessModeNone)
+	}
+}
+
+// GetMaxTokenPermissions returns the maximum allowed permissions
+func (cfg *OwnerActionsConfig) GetMaxTokenPermissions() repo_model.ActionsTokenPermissions {
+	if cfg.MaxTokenPermissions != nil {
+		return *cfg.MaxTokenPermissions
+	}
+	// Default max is write for everything
+	return repo_model.MakeActionsTokenPermissions(perm.AccessModeWrite)
+}
+
+// ClampPermissions ensures that the given permissions don't exceed the maximum
+func (cfg *OwnerActionsConfig) ClampPermissions(perms repo_model.ActionsTokenPermissions) repo_model.ActionsTokenPermissions {
+	maxPerms := cfg.GetMaxTokenPermissions()
+	return repo_model.ClampActionsTokenPermissions(perms, maxPerms)
+}

models/actions/run_job.go

@@ -51,6 +51,11 @@ 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
 
+	// TokenPermissions stores the explicit permissions from workflow/job YAML (no org/repo clamps applied).
+	// Org/repo clamps are enforced when the token is used at runtime.
+	// It is JSON-encoded repo_model.ActionsTokenPermissions and may be empty if not specified.
+	TokenPermissions *repo_model.ActionsTokenPermissions `xorm:"JSON TEXT"`
+
 	Started timeutil.TimeStamp
 	Stopped timeutil.TimeStamp
 	Created timeutil.TimeStamp `xorm:"created"`

models/actions/token_permissions.go

@@ -0,0 +1,60 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package actions
+
+import (
+	"context"
+
+	repo_model "code.gitea.io/gitea/models/repo"
+	"code.gitea.io/gitea/models/unit"
+)
+
+// ComputeTaskTokenPermissions computes the effective permissions for a job token against the target repository.
+// It uses the job's stored permissions (if any), then applies org/repo clamps and fork/cross-repo restrictions.
+// Note: target repository access policy checks are enforced in GetActionsUserRepoPermission; this function only computes the job token's effective permission ceiling.
+func ComputeTaskTokenPermissions(ctx context.Context, task *ActionTask, targetRepo *repo_model.Repository) (ret repo_model.ActionsTokenPermissions, err error) {
+	if err := task.LoadJob(ctx); err != nil {
+		return ret, err
+	}
+	if err := task.Job.LoadRepo(ctx); err != nil {
+		return ret, err
+	}
+	runRepo := task.Job.Repo
+
+	if err := runRepo.LoadOwner(ctx); err != nil {
+		return ret, err
+	}
+
+	repoActionsCfg := runRepo.MustGetUnit(ctx, unit.TypeActions).ActionsConfig()
+	ownerActionsCfg, err := GetOwnerActionsConfig(ctx, runRepo.OwnerID)
+	if err != nil {
+		return ret, err
+	}
+
+	var jobDeclaredPerms repo_model.ActionsTokenPermissions
+	if task.Job.TokenPermissions != nil {
+		jobDeclaredPerms = *task.Job.TokenPermissions
+	} else if repoActionsCfg.OverrideOwnerConfig {
+		jobDeclaredPerms = repoActionsCfg.GetDefaultTokenPermissions()
+	} else {
+		jobDeclaredPerms = ownerActionsCfg.GetDefaultTokenPermissions()
+	}
+
+	var effectivePerms repo_model.ActionsTokenPermissions
+	if repoActionsCfg.OverrideOwnerConfig {
+		effectivePerms = repoActionsCfg.ClampPermissions(jobDeclaredPerms)
+	} else {
+		effectivePerms = ownerActionsCfg.ClampPermissions(jobDeclaredPerms)
+	}
+
+	// Cross-repository access and fork pull requests are strictly read-only for security.
+	// This ensures a "task repo" cannot gain write access to other repositories via CrossRepoAccess settings.
+	isSameRepo := task.Job.RepoID == targetRepo.ID
+	restrictCrossRepoAccess := task.IsForkPullRequest || !isSameRepo
+	if restrictCrossRepoAccess {
+		effectivePerms = repo_model.ClampActionsTokenPermissions(effectivePerms, repo_model.MakeRestrictedPermissions())
+	}
+
+	return effectivePerms, nil
+}