Set permissions at the project- or collection-level

Azure DevOps Services | Azure DevOps Server 2020 | Azure DevOps Server 2019 | TFS 2018 - TFS 2013

Several permissions are set at the project or at the organization/project collection level. You can grant these permissions by adding a user or group to one of the default security groups listed here. Or, you can create a custom security group within a level and add members to that group. You can then change the default permission settings.

An organization is the container for several projects that share resources. For more information about projects and project collections, see Plan your organizational structure.

A project collection is the container for several projects that share resources. For more information about projects and project collections, see About projects and scaling your organization.

Project level Organization/Collection level
- Build Administrators
- Contributors
- Project Administrators
- Project Valid Users
- Readers
- Release Administrators
- TeamName Team
- Project Collection Administrators
- Project Collection Build Administrators
- Project Collection Build Service Accounts
- Project Collection Proxy Service Accounts
- Project Collection Service Accounts
- Project Collection Test Service Accounts
- Project Collection Valid Users
- Security Service Group

Note

The above list indicates the latest groups defined for Azure DevOps and TFS 2017 and later versions. For earlier versions of TFS, the list may differ. Only add service accounts to TFS service account groups. To understand valid user groups, see About security, membership, and permissions; Valid user groups.

For a description of each group and each permission, see Permissions and groups reference, Groups.

Tip

For users tasked with managing project-level features —such as, teams, area and iteration paths, repositories, service hooks, and service end points—add them to the Project Administrators group. For users tasked with managing organization or collection-level features —such as, projects, policies, processes, retention policies, agent and deployment pools, and extensions—add them to the Project Collection Administrators group. To learn more, see About user, team, project, and organization-level settings.

Prerequisites

  • You must be a member of a project. If you don't have a project yet, create one in Azure DevOps. If you haven't been added as a team member, get added now.
  • You must be a member of a project. If you don't have a project yet, create one in an on-premises TFS. If you haven't been added as a team member, get added now.
  • To manage permissions or groups at the project level, you must be a member of the Project Administrators Group. If you created the project, you are automatically added as a member of this group.
  • To manage permissions or groups at the collection or instance level, you must be a member of the Project Collection Administrators Group. If you created the organization or collection, you are automatically added as a member of this group.

Add a user or group to a security group

As roles and responsibilities change, you might need to change the permission levels for individual members of a project. The easiest way to do that is to add the user or a group of users to a pre-defined security group. If roles change, you can then remove the user from a group.

Here we show how to add a user to the built-in Project Administrators group. The method is similar to adding an Azure Active Directory or Active Directory group.

Note

To enable the new user interface for the Project Permissions Settings Page, see Enable preview features.

  1. Open the web portal and choose the project where you want to add users or groups. To choose another project, see Switch project, repository, team.

  2. Choose Project settings and then Permissions.

    Choose Project settings, and then Permissions

  3. Choose Project Administrators group, Members, and then Add.

    Project Settings > Permissions, Add member

  4. Enter the name of the user account into the text box and then select from the match that appears. You can enter several identities recognized by the system into the Add users and/or groups box. The system automatically searches for matches. Choose the matches that meet your choices.

    Add users and group dialog, preview page.

    Note

    Users that have limited access, such as Stakeholders, won't be able to access select features even if granted permissions to those features. To learn more, see Permissions and access.

  5. Choose Save.

  1. Open the web portal and choose the project where you want to add users or groups. To choose another project, see Switch project, repository, team.

  2. Choose Project Settings and then Security.

    To see the full image, click to expand.

    Project Settings>Security

  3. Choose Project Administrators group, Members, and then Add.

    Project Settings>Security, Add member

  4. Enter the name of the user account into the text box. You can enter several identities into the text box, separated by commas. The system automatically searches for matches. Choose the match(es) that meets your choice.

    Add users and group dialog, on-premises.

    Note

    Users that have limited access, such as Stakeholders, won't be able to access select features even if granted permissions to those features. To learn more, see Permissions and access.

  5. Choose Save changes. Choose the refresh icon to see the additions.

  1. Open the web portal and choose the project where you want to add users or groups. To choose another project, see Switch project, repository, team.

  2. Choose the gear icon to open the administrative context.

    Open Project Settings, horizontal nav

  3. Choose Security, Project Administrators group, Members, and then Add.

    Project Settings>Security, Add member

  4. Enter the name of the user account into the text box. You can enter several identities into the text box, separated by commas. The system automatically searches for matches. Choose the match(es) that meets your choice.

    Add users and group dialog, TFS 2018 and earlier versions.

    Note

    Users that have limited access, such as Stakeholders, won't be able to access select features even if granted permissions to those features. To learn more, see Permissions and access.

  5. Choose Save changes. Choose the refresh icon to see the additions.

