Build and release permissions and roles (Security)

VSTS | TFS 2018 | TFS 2017 | TFS 2015

Note

Build and release pipelines are called definitions in TFS 2018 and in older versions. Service connections are called service endpoints in TFS 2018 and in older versions.

To support security of your build and release operations, you can add users to a built-in security group, set individual permissions for a user or group, or add users to pre-defined roles. You manage security for the following objects from the Build and Release hub of the web portal, either from the user or admin context.

This topic provides a description of the permissions and roles used to secure operations. To learn how to set permissions or add a user or group to a role, see Set build and release permissions.

For permissions, you grant or restrict permissions by setting the permission state to Allow or Deny, either for a security group or an individual user. For a role, you add a user or group to the role. To learn more about how permissions are set, including inheritance, see About permissions and groups. To learn how inheritance is supported for role-based membership, see About security roles.

Default permissions assigned to built-in security groups

Once you have been added as a team member, you are a member of the Contributors group. This allows you to define and manage builds and releases. The most common built-in groups include Readers, Contributors, and Project Administrators. These groups are assigned the default permissions as listed below.

Task Stakeholders Readers Contributors Build
Admins
Account Owner/
Project Admins
Release Admins
View build and release pipelines checkmark checkmark checkmark checkmark checkmark
Define builds with continuous integration checkmark checkmark checkmark
Define releases, manage deployments, manage releases with Release Management checkmark checkmark checkmark
Approve releases checkmark checkmark checkmark checkmark
Package Management (5 users free) checkmark checkmark checkmark
Queue builds, edit build quality checkmark checkmark checkmark
Manage build queues and build qualities checkmark checkmark
Manage build retention policies, delete and destroy builds checkmark checkmark checkmark
Administer build permissions checkmark checkmark
Manage release permissions checkmark checkmark
Create and edit task groups checkmark checkmark checkmark checkmark
Manage task group permissions checkmark checkmark checkmark
Can view library items such as variable groups checkmark checkmark checkmark checkmark checkmark
Use and manage library items such as variable groups checkmark checkmark checkmark

Security of agents and library entities

You use pre-defined roles and manage membership in those roles to configure security on agent pools and queues. You can configure this in a hierarchical manner either for all pools and queues, or for an individual pool or queue.

Roles are also defined to help you configure security on shared library entities such as variable groups and service connection. Membership of these roles can be configured hierarchically, as well as at either project level or individual entity level.

Build permissions

Permissions in Build follow a hierarchical model. Defaults for all the permissions can be set at the project level and can be overridden on an individual build pipeline.

To set the permissions at project level for all build pipelines in a project, choose Security from the action bar on the main page of Builds hub.

To set or override the permissions for a specific build pipeline, choose Security from the context menu of the build pipeline.

The following permissions are defined in Build. All of these can be set at both the levels.

Permission Description
Administer build permissions Can change any of the other permissions listed here.
Queue builds Can queue new builds.
Delete build pipeline Can delete build pipeline(s).
Delete builds Can delete builds for a pipeline. Builds that are deleted are retained in the Deleted tab for a period of time before they are destroyed.
Destroy builds Can delete builds from the Deleted tab.
Edit build pipeline Can save any changes to a build pipeline, including configuration variables, triggers, repositories, and retention policy.
Edit build quality Can add tags to a build.
Override check-in validation by build Applies to TFVC gated check-in builds. This does not apply to PR builds.
Retain indefinitely Can toggle the retain indefinitely flag on a build.
Stop builds Can stop builds queued by other team members or by the system.
View build pipeline Can view build pipeline(s).
View builds Can view builds belonging to build pipeline(s).
Update build information It is recommended to leave this alone. It's intended to enable service accounts, not team members.
Manage build qualities Only applies to XAML builds
Manage build queue Only applies to XAML builds

Default values for all of these permissions are set for team project collections and project groups. For example, Project Collection Administrators, Project Administrators, and Release Administrators are given all of the above permissions by default. Contributors are given all permissions except Administer release permissions. Readers, by default, are denied all permissions except View release pipeline and View releases.

When it comes to security, there are different best practices and levels of permissiveness. While there's no one right way to handle permissions, we hope these examples help you empower your team to work securely with builds.

  • By default, contributors in a project cannot create or edit build pipelines. To grant permissions to work on build pipelines, select Contributors and set the Edit build pipeline permission to Allow.

  • In many cases you probably also want to set Delete build pipeline to Allow. Otherwise these team members can't delete even their own build pipelines.

  • Without Delete builds permission, users cannot delete even their own completed builds. However, keep in mind that they can automatically delete old unneeded builds using retention policies.

  • We recommend that you do not grant these permissions directly to a person. A better practice is to add the person to the build administrator group or another group, and manage permissions on that group.

