VSTS | TFS 2017 | TFS 2015 | Previous versions (XAML builds)
At the beginning of the build process, the build agent downloads the files from your remote repository into a local sources directory. After you select the repository, you can specify options for how the files are downloaded.
Git
VSTS, TFS 2017 Update 2, and newer: Click the Tasks tab, click Get sources, click This project, and then select the name of the Git repo.
TFS 2017 RTM and older: Click the Repository tab, and then for Repository type select Git.
Repository: Select a repository in your team project.
Branch (default): Select the branch that you want to be the default when you manually queue this build.
VSTS, TFS 2017 Update 2 or newer: Click Advanced settings to see the following options.
Clean:
If you set it to true, this command is run: git clean -fdx, git reset -hard HEAD
Set this to false if you want to define an incremental build to improve performance.
Tip: In this case, if you are building Visual Studio projects, on the Build tab, you can also uncheck the Clean check box of the Visual Studio Build or MSBuild step.
This setting has no effect if you are using a hosted agent.
Label sources: Select either On successful build or On every build if you want to label your source code files to enable your team to easily identify which version of each file is included in the completed build.
In the Label format you can use user-defined and predefined variables that have a scope of "All." For example:
$(Build.DefinitionName)_$(Build.DefinitionVersion)_$(Build.BuildId)_$(Build.BuildNumber)_$(My.Variable)
The first three variables are predefined. My.Variable is defined by you on the variables tab.
The build process labels your sources with a Git tag.
Note: Some build variables might yield a value that is not a valid label. For example variables such as $(Build.RequestedFor) and Build.DefinitionName can contain white space. If the value contains white space, the tag is not created.
Checkout submodules: Select if you want to download files from submodules.
Checkout files from LFS: Select if you want to download files from large file storage (LFS).
VSTS: Select the check box to enable this option.
TFS 2017 and TFS 2015 (OSX and Linux only): On the Variables tab, set Agent.Source.Git.Lfs to true.
Don't sync sources: Select the check box if you want to skip fetching new commits. This option can be useful in cases such as when you want to:
Git init, config, and fetch using your own custom options.
Use a build process to just run automation (for example some scripts) that do not depend on code in version control.
Shallow fetch: Select if you want to limit how far back in history to download. Effectively this results in git fetch --depth=n. If your repository is large, this option might make your build process more efficient. Your repository might be large if it has been in use for a long time. It also might be large if you added and later deleted large files.
In these cases this option can help you conserve network and storage resources. It might also save time. The reason it doesn't always save time is because in some situations the server might need to spend time calculating the commits to download.
VSTS: After you select the check box to enable this option, in the Depth box specify the number of commits.
TFS 2017 and TFS 2015 (OSX and Linux only): On the Variables tab, set Agent.Source.Git.ShallowFetchDepth to the number of commits in history you want to download. Specify 0 to set no limit.
Tip
If you're using VSTS, the above variables also work and override the check box controls. So for example, you can override the setting when you queue the build.
Team Foundation Version Control
VSTS, TFS 2017 Update 2, and newer: Click the Tasks tab, click Get sources, click This project, and then select the TFVC repo (for example,
$TeamProject).TFS 2017 RTM and older: Click the Repository tab, and then for Repository type the TFVC repo (for example,
$TeamProject).
Repository Ignore this option.
Mappings (workspace): Include with a type value of Map only the folders that your build process requires. If a subfolder of a mapped folder contains files that the build process does not require, map it with a type value of Cloak. When would I need to change TFVC mappings. How should I do it?
VSTS, TFS 2017 Update 2 or newer: Click Advanced settings to see the following options.
Label sources: Select either On successful build or On every build if you want to label your source code files to enable your team to easily identify which version of each file is included in the completed build.
In the Label format you can use user-defined and predefined variables that have a scope of "All." For example:
$(Build.DefinitionName)_$(Build.DefinitionVersion)_$(Build.BuildId)_$(Build.BuildNumber)_$(My.Variable)
The first three variables are predefined. My.Variable is defined by you on the variables tab.
The build process labels your sources with a TFVC label.
Clean:
If you set it to true, the build agent cleans the repo this way:
undo pending changes
scorch
Set this to false if you want to define an incremental build to improve performance.
Tip
In this case, if you are building Visual Studio projects, on the Build tab, you can also uncheck the Clean check box of the Visual Studio Build or MSBuild step.
This setting has no effect if you are using a hosted agent.
GitHub
VSTS, TFS 2017 Update 2, and newer: Click the Tasks tab, click Get sources, and then click GitHub.
TFS 2017 RTM and older: This option is not available, but you can instead use the External git option.
Connect using your GitHub user account
Note
If you're using a pop-up blocker, you'll need to allow your VSTS account to display pop-up windows.
This is the easier way to authorize your account. This approach grants your VSTS account access to GitHub via OAuth.
On the Repository tab, next to the Connection drop-down, click the Manage link. The Services tab opens as a new tab in your browser.
Click New Service Endpoint and choose GitHub.
In the Add New GitHub Service Connection dialog box, select Grant authorization, and then click Authorize.
In the new browser window, sign in to GitHub and follow the instructions to authorize VSTS to access your GitHub account.
On the Repository tab, select the Connection you created.
Select the Repository that contains the code you want to build.
Connect using a personal access token
Sign in to GitHub and make sure you have permission to read the repository.
In GitHub, create an access token.
Select the repo, user, and admin:repo_hook scopes.
Copy the token to your clipboard.
Sign on to VSTS and create a build definition.
On the Repository tab, next to the Connection drop-down, click the Manage link. The Services tab opens as a new tab in your browser.
Click New Service Endpoint and choose GitHub.
In the Add New GitHub Service Connection dialog box, select Personal access token.
Paste the token and give the connection a name.
On the Repository tab, select the Connection you created.
Select the Repository that contains the code you want to build.
Other options
Default branch: Select the branch that you want to be the default when you manually queue this build.
VSTS, TFS 2017 Update 2 or newer: Click Advanced settings to see the following options.
Clean:
If you set it to true, this command is run: git clean -fdx, git reset -hard HEAD
Set this to false if you want to define an incremental build to improve performance.
Tip: In this case, if you are building Visual Studio projects, on the Build tab, you can also uncheck the Clean check box of the Visual Studio Build or MSBuild step.
This setting has no effect if you are using a hosted agent.
Checkout submodules: Select if you want to download files from submodules.
Checkout files from LFS: Select if you want to download files from large file storage (LFS).
VSTS: Select the check box to enable this option.
TFS 2017 and TFS 2015 (OSX and Linux only): On the Variables tab, set Agent.Source.Git.Lfs to true.
Don't sync sources: Select the check box if you want to skip fetching new commits. This option can be useful in cases such as when you want to:
Git init, config, and fetch using your own custom options.
Use a build process to just run automation (for example some scripts) that do not depend on code in version control.
Shallow fetch: Select if you want to limit how far back in history to download. Effectively this results in git fetch --depth=n. If your repository is large, this option might make your build process more efficient. Your repository might be large if it has been in use for a long time. It also might be large if you added and later deleted large files.
In these cases this option can help you conserve network and storage resources. It might also save time. The reason it doesn't always save time is because in some situations the server might need to spend time calculating the commits to download.
VSTS: After you select the check box to enable this option, in the Depth box specify the number of commits.
TFS 2017 and TFS 2015 (OSX and Linux only): On the Variables tab, set Agent.Source.Git.ShallowFetchDepth to the number of commits in history you want to download. Specify 0 to set no limit.
Tip
If you're using VSTS, the above variables also work and override the check box controls. So for example, you can override the setting when you queue the build.
External Git (remote repository)
Sign in to the external Git service (for example, BitBucket) and make sure you have permission to read the repository.
Sign on to the VSTS or Team Foundation Server web portal and create a build definition.
On the Repository tab, next to the Connection drop-down, click the Manage link. The Services tab opens as a new tab in your browser.
Click New Service Endpoint and choose External Git.
Fill in the Add New External Git Repository Connection dialog box.
On the Repository tab, select the Connection you created.
Select the Repository that contains the code you want to build.
Branch (default): Select the branch that you want to be the default when you manually queue this build.
VSTS, TFS 2017 Update 2 or newer: Click Advanced settings to see the following options.
Clean:
If you set it to true, this command is run: git clean -fdx, git reset -hard HEAD
Set this to false if you want to define an incremental build to improve performance.
Tip: In this case, if you are building Visual Studio projects, on the Build tab, you can also uncheck the Clean check box of the Visual Studio Build or MSBuild step.
This setting has no effect if you are using a hosted agent.
Checkout submodules: Select if you want to download files from submodules.
Checkout files from LFS: Select if you want to download files from large file storage (LFS).
VSTS: Select the check box to enable this option.
TFS 2017 and TFS 2015 (OSX and Linux only): On the Variables tab, set Agent.Source.Git.Lfs to true.
Don't sync sources: Select the check box if you want to skip fetching new commits. This option can be useful in cases such as when you want to:
Git init, config, and fetch using your own custom options.
Use a build process to just run automation (for example some scripts) that do not depend on code in version control.
Shallow fetch: Select if you want to limit how far back in history to download. Effectively this results in git fetch --depth=n. If your repository is large, this option might make your build process more efficient. Your repository might be large if it has been in use for a long time. It also might be large if you added and later deleted large files.
In these cases this option can help you conserve network and storage resources. It might also save time. The reason it doesn't always save time is because in some situations the server might need to spend time calculating the commits to download.
VSTS: After you select the check box to enable this option, in the Depth box specify the number of commits.
TFS 2017 and TFS 2015 (OSX and Linux only): On the Variables tab, set Agent.Source.Git.ShallowFetchDepth to the number of commits in history you want to download. Specify 0 to set no limit.
Tip
If you're using VSTS, the above variables also work and override the check box controls. So for example, you can override the setting when you queue the build.
Subversion
You can build code you manage in Subversion. You must install the Subversion client on your build agents.
Q&A
How can I clean the repository in a different way?
If you want the Clean switch described above to work differently, then on the Variables tab, set the Build.Clean variable to:
allif you want to delete Agent.BuildDirectory, which is the entire working folder that contains the sources folder, binaries folder, artifact folder, and so on.sourceif you want to delete Build.SourcesDirectory.binaryIf you want to delete Build.BinariesDirectory.
How do I reference the sources directory on the build agent?
Use the Build.SourcesDirectory variable.
What kinds of submodules can I check out?
If you select Checkout submodules, the build process will check out your Git submodules so long as they are:
Children (immediate submodules) of the Git repo you've selected for this build process. In effect, the build process runs
git submodule update --init(notgit submodule update -init --recursive).Unauthenticated: A public unauthenticated repo with no credentials required to clone or fetch.
Authenticated:
Contained in the same team project, GitHub organization, or Bitbucket account as the Git repo specified above.
Added by using a relative url from main repository. For example this one would be checked out:
git submodule add /../../submodule.git mymoduleThis one would not be checked out:git submodule add https://fabrikamfiber.visualstudio.com/DefaultCollection/_git/ConsoleApp mymodule
Which GitHub repositories can I build?
You can build repositories you are authorized to push to.
What protocols can the build agent use with Git?
We support HTTPS.
We do not yet support SSH. See User Voice: Allow build to use ssh authentication while checking out git sub modules
When would I need to change TFVC mappings. How should I do it?
Make sure that you Map all folders that contain files that your build process requires. For example, if you add another project, you might have to add another mapping to the workspace.
Cloak folders you don't need. By default the root folder of team project is mapped in the workspace. This configuration results in the build agent downloading all the files in the version control folder of your team project. If this folder contains lots of data, your build could waste build system resources and slow down your build process by downloading large amounts of data that it does not require.
When you remove projects, look for mappings that you can remove from the workspace.
If this is a CI build, in most cases you should make sure that these mappings match the match the filter settings of your CI trigger on the Triggers tab.
For more information on how to optimize a TFVC workspace, see Optimize your workspace.
Is it possible to disable downloading files?
If you want to disable downloading sources:
VSTS, TFS 2017 Update 2, and newer: Click Advanced settings, and then select Don't sync sources.
TFS 2017 RTM and older: Define
Build.SyncSourceson the variables tab and set it to false.
Do I need an agent?
You need at least one agent to run your build or release. Get an agent.
I can't select a default agent queue and I can't queue my build or release. How do I fix this?
See 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 VSTS and not yet available on-premises. Some features are available on-premises if you have upgraded to the latest version of TFS.