Remove a user or a group

  1. To remove a user or group from a security group, choose the More actions icon, and then Remove.

    Screenshot of Remove a user, cloud version.

  2. Choose Delete to confirm removal of the group member.

    Remove user confirmation dialog, cloud version.

  1. To remove a user from a group, choose Remove next to the user's name that you want to remove.

    !Remove user confirmation dialog, on-premises versions.](media/project-collection/remove-admin-member-server.png)

Change the permission level for a project-level group

Note

To enable the new user interface for the Project Permissions Settings Page, see Enable preview features.

  1. From the Permissions page, choose the group whose permissions you want to change.

    For example, here we grant permission to the Contributors group to Delete and restore work items.

    Screenshot of Contributors group, permissions, preview page.

    Your changes are automatically saved.

    Tip

    In general, if you add a user to the Contributors group, they can add and modify work items. You can restrict permissions of users or user groups to add and modify work items based on the area path. For details, see Set permissions and access for work tracking, Modify work items under an area path.

    For a description of each permission, see Permissions and groups reference, project-level permissions.

    Note

    You can't change the permission settings for the Project Administrators group. This is by design.

  1. From the Security page, choose the group whose permissions you want to change.

    For example, here we grant permission to the Contributors group to delete and restore work items.

    Screenshot of Contributors group, permissions, on-premises versions.

    Tip

    In general, if you add a user to the Contributors group, they can add and modify work items. You can restrict permissions of users or user groups to add and modify work items based on the area path. For details, see Set permissions and access for work tracking, Modify work items under an area path.

    For a description of each permission, see Permissions and groups reference, project-level permissions.

    Note

    You can't change the permission settings for the Project Administrators group. This is by design.

  2. Choose Save changes.

Add a group and change its permissions at the organization or collection-level group

Note

To enable the new user interface for the Organization Permissions Settings Page v2, see Enable preview features. The preview page provides a group settings page that the current page does not.

  1. From your project web portal, choose the Azure DevOps icon, and then select gear icon Organization settings.

    Open Organization settings

  2. Under Security, choose Permissions, and then choose New group to open the dialog for adding a group.

    Create security group at the organization-level

  3. Enter a name for the group, members of the group, and optionally a description.

    For example, here we define a Work Tracking Administrators group.

    Security group dialog, Add a security group at the organization-level

    Choose Create.

  4. Choose the group name you just created and change the permission levels. For a description of each permission, see Permissions and groups reference, Collection-level permissions.

    Here we grant this group permissions to manage customizations for the Inheritance process model.

    Create Custom group dialog, cloud version.

    Your changes are automatically saved.

    Note

    You can't change the permission settings for the Project Collection Administrators group. This is by design.

  1. From your project web portal, choose the Azure DevOps icon, and then select gear icon Organization settings.

    Open Collection settings, on-premises versions.

  2. Choose Security, and then choose Create group to open the dialog for adding a group.

    Create security group at the collection-level

  3. Enter a name for the group, and optionally a description.

    For example, here we define a Work Tracking Administrators group.
    Security group dialog, Add a security group at the organization or collection level
    For a description of each permission, see Permissions and groups reference, collection-level permissions.

  4. Choose the group name you just created and change the permission levels.

    Here we grant this group permissions to manage customizations for the Inheritance process model.

    Screenshot of Custom group, change permissions, on-premises versions.

  5. Choose Save changes.

    Note

    You can't change the permission settings for the Project Collection Administrators group. This is by design.

  1. Choose the settings icon and select Organization settings (Azure DevOps) or Collection settings (on-premises).

    Screenshot of Open Collection Settings, TFS-2018 and earlier versions.

  2. Choose Security, and then choose Create group to open the dialog for adding a group.

    Create security group at the collection-level, TFS-2018 and earlier versions.

  3. Enter a name for the group, and optionally a description.

    For example, here we define a Work Tracking Administrators group.
    Security group dialog, Add a security group at the organization or collection level
    For a description of each permission, see Permissions and groups reference, collection-level permissions.

  4. Choose the group name you just created and change the permission levels.

    Here we grant this group permissions to manage customizations for the Inheritance process model.

    Screenshot of Custom group, change permissions, TFS-2018 and earlier versions.

  5. Choose Save changes.

    Note

    You can't change the permission settings for the Project Collection Administrators group. This is by design.

