feat: Add configurable permissions for Actions automatic tokens #36173

Excellencedev · 2025-12-17T06:20:07Z

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.).
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.
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

Unit Tests: Run go test ./services/actions/... and go test ./models/repo/... to verify parsing logic and permission clamping.
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.
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

/fixes #24635
/claim #24635

Excellencedev · 2025-12-17T11:31:19Z

@lunny @wxiaoguang Please review this

wxiaoguang · 2025-12-17T12:30:54Z

Thank you for asking me to review, but I don't use Actions. You can invite the maintainers from the original issue to review.

Excellencedev · 2025-12-17T14:29:21Z

Thank you for asking me to review, but I don't use Actions. You can invite the maintainers from the original issue to review.

@silverwind Please review

silverwind · 2025-12-17T17:14:54Z

I review mostly frontend stuff and am not much of an actions user myself, so please be patient until someone finds time to review it properly.

Excellencedev · 2025-12-17T17:30:04Z

I review mostly frontend stuff and am not much of an actions user myself, so please be patient until someone finds time to review it properly.

No problem

routers/web/repo/setting/actions.go

tests/integration/actions_job_token_test.go

wxiaoguang · 2025-12-17T19:01:16Z

By the way, I see another (older) PR: Feat/actions token permissions #36113 , it added more than 2000 lines of code.

What are the differences? Which PR would win ....... @Zettat123

Zettat123 · 2025-12-17T20:53:54Z

By the way, I see another (older) PR: Feat/actions token permissions #36113 , it added more than 2000 lines of code.

What are the differences? Which PR would win ....... @Zettat123

This PR doesn't fully implement the proposal in #24635. (For example, it doesn't support configuring actions access between repositories in the same organization)

It seems that #36113 implemented these features, but I think its code needs improvement.

templates/repo/settings/actions_general.tmpl

silverwind · 2025-12-18T01:47:54Z

Issues I see on this screenshot:

Header text is black on dark theme
Contrast on light text is too low

I can probably help fix those, the first one may be a missing override of the fomantic CSS.

Excellencedev · 2025-12-18T01:53:03Z

@Zettat123 @silverwind Pls give me a few hours(15-20 hours) and this PR will be ready to go
I will make sure to address all your comments and make sure I do everything from the issue
Drafting until then
When it is done, I will undraft it and notify you

wxiaoguang · 2025-12-18T01:57:15Z

By the way, I see another (older) PR: Feat/actions token permissions #36113 , it added more than 2000 lines of code.
What are the differences? Which PR would win ....... @Zettat123

This PR doesn't fully implement the proposal in #24635. (For example, it doesn't support configuring actions access between repositories in the same organization)

It seems that #36113 implemented these features, but I think its code needs improvement.

But "PR: Feat/actions token permissions #36113" came first, and it is more complete, why not respect the first author, but only review this second one?

Excellencedev · 2025-12-18T01:59:50Z

By the way, I see another (older) PR: Feat/actions token permissions #36113 , it added more than 2000 lines of code.
What are the differences? Which PR would win ....... @Zettat123

This PR doesn't fully implement the proposal in #24635. (For example, it doesn't support configuring actions access between repositories in the same organization)
It seems that #36113 implemented these features, but I think its code needs improvement.

But "PR: Feat/actions token permissions #36113" came first, and it is more complete, why not respect the first author, but only review this second one?

@wxiaoguang should i close my pr ?

wxiaoguang · 2025-12-18T02:07:38Z

By the way, I see another (older) PR: Feat/actions token permissions #36113 , it added more than 2000 lines of code.
What are the differences? Which PR would win ....... @Zettat123

This PR doesn't fully implement the proposal in #24635. (For example, it doesn't support configuring actions access between repositories in the same organization)
It seems that #36113 implemented these features, but I think its code needs improvement.

But "PR: Feat/actions token permissions #36113" came first, and it is more complete, why not respect the first author, but only review this second one?

