Managing Roles and Permissions
User access levels in TeamCity are handled by assigning different roles to users thus granting them respective permissions.
A permission is an authorization to perform particular operations, for example, to run a build or modify build configuration settings.
A role is a set of permissions that can be granted to a user in one or all projects thus controlling access to the projects and various features in the UI.
Authorization Mode
TeamCity authorization supports two modes: simple and per-project.
In the simple mode, there are only three types of authorization levels: guest, logged-in user, and administrator.
In the per-project mode, you can assign users roles in projects or server-wide. The set of permissions in roles is editable.
Permissions within a role granted at the project level are automatically propagated in all the subprojects of this project.
The View project and all parent projects permission allows viewing not only the project (with its subprojects) but its parent projects too.
Changing Authorization Mode
Unless explicitly configured, the simple authorization mode is used in TeamCity Professional and per-project is used in TeamCity Enterprise.
To change the authorization mode, go to Administration | Authentication and enable/disable the Enable per-project permissions option.
Simple Authorization Mode
Role | Description |
|---|---|
Administrator | User with no restrictions; corresponds to the System Administrator role in the per-project authorization mode. |
Logged-in user | Corresponds to the default Project Developer role granted for all projects in the per-project authorization mode. |
Guest user | Corresponds to the default Project Viewer role granted for all projects in the per-project authorization mode. |
Per-Project Authorization Mode
Roles are assigned to users by administrators on a per-project basis: a user can have different roles in different projects, and hence, the permissions are project-based. A user can have a role in a specific project or in all available projects, or no roles at all. You can associate a user account with a set of roles. A role can also be granted to a user group. This means that the role is automatically granted to all the users that are included into the group (both directly or through other groups).
You can add roles and assign permissions to them in Administration | Roles. Click Add permission under any role to see the list of all available permissions, select a required permission, and click Add. To add multiple permissions, hold the CTRL key when selecting them.
By default, TeamCity provides the following per-project roles:
Role | Description |
|---|---|
System Administrator | Has no restrictions in permissions, and has all of the Project Administrator's permissions. Сan create and manage user accounts, change HTTPS settings, authorize build agents, set up projects and build configurations, edit the TeamCity server settings, manage TeamCity licenses, configure server data clean-up rules, change VCS roots, and so on. |
Project Administrator | Can customize general settings of a project and settings of build configurations, assign roles to the project users, create subprojects, change a user's VCS username in the project without adding the permission to modify user profile and roles. Has all the Project Developer's permissions. With the enabled "Change user / group notification rules in project" permission, can edit notification rules for users and user groups assigned to their projects. |
Project developer | Usually commits changes to a project. Can start/stop builds, reorder builds in the build queue, label the build sources, review agent details, start investigation of a failed build. Note that by default this role has the Customize build parameters and Change build source code with a custom patch permissions. This could give indirect access to altering a configuration/environment per build (see more details). |
Project Viewer | Has read-only access to projects and can only view the project, its parent, and subprojects. Does not have permissions to view agent details. |
Agent manager | Can customize and manage Build Agents, change the run configuration policy, enable/disable build agents, and pause/resume build queue. |
When per-project permissions are enabled, server administrators can modify the roles, delete them, or add new roles with any combination of permissions right in the TeamCity Administration web UI, or by modifying the roles-config.xml file stored in the <TeamCity Data Directory>/config directory. When assigning roles to users, the View role permissions link in the web UI displays the list of permissions for each role in accordance with their current configuration.
Project-level Agent Management Permissions
TeamCity has the following project-level permissions to perform a task on an agent:
Enable/disable agents associated with project
Start/Stop cloud agent for project
Change agent run configuration policy for project
Administer project agent machines (for example, reboot, view agent logs)
Remove project agent
Authorize project agent
All project-level agent management permissions are by default added to the Project Administrator role.
A user can perform a task controlled by one of these permissions on all the agents belonging to some pool provided this permission is granted to the user in all the projects associated with this pool. For example, a user with the "Enable/disable agents associated with project" permission granted in some projects can enable or disable agents which belong to the pools of the related projects if the permission is granted in all the projects associated with the pools.
Managing Roles
If per-project permissions are enabled in your installation, you can view the existing roles, modify them, and create new ones in the TeamCity UI — on the Administration | Roles page. It allows:
Creating new roles.
Deleting existing roles.
Adding/deleting permissions from existing roles.
Including/excluding permissions from a role.
Note that role settings are global.
Permission Inheritance
User permissions are shared from a parent project to its subprojects, and from a parent user group to child groups.
Project Inheritance
Suppose a project "Main" has two subprojects: "Project A" and "Project B". Each project has a corresponding user group:
The "Main Project Users" group grants its users the "Project administrator" role for project "Main".
"Group A" and "Group B" give their users the "Project viewer" role for corresponding child projects.
A user added to "Main Project Users" and "Group A" will have the "Project administrator" role in both child projects because this role is inherited from the "Main Project Users" group.
Group Inheritance
When you assign a role to a user group, all child groups of this group get the same permissions. On the Administration | Groups page, groups with inherited roles display the "N/M" counter under the "Roles" column. "N" is the number of roles assigned to this group directly, and "M" is the number of roles inherited from parent groups.
In the figure below, the "Tier 3" group has two roles inherited from its parent "Tier 1" and "Tier 2" groups. Since this group has no directly assigned roles, its counter is "0/2".
