Lab Build agents – How it works

Note: Cross posted from Nothing geeky....


  • The Lab management end-to-end workflow works leverages the Team Foundation Build Agent/Build Controllers to do the deployment.

  • Given that build agent is primarily targeted for compiling sources, a getting-started user will get a bunch of questions :

  • a) How does the build agent inside a lab environment work ?

    b) Can I use the build agent inside the lab environment for both compiling sources and deploying my application ?

    c) How are the build agents selected for compiling sources ?

    Let me try to answer the above questions. And before that, take a look at our Getting started with Lab Management series and Lab management videos

  • How does the build agent inside a lab environment work ?

  • The build agent inside a lab environment also does the regular functionality of executing the tasks given by build controller. In the case of an end-to-end (E2E) workflow ( which is nothing but a build definition), the task done by the agent will be deployment ( any script that user specifies : WIX, MSI, batch file, ps …) instead of compiling sources.

  • If you have lab service account set for your project collection, then the build agent will use that identity while talking to TFS.

  • Example: If you have your build agent running as domain\user account in your VM and set your lab service account as domain\svcaccount, then any out going call made by the build agent to the TFS will go with this identity. As the name implies, lab service account will be a service account with less privileges and hence this account will not be granted permissions on source control by default.

  • Can I use the build agent inside the lab environment for both compiling sources and deploying ?

  • The recommended way is to have a separate build agent machine for compiling sources.

  • The reasons being :

  • Lab build agents (== build agents inside a lab environment) communicate with TFS using the lab service account identity which doesn’t have permissions on source control ( which is required for building sources). So this will not work out of box. Few manual steps has to be done in order to achieve this.

  • Lab machines that has to be in a clean state for deployment and might not have all the targets needed for compiling sources.

Example: To build a share point app and build a wsp package, the sharepoint target binaries are required on the build machine and it is not possible to have that in the lab environment ( since the VMs need to be clean before deployment).

How is the build agent selected for compiling sources ?

  • For running the E2E workflow, you will be creating a build definition for compiling sources. The default "Agent selection criteria" for this build definition will be "Agent which has any name and which doesn’t have tags ". The default " Tags is empty" criteria is to ensure that lab build agents are not picked up for compiling sources ( lab build agent always carries few custom tags that are pushed by lab and will not satisfy this criteria).


    If you have added tags to your non-lab build agents and just go with the default "Agent settings" options while creating the build definition, the tagged build agents will not be picked up for compilation and you might get an error which says "The build controller xxx does not contain an enabled build agent with name * and no tags".


    To workaround the issue, chose the tags explicitly while chose the agent for compiling sources (like below) or have separate build controllers - one for managing compilation agents and another for managing lab build agents.


    If you chose any of the lab build agents explicitly for compiling sources, then you will get an error saying "No matching items found in S/ in your workspace, or you do not have permissions to access them". This happens because the lab build agents will not have source control permission by default.


    You might get the above error, when "MatchAtleast" is chosen instead of "MatchExactly" in which case the lab build agents might also get picked up.

    How can I compile the sources using build agents inside the lab environment:

       Though the general recommendation is to not use the build agents inside the lab environment for compiling sources, you might have a scenario to do so. In that case you need to do the below steps to acheive this :

  •         Grant the lab service account "Read" permissions on the source control. By default when the a lab service account is set, it is denied source control permissions (to be "secure by default"). But, if you want your lab machines to compile sources then, the lab service account need to get the sources and hence it needs read permissions. This post explains how to give read permissions using "tf permisisons" command.
  •         While creating the compilation build definition, make sure that you either explictly chose the specific lab build agent or chose a tag or set some name filter so that the lab machines get chosen ( the reason being, by default lab machines will be excluded from the selection as mention above).

Hope this helps!