@wxiaoguang should i close my pr ?

I don't know. Reviewers decide.

Zettat123 · 2025-12-18T02:09:57Z

By the way, I see another (older) PR: Feat/actions token permissions #36113 , it added more than 2000 lines of code.
What are the differences? Which PR would win ....... @Zettat123

This PR doesn't fully implement the proposal in #24635. (For example, it doesn't support configuring actions access between repositories in the same organization)
It seems that #36113 implemented these features, but I think its code needs improvement.

But "PR: Feat/actions token permissions #36113" came first, and it is more complete, why not respect the first author, but only review this second one?

I reviewed both PRs, but did not receive responses to my comments in #36113. If @Excellencedev will address the review comments, I think we should keep this PR.

silverwind · 2025-12-18T02:12:59Z

Imho, the only sensible thing we can do is race these 2 PRs.

Excellencedev · 2025-12-18T03:03:36Z

Adressed most your comments in my latest commit, now i just need to make sure i fully implement the proposal in #24635

models/repo/repo_unit.go

Zettat123 · 2025-12-18T03:26:52Z

According to the solution in #24635, I think this PR does not implement:

Support configuring the permissions
Support configuring access between repositories
Private packages can be accessed by Actions only when they have been linked to repositories

Excellencedev · 2026-01-07T08:15:17Z

@ChristopherHX pls review...thanks
I will be updating docs too soon

ChristopherHX · 2026-01-07T10:15:33Z

In my opinion, I don't think we should use contents. In GitHub, contents controls permissions for both code and releases.

Banning contents for workflows stored in .gitea sounds like reasonable approach for me, but could still force users to update their workflows as it has been ignored for years.

(Could be done by schema checking and rejecting the workflow run if contents is present then show an run start failure. Pointing to docs.) (I had already started Schema Checking in nektos/act, just need a permissive schema for gitea that only covers permissions for now)

In .github folder I prefer contents to remain consistent with GitHub.

Need to allocate some time to go through this PR.

Excellencedev · 2026-01-07T10:22:17Z

@ChristopherHX Is what I did here okay 28dff2a ?

ChristopherHX · 2026-01-07T10:39:03Z

28dff2a

My problem with

			case "contents":
				result.Code = accessMode
				result.Releases = accessMode

is that result.Releases and result.Code could already be set to a lower value explicitly. If we agree to not allow running such workflow then the code here could be kept.
e.g.

releases: none
contents: write

A schema could also mention either releases and code or contents is valid. Currently you could mix them without contents having a lower priority in your parsing code.

Excellencedev · 2026-01-07T11:14:44Z

I've refactored the parser to implement priority: contents is applied first, then granular scopes like code and releases override it. This ensures specific keywords always take precedence over the broad contents keyword, regardless of their order in the YAML. I added unit test to verify this
Fix is in 43931dc

Excellencedev · 2026-01-07T11:48:28Z

@ChristopherHX @Zettat123 I added a docs update for this PR: https://gitea.com/gitea/docs/pulls/318

models/perm/access/repo_permission.go

Zettat123 · 2026-01-07T17:48:09Z

I found a TODO in services/context/package.go. Do we need to implement it, or should we remove it?

gitea/services/context/package.go

