User Groups

User groups provide a reusable, hierarchical way to grant access in Gitea Enterprise. Instead of adding the same users to every team or repository individually, administrators can define a group once, add members, and assign the group to organization teams or repositories.

User groups are available in Gitea Enterprise v26 and later. Repository collaborator user groups were added in Gitea Enterprise v27.

Enable user groups

1. Open Site Administration > User Groups.
2. Check Enable user groups.
3. Save the setting.

When user groups are enabled, the user-group management pages, LDAP user-group synchronization settings, team user-group sections, and repository collaborator controls are shown. Disabling the feature hides all user-group related UI and routes.

Create and manage groups

1. Open Site Administration > User Groups.
2. Click New User Group.
3. Enter a Name and, optionally, a Description.
4. Optionally choose a Parent group to build a hierarchy. A group can have more than one parent: on the edit page of the group, Also a child of adds further parents (choosing another parent there replaces all the parents of the group).
5. Leave Slug empty to derive it from the name, or enter a stable lowercase identifier using letters, numbers, dots, underscores, and hyphens.
6. Click Create Group.

From a group’s edit page you can:

• add or remove individual members
• create or view child groups
• review which organization teams and repositories use the group, or one of its ancestor groups (Teams Using an Ancestor Group, Repositories Using an Ancestor Group)

Group names are normalized when saved, so two names that differ only in case or surrounding spaces refer to the same group.

Hierarchy and effective members

User groups can be nested. A child group includes its own direct members and the effective members inherited from all of its parent groups. With several parents, a user that is a member of any parent is an effective member of the child. When a user group is assigned to a team or repository, all effective members of the group receive that access.

Assign groups to organization teams

1. Open the organization’s Teams page and select a team.
2. Open the User Groups section.
3. Click Add User Group and select one or more groups.

Members inherited through child user groups are included in the team. Removing a member from the source user group removes the access granted through that team.

Assign groups to repositories

Starting in Gitea Enterprise v27, repository administrators can assign user groups as repository collaborators:

1. Open Repository > Settings > Collaborators.
2. In the User Groups section, search for and add a user group.
3. Choose the access mode: read, write, or admin.

The selected group’s effective members receive that access on the repository, and the list of users behind a collaborator group can be shown on the same page. You can change or remove a repository user group from the same page. Site administrators can also open the user group page of a team.

Synchronize LDAP groups to user groups

User groups can be synchronized from an LDAP authentication source:

1. Open Site Administration > Identity & Access > Authentication Sources and edit the LDAP source.
2. Set LDAP Group Synchronization Mode to Synchronize groups to user groups.
3. Configure the group unique ID, name, description, parent detection strategy, and sync interval.
4. Save the authentication source, then choose Sync LDAP User Groups Now to run an initial synchronization.

The synchronization creates and updates user groups and their members from the directory. The last synchronization status is shown on the authentication source page.

Agents

When an agent restricts who may command it, the list of principals accepts user groups next to users and organization teams.

Performance

Starting with Gitea Enterprise v27.3.8, resolving and updating user group membership scales to large instances: organization membership is updated in batches, queries that touch many groups or users no longer hit database bind-parameter limits, and an LDAP synchronization reads every member of large Active Directory groups.

Availability

User groups were introduced in Gitea Enterprise v26. Repository collaborator user groups were added in Gitea Enterprise v27.