Table of contents
TOC
Collapse the table of content
Expand the table of content

Administer your build and deployment system

Last Updated: 9/26/2016

Team Services | TFS 15 Preview | TFS 2015 | Previous versions (XAML builds)

Get an agent

To build your code or deploy your software you need at least one agent, and as you add more code and people, you'll eventually need more.

System capabilities

System capabilities are name/value pairs that you can use to ensure that your build definition is run only by agents that meet criteria specified by you. Environment variables automatically appear in the list. Some capabilities (such as frameworks) are also added automatically.

When a build is queued, the system sends the job only to agents that have the capabilities demanded by the build definition.

User capabilities

You can manually add capabilities (name/value pairs) that you know your agent has and that your want your build definition to be able to demand.

Agent pools and queues

You organize your agents into pools, and provide access to the pools using queues.

Agent pools

Use agent pools to organize and define permission boundaries around your agents. Pools are scoped to your Team Foundation Server application tier or Visual Studio Team Services (Team Services) account. You can share your pool across multiple team project collections.

You create and manage pools from the Agent pools control panel tab ▼

  • Team Services: https://{your_account}.visualstudio.com/_admin/_AgentPool
  • On-premises: http://{your_server}:8080/tfs/_admin/_AgentPool

manage project

New pool

When you create a new pool, in most cases you should leave Auto-provision queues in all projects selected. This setting ensures all collections have a queue to access the pool. The system creates a queue for existing collections and whenever a collection is created. You can modify this setting later (right-click the pool).

If you have sufficient permissions, you can control who can access and manage your agent pools.

To grant global permissions, select All Pools and then:

  • Add a user or a group and grant:

    • Administrator to enable them to create new pools, add agents to all existing pools, and grant permissions to other users and groups to do the same.

    • Reader to enable them to view all agent pools.

  • To delete a group or user, hover over it and click the Remove user icon.