Manage group settings

Note

To enable the new user interface for the Project Permissions Settings Page or the Organization Permissions Settings Page v2, see Enable preview features. Both preview pages provide a group settings page that the current page does not.

You can change a group description, add a group image, or delete a group through the group Settings page.

From the Project > Settings > Permissions or Organization > Settings > Permissions page, choose the group you want to manage, and then choose Settings.

For example, here we open the Settings for the Work Tracking Administrators group.

Screenshot of Open group settings, preview page.

You can modify the group name, group description, upload an image, or delete the group.


You can change a group name, description, add a group image, or delete a group.

  1. From the Project > Settings > Security or Organization > Settings > Security page, choose the group you want to manage

  2. Choose from the Edit menu to either Edit profile or Delete.

    For example, here we open the Edit profile for the Stakeholder Access group.

    Open Edit group profile, on-premises versions.

    . . . and change the description. Note that you can change the name of the group as well.

    Edit group dialog profile description, on-premises versions.

  3. Choose Save to save your changes.

On-premises deployments

For on-premises deployments, see these additional topics:

If your on-premises deployment is integrated with SQL Server Reports, you'll need to manage membership for those products separately from their websites. See Grant permissions to view or create SQL Server reports in TFS.

If your on-premises deployment is integrated with a SharePoint product or SQL Server Reports, you'll need to manage membership for those products separately from their websites.

FAQs

Q: When do I need to add someone to the Project Collection Administrator role?

A: It varies. For most organizations that use Azure DevOps, Project Collection Administrators manage the collections that members of the Team Foundation Administrators group create. Members of the Project Collection Administrators group don't create the collections themselves. Project collection administrators also do many operations required to maintain the collection. Operations include creating team projects, adding users to groups, modifying the settings for the collection, and so on.

Q: What are the optimal permissions to administer a project collection across all of its components and dependencies?

A: Project collection administrators must be members of the following groups or have the following permissions:

  • Team Foundation Server: A member of the Project Collection Administrators group, or have the appropriate collection-level permissions set to Allow.

  • SharePoint Products: If the collection is configured with a site collection resource, then a member of the Site Collection Administrators group.

  • Reporting Services: If the collection is configured with reporting resources, then a member of the Team Foundation Content Manager group.

Q: I'm an admin, but I don't have permission to add a Project Collection Administrator. What do I need?

A: The following permissions are required:

  • You must be a Project Collection Administrator, or your View Server-Level Information and Edit Server-Level Information permissions must be set to Allow.

  • To add permissions for SharePoint Products, you must be a member of the Site Collection Administrators or Farm Administrators groups for SharePoint Products.

  • To add permissions for Reporting Services, you must be a member of the Content Managers or Team Foundation Content Managers groups for Reporting Services.

Important

To perform administrative tasks like creating project collections, your user requires administrative permissions. The service account that the Team Foundation Background Job Agent uses must have certain permissions granted to it. For more information, see Service accounts and dependencies in Team Foundation Server and Team Foundation Background Job Agent.

Q: Where can I find information about each individual permission?

A: You can find detailed information about individual permissions and their relationship to default security groups in the Permission and groups reference. To give a user project administration permission, complete the following steps:

  1. From the team page, select the settings icon Settings icon to go to the team administration page.

  2. Add the user to the Project Administrators group.

Next steps