Release permissions

Permissions in Release Management follow a hierarchical model. Defaults for all the permissions can be set at the project level and can be overridden on an individual release pipeline. Some of the permissions can also be overridden on a specific environment within a pipeline. The hierarchical model helps you define default permissions for all definitions at one extreme, and to lock down the production environment for an application at the other extreme.

To set permissions at project level for all release definitions in a project, open the shortcut menu from the drop-down list icon next to All release pipelines and choose Security.

To set or override the permissions for a specific release pipeline, open the shortcut menu from the drop-down list icon next to that pipeline name. Then choose Security to open the Permissions dialog.

To specify security settings for individual environments in a release pipeline, open the Permissions dialog by choosing Security on the shortcut menu that opens from the ellipses (...) on an environment in the release pipeline editor.

The following permissions are defined in Release Management. The scope column explains whether the permission can be set at the project, release pipeline, or environment level.

Permission Description Scopes
Administer release permissions Can change any of the other permissions listed here. Project, Release pipeline, Environment
Create releases Can create new releases. Project, Release pipeline
Delete release pipeline Can delete release pipeline(s). Project, Release pipeline
Delete release environment Can delete environment(s) in release pipeline(s). Project, Release pipeline, Environment
Delete releases Can delete releases for a pipeline. Project, Release pipeline
Edit release pipeline Can save any changes to a release pipeline, including configuration variables, triggers, artifacts, and retention policy as well as configuration within an environment of the release pipeline. To make changes to a specific environment in a release pipeline, the user also needs Edit release environment permission. Project, Release pipeline
Edit release environment Can edit environment(s) in release pipeline(s). To save the changes to the release pipeline, the user also needs Edit release pipeline permission. This permission also controls whether a user can edit the configuration inside the environment of a specific release instance. The user also needs Manage releases permission to save the modified release. Project, Release pipeline, Environment
Manage deployments Can initiate a direct deployment of a release to an environment. This permission is only for direct deployments that are manually initiated by selecting the Deploy or Redeploy actions in a release. If the condition on an environment is set to any type of automatic deployment, the system automatically initiates deployment without checking the permission of the user that created the release. Project, Release pipeline, Environment
Manage release approvers Can add or edit approvers for environment(s) in release pipeline(s). This permissions also controls whether a user can edit the approvers inside the environment of a specific release instance. Project, Release pipeline, Environment
Manage releases Can edit the configuration in releases. To edit the configuration of a specific environment in a release instance, the user also needs Edit release environment permission. Project, Release pipeline
View release pipeline Can view release pipeline(s). Project, Release pipeline
View releases Can view releases belonging to release pipeline(s). Project, Release pipeline

Default values for all of these permissions are set for team project collections and project groups. For example, Project Collection Administrators, Project Administrators, and Release Administrators are given all of the above permissions by default. Contributors are given all permissions except Administer release permissions. Readers, by default, are denied all permissions except View release pipeline and View releases.

Task group permissions

Task group permissions follow a hierarchical model. Defaults for all the permissions can be set at the project level and can be overridden on an individual task group pipeline.

You use task groups to encapsulate a sequence of tasks already defined in a build or a release pipeline into a single reusable task. You define and manage task groups in the Task groups tab of the Build and Release hub.

Permission Description
Administer task group permissions Can add and remove users or groups to task group security.
Delete task group Can delete a task group.
Edit task group Can create, modify, or delete a task group.

Library roles and permissions

Permissions for library artifacts, such as variable groups and secure files, are managed by roles. You use a variable group to store values that you want to make available across multiple build and release pipelines. You define and manage variable groups and secure files in the Library tab of the Build and Release hub.

Role Description
Administrator Can use and manage library items.
Reader Can only read library items.
User Can use library items, but not manage them.

Service connection security roles

You add users to the following roles from the project-level admin context, Services page. To create and manage these resources, see Service connections for build and release.

Role Description
User Can use the endpoint when authoring build or release pipelines.
Administrator Can manage membership of all other roles for the service connection as well as use the endpoint to author build or release pipelines. The system automatically adds the user that created the service connection to the Administrator role for that pool.

Deployment pool security roles

You add users to the following roles from the collection-level admin context, Deployment Pools page. To create and manage deployment pools, see Deployment groups.

Role Description
Reader Can only view deployment pools.
Service Account Can view agents, create sessions, and listen for jobs from the agent pool.
User Can view and use the deployment pool for creating deployment groups.
Administrator Can administer, manage, view and use deployment pools.