To grant narrower permissions, select a specific agent pool (for example Default or Hosted, click Roles, and then:

  • Add a user or a group and grant Administrator or Reader.

  • To delete a group or user, hover over it and click the Remove user icon.

Click Save to implement your changes.

How does the agent authenticate and communicate with the TFS AT?

Queues

An agent queue provides access to a pool of agents. When you create a build or release definition, you specify which queue it uses. Queues are scoped to your team project collection, so you can share them across build and release definitions in multiple team projects.

You create and manage your queues from the Agent queues control panel tab ▼

  • Team Services https://{your-account}.visualstudio.com/{your-project}/_admin/_AgentQueue
  • On-premises http://{your-server}:8080/tfs/{your-project}/_admin/_AgentQueue

manage project

If you see the following view, click your team project.

control panel top to team project

control panel collection agent queues

If you have sufficient permissions, you can control who can access and manage your queues.

To grant global permissions, select All Queues and then:

  • Add a user or a group and grant:

    • Administrator to administer, manage, use, and view queues.

    • Creator to create and view queues.

    • User to view and use the queue when they define or queue a build.

    • Reader to view the queue.

  • To delete a group or user, hover over it and click the Remove user icon.

To grant narrower permissions, select a specific queue (for example Default (Default) or Hosted (Hosted) and then:

  • Add a user or a group and grant User or Administrator.

  • To delete a group or user, hover over it and click the Remove user icon.

Click Save to implement your changes.

Global retention policy settings

If you are using an on-premises Team Foundation Server, you can specify retention policy defaults and maximums for a team project collection. You can also specify when builds are permanently destroyed (removed from the Deleted tab in the build explorer).

If you are using Team Services, you can view but not change these settings.

Global retention policy settings are on the Build control panel tab ▼

  • Team Services: https://{your_account}.visualstudio.com/_admin/_BuildQueue
  • On-premises: http://{your_server}:8080/tfs/_admin/_buildQueue

manage project

control panel collection build

Administer permissions

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.

Check in to the team project

To do anything your team member needs access to your Team Services account. The most common way to grant permission is to make the person a member of your team:

  1. Browse to your team project Security tab.

    • Team Services: https://{your-account}.visualstudio.com/{your-project}/{your-project-team}/_admin/_security

    • On-premises: http://{your-server}:8080/tfs/DefaultCollection/{your-project}/_admin/_security

  2. Click Members and then add your team member.

  3. Click Contributors, and then Members and make sure your team is a member.

Your team members can now check in code. If your team project already has build definitions, then they can view those builds. If you've got automatically triggered builds such as a CI build, then their code gets built. The team can now also manually queue builds, and cancel their own builds.

Note: The above capabilities are allowed by default in a new team project. If your team project has been around for a while, then you might see different permissions allowed or denied because of changes made by the administrator.

Work with builds

After you've added people to the team, by default they do not have permission to create or edit build definitions. For example, when they try to save a build definition they'll get a 403: TF215002: Access denied. message.

Create and edit build definitions

To enable your team members to create and edit build definitions:

  1. Browse to the Build tab.

    • Team Services: https://{your-account}.visualstudio.com/{your-project}/_build

    • On-premises: http://{your-server}:8080/tfs/DefaultCollection/{your-project}/_build

  2. Click All Definitions.

  3. If you want to grant permissions to work on build definitions in all folders, then skip to the next step.

    However, if you prefer to limit your team to creating and editing builds in a specific folder:

    1. If the folder doesn't exist yet, create it.

    2. Open the folder.

    I tried to give contributors permission to create build definitions in a specific folder, but they're blocked. What went wrong?

  4. Click Security.

  5. Click Contributors.

  6. Set Edit build definition to Allow.

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

Use a queue

By default your Build Administrators are given the Administrator role in your agent queues. If you want other people to also be permitted to use the queue, you'll need to add them.

  1. Open the queues tab described above.

  2. Click the queue you want the team to use.

  3. Click Roles.

  4. If the user or group (for example, {your-project}\Contributors) is not already listed, click Add and then add them as either a User or an Administrator.

Do other things with builds

In the dialog box you used above, you might want to grant other kinds of permissions that team members don't get by default. Below are the other kinds of build permissions you can grant, listed roughly in order of impact:

  • Manage build qualities applies only to XAML builds.

  • Retain indefinitely. Enable someone to flag a build so that it won't be deleted by your retention policies.

  • Stop builds queued by other team members or by the system on their behalf.

  • Manage build queue applies only to XAML builds.

  • Override check-in validation by build applies to TFVC gated check-in builds. This does not apply to PR builds.

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

  • Destroy builds allows you to delete builds from the Deleted tab.

  • Administer build permissions enables people to grant the above permissions.

    We recommend that you do not grant this permission directly to a person. A better practice is to add the person to a build administrator group, described below.

Note: Update build information is also listed, but we recommend you leave this one alone. It's intended to enable service accounts, not team members.

Build administrators

To delegate the ability to grant the above permissions to others, add the person or group to either the:

  • Build Administrators group for the team project on the security tab for the team project.

  • Project Collection Build Administrators group (covers all team projects) on the security tab for the collection.

Q&A

How are agent pools and queues organized?

Build system architecture

How does the agent authenticate and communicate with the TFS AT?

The agent pool administrator role is needed only when you register an agent. At that time, the agent downloads an OAUth token so that it can listen to the queue. The account that you use in this role has no bearing on future communication between the agent and the TFS AT.

When a build is run, it generates an OAuth token for the scoped identity selected on the general tab of the build definition. That token is short lived and is used to access resources on the application tier.

I'm trying to create a queue that uses an existing pool, but the controls are grayed out. Why?

On the Create Queue dialog box, you can't use an existing pool if it is already referenced by another queue. Each pool can be referenced by only one queue within a given team project collection.

The TFS URLs don't work for me. How can I get the correct URL?

Web Site Settings and Security

I tried to give contributors permission to create build definitions in a specific folder, but they're blocked. What went wrong?

There's a known problem in which a TF215002 error prevents authorized users from creating build definitions. This problem occurs if they have Edit build definition permission for only a subfolder and not for the root folder. These users can edit existing definitions but can't create new ones. We're working on fixing it.

© 2016 Microsoft