Lines 95 to 105 in f9d3983

    
           func determineAccessMode(ctx *Base, pkg *Package, doer *user_model.User) (perm.AccessMode, error) { 
        
           	if setting.Service.RequireSignInViewStrict && (doer == nil || doer.IsGhost()) { 
        
           		return perm.AccessModeNone, nil 
        
           	} 
        
           	if doer != nil && !doer.IsGhost() && (!doer.IsActive || doer.ProhibitLogin) { 
        
           		return perm.AccessModeNone, nil 
        
           	} 
        
           	// TODO: ActionUser permission check 
        
           	accessMode := perm.AccessModeNone

Excellencedev · 2026-01-07T18:24:00Z

I found a TODO in services/context/package.go. Do we need to implement it, or should we remove it?

gitea/services/context/package.go

Lines 95 to 105 in f9d3983

func determineAccessMode(ctx *Base, pkg *Package, doer *user_model.User) (perm.AccessMode, error) {

if setting.Service.RequireSignInViewStrict && (doer == nil || doer.IsGhost()) {

return perm.AccessModeNone, nil

}

if doer != nil && !doer.IsGhost() && (!doer.IsActive || doer.ProhibitLogin) {

return perm.AccessModeNone, nil

}

// TODO: ActionUser permission check

accessMode := perm.AccessModeNone

@Zettat123 fixed f8a0b25

routers/api/packages/api.go

Excellencedev · 2026-01-07T19:56:48Z

ready for another review @Zettat123

models/repo/repo_unit.go

Excellencedev · 2026-01-09T00:53:04Z

@Zettat123 @ChristopherHX pls review this

Zettat123 · 2026-01-09T21:42:16Z

models/repo/repo_unit.go

+	TokenPermissionMode ActionsTokenPermissionMode `json:"token_permission_mode,omitempty"`
+	// DefaultTokenPermissions defines the specific permissions for workflow tokens when TokenPermissionMode is set to "custom"
+	// and no "permissions" keyword is defined in the workflow YAML.
+	DefaultTokenPermissions *ActionsTokenPermissions `json:"default_token_permissions,omitempty"`


I've reviewed the code. If I understand correctly, the steps you listed are for MaxTokenPermissions, not DefaultTokenPermissions. I'm still not sure what DefaultTokenPermissions actually does. If it's a necessary field, we need a form to configure it on the UI. If not, we should remove it.

Zettat123 · 2026-01-09T21:43:49Z

Based on the recent comments, it appears that the current implementation still contains logical inconsistencies and redundant code. This suggests that the PR requires a more thorough analysis of the existing code and a more comprehensive integration of the review comments provided so far.

To ensure we use everyone’s time effectively, I am converting this PR back to Draft status. Since maintainer resources are limited, we expect contributors to perform a rigorous self-review before requesting a formal review. Please ensure the logic is fully closed, redundant elements are removed, and similar issues throughout the PR are addressed consistently.

While I would like to help move this PR forward, I am currently tied up with several urgent tasks and do not have the bandwidth to review a PR of this size at this moment. Once you feel the PR is truly ready and you have switched the status back to "Ready for review," I welcome other reviewers to review this PR and provide their feedback. I would appreciate any comments on this.

Excellencedev · 2026-01-10T04:11:07Z

Okay understood but I hope this PR won't just amount to nothing as it's been open for almost a month with several review comments from different maintainers

I will work throughout next week to make this "reviewable" an snake sure maintainers have a good time reviewing this

I just hope other maintainers will have on this in the future also

feat: Add configurable permissions for Actions automatic tokens

3a10e8f

GiteaBot added the lgtm/need 2 This PR needs two approvals by maintainers to be considered for merging. label Dec 17, 2025

algora-pbc bot added the 🙋 Bounty claim label Dec 17, 2025

github-actions bot added modifies/translation modifies/go Pull requests that update Go code modifies/templates This PR modifies the template files labels Dec 17, 2025

Merge branch 'main' into fix-24635

249794c

lunny requested a review from Zettat123 December 17, 2025 16:53

Zettat123 reviewed Dec 17, 2025

View reviewed changes

routers/web/repo/setting/actions.go Show resolved Hide resolved

routers/web/repo/setting/actions.go Show resolved Hide resolved

tests/integration/actions_job_token_test.go Show resolved Hide resolved

Merge branch 'main' into fix-24635

e20d12e

silverwind reviewed Dec 18, 2025

View reviewed changes

templates/repo/settings/actions_general.tmpl Outdated Show resolved Hide resolved

Excellencedev marked this pull request as draft December 18, 2025 01:53

Adress all review comments

9a69f65

Zettat123 reviewed Dec 18, 2025

View reviewed changes

models/repo/repo_unit.go Show resolved Hide resolved

lunny requested a review from ChristopherHX January 7, 2026 06:19

refactor the parser

43931dc

github-actions bot removed the docs-update-needed The document needs to be updated synchronously label Jan 7, 2026

Zettat123 reviewed Jan 7, 2026

View reviewed changes

models/perm/access/repo_permission.go Show resolved Hide resolved

add releases and projects units

a5debd9

Excellencedev requested a review from Zettat123 January 7, 2026 17:45

Excellencedev force-pushed the fix-24635 branch from eebb54f to a5debd9 Compare January 7, 2026 18:16

resolve todo

f8a0b25

Zettat123 reviewed Jan 7, 2026

View reviewed changes

routers/api/packages/api.go Outdated Show resolved Hide resolved

fixes

1dfc172

Excellencedev requested a review from Zettat123 January 7, 2026 19:00

Excellencedev added 2 commits January 7, 2026 20:21

formatting issues

1840f0a

...

7364953

Zettat123 reviewed Jan 7, 2026

View reviewed changes

models/repo/repo_unit.go Show resolved Hide resolved

improve comments

4e524d3

Excellencedev requested a review from Zettat123 January 8, 2026 02:34

Zettat123 reviewed Jan 9, 2026

View reviewed changes

lunny marked this pull request as draft January 9, 2026 22:50

Uh oh!

feat: Add configurable permissions for Actions automatic tokens #36173

Are you sure you want to change the base?

feat: Add configurable permissions for Actions automatic tokens #36173

Uh oh!

Conversation

Excellencedev commented Dec 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Overview

Key Features

1. Granular Token Permissions

2. Organization & Repository Settings

3. Security Hardening

4. Technical Implementation

How to Test

Documentation

Uh oh!

Excellencedev commented Dec 17, 2025

Uh oh!

wxiaoguang commented Dec 17, 2025

Uh oh!

Excellencedev commented Dec 17, 2025

Uh oh!

silverwind commented Dec 17, 2025

Uh oh!

Excellencedev commented Dec 17, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

wxiaoguang commented Dec 17, 2025

Uh oh!

Zettat123 commented Dec 17, 2025

Uh oh!

Uh oh!

silverwind commented Dec 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Excellencedev commented Dec 18, 2025

Uh oh!

wxiaoguang commented Dec 18, 2025

Uh oh!

Excellencedev commented Dec 18, 2025

Uh oh!

wxiaoguang commented Dec 18, 2025

Uh oh!

Zettat123 commented Dec 18, 2025

Uh oh!

silverwind commented Dec 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Excellencedev commented Dec 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Zettat123 commented Dec 18, 2025

Uh oh!

Excellencedev commented Jan 7, 2026

Uh oh!

ChristopherHX commented Jan 7, 2026

Uh oh!

Excellencedev commented Jan 7, 2026

Uh oh!

ChristopherHX commented Jan 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Excellencedev commented Jan 7, 2026

Uh oh!

Excellencedev commented Jan 7, 2026

Uh oh!

Uh oh!

Zettat123 commented Jan 7, 2026

Uh oh!

Excellencedev commented Jan 7, 2026

Uh oh!

Uh oh!

Excellencedev commented Jan 7, 2026

Uh oh!

Uh oh!

Excellencedev commented Jan 9, 2026

Excellencedev commented Dec 17, 2025 •

edited

Loading

silverwind commented Dec 18, 2025 •

edited

Loading

silverwind commented Dec 18, 2025 •

edited

Loading

Excellencedev commented Dec 18, 2025 •

edited

Loading

ChristopherHX commented Jan 7, 2026 •

edited

Loading

Excellencedev commented Jan 10, 2026 •

edited

Loading