Continuous Integration with Visual Studio Team Services

Visual Studio Team Services (VSTS) has a lot to offer and in most cases completely free for small teams. If it is being used for source control then it is easy to set up Continuous Builds.

This article assumes you have a VSTS account setup already and it is being used as a source control repository.

Generate PAK code for agent authentication

First you need to generate a PAK code for authentication this is done via VSTS by going to the my account section -> security or

https://{myaccount}.visualstudio.com/DefaultCollection/_details/security/tokens
  • Click Add and enter a suitable name.
  • Select the duration for the token for 90/180 days or a year.
  • Under Authorization Scopes select Agent Pools (read,manage) and Deployment group (read, manage).
  • Click on Create Token and take a note of the key, note this key will not be visible again.

For more details on setting up permissions see the following:

https://docs.microsoft.com/en-us/vsts/build-release/actions/agents/prepare-permissions

Download and Configure Build Agent

Next step is to download and configure an agent on VSTS by this path 

https://{myaccount}.visualstudio.com/DefaultCollection/_admin/_AgentPool

Then click on the Download Agent button

This will download a zip file which you can unpack to a suitable location, there is no installation required just some configuration.

Open a command  prompt and run the config.cmd as admin in the directory the zip file was extracted to.

This command will setup the agent as a service for VSTS 

config.cmd --unattended --url https://{myaccount}.visualstudio.com --auth pat --token {mytoken} --pool default --agent {agentname} --acceptTeeEula --runAsService

You will need to replace the url token and agent name parts, the agent name is just an identifier which usually default to machine name. The runAsService flag ensures that the agent will be setup as a windows service usually with the following naming convention:

VSTS Agent (username.agentname)

The full list of options can be found under config.cmd /? or by going to https://docs.microsoft.com/en-us/vsts/build-release/actions/agents/v2-windows

Once configured it cannot be edited so you need to run the remove command to make any changes by running the remove command. You will need your token again to remove.

config.cmd remove

The remove command also removes the agent registration from VSTS so it needs to be run, simply removing the agent files locally and trying to reconfigure will not work.

Setup a Build Definition

Once the agent is installed you need to create a build definition in VSTS by going to the Builds menu or

https://{myaccount}.visualstudio.com/DefaultCollection/AML/_build
  • Click on New
  • Select the Source this will be This account
  • Select the Project and Repository this will then allow a workspace mapping to be setup
  • Click continue then select a template, this is probably the easiest option to begin with in this case we are using the ASP.NET template

In the next screen ensure the Private default queue is selected for agent queue.

In the left hand pane the steps are displayed depending on your build these may not all be required.

The build definition has a number of options for when a build is triggered. We want a continuous build i.e build whenever there is a code change so this is done via the Triggers tab in the build definition.

Select Enable continuous integration, here you can specify what triggers the build, either by monitoring your entire workspace or by selecting specific folders, this is handy if a project has dependencies on other projects on separate workspace paths.

Troubleshooting

You may get this error on second build in the Get Source task

TF400017: The workspace properties table for the local workspace... Project Collection Build Service (...) could not be opened. Access is denied

This is just an issue with the permissions which can be solved by ensuring the permissions are correct in

https://{myaccount}.visualstudio.com/DefaultCollection/_admin/_security

Make sure the Project Collection Build Service Accounts have the Administer workspaces permission

For more complex solutions you may need some additional steps in the build definition. For example if you have multiple projects in a solution then you need to first ensure that all referenced projects are mapped in the workspaces section of the build definition.

If you have more than one solution file present you may need to tell the build which one to use, by default it looks in the main directory. This will be locked normally but you can unlink the path and specify your own.

For nuget package references these need to be referencing the packages folder that is mapped to the workspace, and not some other location on your machine. Otherwise the build will fail to pull in the referenced libraries when building in the agent context.