feat(org): add team visibility so org members can discover teams (#37680)

Closes #37670. Today, org members in Gitea only see teams they're a member of. In larger orgs that hurts onboarding and discoverability — there's no way to look up which team owns what without asking around. GitHub solves this with a per-team visibility setting; this PR brings the same model to Gitea. ## What changes - Every team gets a `visibility` setting: - `private` *(default)* — only team members and org owners can see the team. Same as today's behavior. - `limited` — listable by any member of the organization. Members and the repos the team has access to are visible too. Non-org-members still see nothing. - `public` — listable by any signed-in user. - The Owners team visibility is fixed and cannot be changed via settings. - Existing teams default to `private`, so this is a no-op for anyone who doesn't change anything. ## API - `Team`, `CreateTeamOption`, `EditTeamOption` all gain a `visibility` field (string enum: `private` | `limited` | `public`). - `GET /orgs/{org}/teams` and `/orgs/{org}/teams/search` now apply the same visibility rules as the web UI: - site admins and org owners still see every team - other org members see their own teams plus any `limited` or `public` team - `private` teams are no longer leaked through these endpoints - Swagger/OpenAPI specs regenerated. ## UI View from admin2 (not an owner): <img width="1669" height="726" src="https://github.com/user-attachments/assets/daf4bccb-644b-4426-b178-71963aeaf73b" /> View from admin (owner): <img width="2559" height="863" src="https://github.com/user-attachments/assets/4f22cebc-e9df-4fd2-8ed4-724d31fadb7a" /> --------- Signed-off-by: bircni <bircni@icloud.com> Co-authored-by: TheFox0x7 <thefox0x7@gmail.com> Co-authored-by: wxiaoguang <wxiaoguang@gmail.com>
2026-06-15 20:25:18 +02:00 · 2026-06-14 21:07:25 +02:00
parent 80ca22a9ef
commit 55250407dd
31 changed files with 850 additions and 144 deletions
--- a/models/db/engine.go
+++ b/models/db/engine.go
@@ -28,9 +28,8 @@ var (
 	registeredInitFuncs []func() error
 )

-// Engine represents a xorm engine or session.
-type Engine interface {
-	Table(tableNameOrBean any) *xorm.Session
+// SQLSession represents a common interface for engine and session to execute SQLs
+type SQLSession interface {
 	Count(...any) (int64, error)
 	Decr(column string, arg ...any) *xorm.Session
 	Delete(...any) (int64, error)
@@ -52,7 +51,6 @@ type Engine interface {
 	Limit(limit int, start ...int) *xorm.Session
 	NoAutoTime() *xorm.Session
 	SumInt(bean any, columnName string) (res int64, err error)
-	Sync(...any) error
 	Select(string) *xorm.Session
 	SetExpr(string, any) *xorm.Session
 	NotIn(string, ...any) *xorm.Session
@@ -61,12 +59,20 @@ type Engine interface {
 	Distinct(...string) *xorm.Session
 	Query(...any) ([]map[string][]byte, error)
 	Cols(...string) *xorm.Session
+	Table(tableNameOrBean any) *xorm.Session
 	Context(ctx context.Context) *xorm.Session
-	Ping() error
+	QueryInterface(sqlOrArgs ...any) ([]map[string]any, error)
 	IsTableExist(tableNameOrBean any) (bool, error)
 }

-// Session represents a xorm session interface, used as an abstraction over *xorm.Session.
+// Engine represents a xorm engine
+type Engine interface {
+	SQLSession
+	Sync(...any) error
+	Ping() error
+}
+
+// Session represents a xorm session interface
 type Session interface {
 	Engine
 	And(query any, args ...any) *xorm.Session
@@ -89,7 +95,6 @@ type EngineMigration interface {
 	Dialect() dialects.Dialect
 	DropTables(beans ...any) error
 	NewSession() *xorm.Session
-	QueryInterface(sqlOrArgs ...any) ([]map[string]any, error)
 	SetMapper(mapper names.Mapper)
 	SyncWithOptions(opts xorm.SyncOptions, beans ...any) (*xorm.SyncResult, error)
 	TableInfo(bean any) (*schemas.Table, error)
--- a/models/db/list.go
+++ b/models/db/list.go
@@ -24,10 +24,9 @@ type Paginator interface {
 }

 // SetSessionPagination sets pagination for a database session
-func SetSessionPagination(sess Engine, p Paginator) Session {
+func SetSessionPagination(sess Engine, p Paginator) {
 	skip, take := p.GetSkipTake()
-
-	return sess.Limit(take, skip)
+	sess.Limit(take, skip)
 }

 // ListOptions options to paginate results
--- a/models/issues/pull_list.go
+++ b/models/issues/pull_list.go
@@ -181,7 +181,7 @@ func PullRequests(ctx context.Context, baseRepoID int64, opts *PullRequestsOptio

 	findSession := listPullRequestStatement(ctx, baseRepoID, opts)
 	applySorts(findSession, opts.SortType, 0)
-	findSession = db.SetSessionPagination(findSession, opts)
+	db.SetSessionPagination(findSession, opts)
 	prs := make([]*PullRequest, 0, opts.PageSize)
 	found := findSession.Find(&prs)
 	return prs, maxResults, found
--- a/models/migrations/migrations.go
+++ b/models/migrations/migrations.go
@@ -414,6 +414,7 @@ func prepareMigrationTasks() []*migration {
 		newMigration(334, "Add cancelling support to action runners", v1_27.AddCancellingSupportToActionRunner),
 		newMigration(335, "Add reusable workflow fields and action_run_attempt_job_id_index table for ActionRunJob", v1_27.AddReusableWorkflowFieldsToActionRunJob),
 		newMigration(336, "Add ActionRunJobSummary table", v1_27.AddActionRunJobSummaryTable),
+		newMigration(337, "Add visibility to team", v1_27.AddVisibilityToTeam),
 	}
 	return preparedMigrations
 }
--- a/models/migrations/v1_27/v337.go
+++ b/models/migrations/v1_27/v337.go
@@ -0,0 +1,36 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package v1_27
+
+import (
+	"gitea.dev/models/db"
+
+	"xorm.io/xorm"
+)
+
+type VisibleType int
+
+type teamWithVisibility struct {
+	Visibility VisibleType `xorm:"NOT NULL DEFAULT 2"`
+}
+
+func (teamWithVisibility) TableName() string {
+	return "team"
+}
+
+func AddVisibilityToTeam(x db.EngineMigration) error {
+	if _, err := x.SyncWithOptions(xorm.SyncOptions{
+		IgnoreDropIndices: true,
+		IgnoreConstrains:  true,
+	}, new(teamWithVisibility)); err != nil {
+		return err
+	}
+
+	// Owner teams must remain listable to all org members; new orgs create
+	// them as "limited", so make existing owner teams limited too.
+	// Filter on authorize=4 (AccessModeOwner) so a user-created team that
+	// happens to share the name "owners" is not accidentally affected.
+	_, err := x.Exec("UPDATE `team` SET visibility = ? WHERE lower_name = ? AND authorize = ?", 1, "owners", 4)
+	return err
+}
--- a/models/organization/org.go
+++ b/models/organization/org.go
@@ -370,6 +370,7 @@ func CreateOrganization(ctx context.Context, org *Organization, owner *user_mode
 			NumMembers:              1,
 			IncludesAllRepositories: true,
 			CanCreateOrgRepo:        true,
+			Visibility:              structs.VisibleTypeLimited,
 		}
 		if err = db.Insert(ctx, t); err != nil {
 			return fmt.Errorf("insert owner team: %w", err)
--- a/models/organization/team.go
+++ b/models/organization/team.go
@@ -14,6 +14,7 @@ import (
 	"gitea.dev/models/unit"
 	user_model "gitea.dev/models/user"
 	"gitea.dev/modules/log"
+	"gitea.dev/modules/structs"
 	"gitea.dev/modules/util"

 	"xorm.io/builder"
@@ -81,9 +82,36 @@ type Team struct {
 	Members                 []*user_model.User `xorm:"-"`
 	NumRepos                int
 	NumMembers              int
-	Units                   []*TeamUnit `xorm:"-"`
-	IncludesAllRepositories bool        `xorm:"NOT NULL DEFAULT false"`
-	CanCreateOrgRepo        bool        `xorm:"NOT NULL DEFAULT false"`
+	Units                   []*TeamUnit         `xorm:"-"`
+	IncludesAllRepositories bool                `xorm:"NOT NULL DEFAULT false"`
+	CanCreateOrgRepo        bool                `xorm:"NOT NULL DEFAULT false"`
+	Visibility              structs.VisibleType `xorm:"NOT NULL DEFAULT 2"`
+}
+
+func (t *Team) IsPublic() bool  { return t.Visibility.IsPublic() }
+func (t *Team) IsLimited() bool { return t.Visibility.IsLimited() }
+func (t *Team) IsPrivate() bool { return t.Visibility.IsPrivate() }
+
+// CanNonMemberReadMeta reports whether a non-member, non-owner doer may read
+// the team's metadata, based on the team's visibility tier and the parent org's
+// visibility. Privileged callers (site admins, org owners, team members) are
+// decided by the caller before reaching here.
+func (t *Team) CanNonMemberReadMeta(ctx context.Context, org, doer *user_model.User) (bool, error) {
+	switch t.Visibility {
+	case structs.VisibleTypePublic:
+		return HasOrgOrUserVisible(ctx, org, doer), nil
+	case structs.VisibleTypeLimited:
+		return IsOrganizationMember(ctx, t.OrgID, doer.ID)
+	default:
+		return false, nil
+	}
+}
+
+func NormalizeTeamVisibility(s string) structs.VisibleType {
+	if vt, ok := structs.VisibilityModes[s]; ok {
+		return vt
+	}
+	return structs.VisibleTypePrivate
 }

 func init() {
--- a/models/organization/team_list.go
+++ b/models/organization/team_list.go
@@ -10,6 +10,8 @@ import (
 	"gitea.dev/models/db"
 	"gitea.dev/models/perm"
 	"gitea.dev/models/unit"
+	user_model "gitea.dev/models/user"
+	"gitea.dev/modules/structs"

 	"xorm.io/builder"
 )
@@ -50,9 +52,15 @@ type SearchTeamOptions struct {
 	Keyword     string
 	OrgID       int64
 	IncludeDesc bool
+	// IncludeVisibilities, when combined with UserID, also returns teams whose
+	// visibility is in this list, even if UserID is not a member. Typical values:
+	//   - {limited,public} for org members
+	//   - {public} for signed-in users who are not org members
+	// Leave empty to return only teams the user is a member of.
+	IncludeVisibilities []structs.VisibleType
 }

-func (opts *SearchTeamOptions) toCond() builder.Cond {
+func (opts *SearchTeamOptions) applyToSession(sess db.SQLSession) {
 	cond := builder.NewCond()

 	if len(opts.Keyword) > 0 {
@@ -68,11 +76,51 @@ func (opts *SearchTeamOptions) toCond() builder.Cond {
 		cond = cond.And(builder.Eq{"`team`.org_id": opts.OrgID})
 	}

-	if opts.UserID > 0 {
+	switch {
+	case opts.UserID > 0 && len(opts.IncludeVisibilities) > 0:
+		sess = sess.Join("LEFT", "team_user", "team_user.team_id = team.id AND team_user.uid = ?", opts.UserID)
+		cond = cond.And(builder.Or(
+			builder.Eq{"team_user.uid": opts.UserID},
+			builder.In("`team`.visibility", opts.IncludeVisibilities),
+		))
+	case opts.UserID > 0:
+		sess = sess.Join("INNER", "team_user", "team_user.team_id = team.id")
 		cond = cond.And(builder.Eq{"team_user.uid": opts.UserID})
+	case len(opts.IncludeVisibilities) > 0:
+		cond = cond.And(builder.In("`team`.visibility", opts.IncludeVisibilities))
 	}
+	sess.Where(cond)
+}

-	return cond
+func VisibleTeamVisibilitiesFor(isOrgMember, isSignedIn bool) []structs.VisibleType {
+	switch {
+	case isOrgMember:
+		return []structs.VisibleType{structs.VisibleTypeLimited, structs.VisibleTypePublic}
+	case isSignedIn:
+		return []structs.VisibleType{structs.VisibleTypePublic}
+	default:
+		return nil
+	}
+}
+
+func ApplyTeamListFilter(ctx context.Context, orgID int64, viewer *user_model.User, isSignedIn bool, opts *SearchTeamOptions) error {
+	if viewer.IsAdmin {
+		return nil
+	}
+	isOwner, err := IsOrganizationOwner(ctx, orgID, viewer.ID)
+	if err != nil {
+		return err
+	}
+	if isOwner {
+		return nil
+	}
+	isOrgMember, err := IsOrganizationMember(ctx, orgID, viewer.ID)
+	if err != nil {
+		return err
+	}
+	opts.UserID = viewer.ID
+	opts.IncludeVisibilities = VisibleTeamVisibilitiesFor(isOrgMember, isSignedIn)
+	return nil
 }

 // SearchTeam search for teams. Caller is responsible to check permissions.
@@ -80,15 +128,12 @@ func SearchTeam(ctx context.Context, opts *SearchTeamOptions) (TeamList, int64,
 	sess := db.GetEngine(ctx)

 	opts.SetDefaultValues()
-	cond := opts.toCond()
+	opts.applyToSession(sess)

-	if opts.UserID > 0 {
-		sess = sess.Join("INNER", "team_user", "team_user.team_id = team.id")
-	}
 	db.SetSessionPagination(sess, opts)

 	teams := make([]*Team, 0, opts.PageSize)
-	count, err := sess.Where(cond).OrderBy("CASE WHEN name=? THEN '' ELSE lower_name END", OwnerTeamName).FindAndCount(&teams)
+	count, err := sess.OrderBy("CASE WHEN name=? THEN '' ELSE lower_name END", OwnerTeamName).FindAndCount(&teams)
 	if err != nil {
 		return nil, 0, err
 	}
--- a/models/organization/team_test.go
+++ b/models/organization/team_test.go
@@ -10,6 +10,8 @@ import (
 	"gitea.dev/models/organization"
 	repo_model "gitea.dev/models/repo"
 	"gitea.dev/models/unittest"
+	user_model "gitea.dev/models/user"
+	"gitea.dev/modules/structs"

 	"github.com/stretchr/testify/assert"
 )
@@ -38,6 +40,43 @@ func TestTeam_IsMember(t *testing.T) {
 	assert.False(t, team.IsMember(t.Context(), unittest.NonexistentID))
 }

+func TestTeam_CanNonMemberReadMeta(t *testing.T) {
+	assert.NoError(t, unittest.PrepareTestDatabase())
+
+	org3 := unittest.AssertExistsAndLoadBean(t, &user_model.User{ID: 3})     // public org
+	org35 := unittest.AssertExistsAndLoadBean(t, &user_model.User{ID: 35})   // private org
+	member := unittest.AssertExistsAndLoadBean(t, &user_model.User{ID: 2})   // member of org 3 and org 35
+	outsider := unittest.AssertExistsAndLoadBean(t, &user_model.User{ID: 5}) // member of neither org
+
+	test := func(name string, team *organization.Team, org, doer *user_model.User, expected bool) {
+		t.Run(name, func(t *testing.T) {
+			ok, err := team.CanNonMemberReadMeta(t.Context(), org, doer)
+			assert.NoError(t, err)
+			assert.Equal(t, expected, ok)
+		})
+	}
+
+	// Public team is gated only by the parent org's visibility.
+	publicTeam := &organization.Team{OrgID: 3, Visibility: structs.VisibleTypePublic}
+	test("public team, public org, member", publicTeam, org3, member, true)
+	test("public team, public org, outsider", publicTeam, org3, outsider, true)
+
+	// Public team inside a private org: only org members may see it.
+	publicTeamPrivOrg := &organization.Team{OrgID: 35, Visibility: structs.VisibleTypePublic}
+	test("public team, private org, org member", publicTeamPrivOrg, org35, member, true)
+	test("public team, private org, outsider", publicTeamPrivOrg, org35, outsider, false)
+
+	// Limited team: any org member, but never outsiders.
+	limitedTeam := &organization.Team{OrgID: 3, Visibility: structs.VisibleTypeLimited}
+	test("limited team, org member", limitedTeam, org3, member, true)
+	test("limited team, outsider", limitedTeam, org3, outsider, false)
+
+	// Private team is never visible to non-members; members/owners are admitted by the caller.
+	privateTeam := &organization.Team{OrgID: 3, Visibility: structs.VisibleTypePrivate}
+	test("private team, org member", privateTeam, org3, member, false)
+	test("private team, outsider", privateTeam, org3, outsider, false)
+}
+
 func TestTeam_GetRepositories(t *testing.T) {
 	assert.NoError(t, unittest.PrepareTestDatabase())

@@ -172,6 +211,52 @@ func TestGetUserOrgTeams(t *testing.T) {
 	test(3, unittest.NonexistentID)
 }

+func TestSearchTeamIncludeVisible(t *testing.T) {
+	assert.NoError(t, unittest.PrepareTestDatabase())
+
+	const orgID int64 = 3
+	// User 5 is an org member but only belongs to team 1 (Owners) — make sure
+	// they don't see team 2 (default private) but do see a freshly added
+	// limited team they are not a member of.
+	visible := &organization.Team{
+		OrgID:      orgID,
+		LowerName:  "visible-team",
+		Name:       "visible-team",
+		AccessMode: 1, // read
+		Visibility: structs.VisibleTypeLimited,
+	}
+	assert.NoError(t, db.Insert(t.Context(), visible))
+	teams, _, err := organization.SearchTeam(t.Context(), &organization.SearchTeamOptions{
+		OrgID:               orgID,
+		UserID:              2,
+		IncludeVisibilities: organization.VisibleTeamVisibilitiesFor(true, true),
+	})
+	assert.NoError(t, err)
+	ids := make(map[int64]bool, len(teams))
+	for _, team := range teams {
+		assert.Equal(t, orgID, team.OrgID)
+		ids[team.ID] = true
+	}
+	// user 2 is in team 1 and team 2 in org 3, plus should see the new visible team.
+	assert.True(t, ids[1], "expected to see team 1 (member)")
+	assert.True(t, ids[2], "expected to see team 2 (member)")
+	assert.True(t, ids[visible.ID], "expected to see visible team")
+
+	// user 5 is only an org member in team 1, must not see secret team 2 but must see the visible one.
+	teams, _, err = organization.SearchTeam(t.Context(), &organization.SearchTeamOptions{
+		OrgID:               orgID,
+		UserID:              5,
+		IncludeVisibilities: organization.VisibleTeamVisibilitiesFor(true, true),
+	})
+	assert.NoError(t, err)
+	ids = make(map[int64]bool, len(teams))
+	for _, team := range teams {
+		ids[team.ID] = true
+	}
+	assert.False(t, ids[2], "user 5 must not see private team 2")
+	assert.True(t, ids[visible.ID], "user 5 must see the limited team")
+}
+
 func TestHasTeamRepo(t *testing.T) {
 	assert.NoError(t, unittest.PrepareTestDatabase())

--- a/models/repo/repo_list.go
+++ b/models/repo/repo_list.go
@@ -783,7 +783,8 @@ func GetUserRepositories(ctx context.Context, opts SearchRepoOptions) (Repositor

 	sess = sess.Where(cond).OrderBy(opts.OrderBy.String())
 	repos := make(RepositoryList, 0, opts.PageSize)
-	return repos, count, db.SetSessionPagination(sess, &opts).Find(&repos)
+	db.SetSessionPagination(sess, &opts)
+	return repos, count, sess.Find(&repos)
 }

 func GetOwnerRepositoriesByIDs(ctx context.Context, ownerID int64, repoIDs []int64) (RepositoryList, error) {