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

Administer your build and deployment system

Last Updated: 8/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

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

Q&A

How are agent pools and queues organized?

Build system architecture

How does security work for agent pools and queues?

The security model for agent pools and queues provides two groups that operate as roles instead of requiring you to manage specific permissions for different users. These groups are defined for each pool and queue created and are scoped as such. There are also groups defined at the account or server level that are automatically added to the pool level groups.

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.

Do I need a build agent?

You need at least one agent to run your build. Get an agent.

I can't select a default agent queue and I can't queue my build. How do I fix this?

See Administer queues.

I use Team Foundation Server on-premises and I don't see some of these features. Why not?

Some of these features are available only on Visual Studio Team Services and not yet available on-premises. Some features are available on-premises if you have upgraded to the latest version of TFS.

Where is the Visual Studio 2013 XAML build documentation?

Visual Studio 2013 XAML build documentation

© 2016 Microsoft