Build definition repository

Last Update: 3/8/2017

Team Services | 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

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.

If you're using the New Build Editor, then 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

    How can I clean the repo a different way?

  • 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).

  • Team Services: 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.

  • Team Services: 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 Team Services, 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

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?

If you're using the New Build Editor, then 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

    How can I clean the repo a different way?

  • 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

If you're using Visual Studio Team Services (Team Services), you can build code in a GitHub repo.

Connect using your GitHub user account

Note: If you're using a pop-up blocker, you'll need to allow your Team Services account to display pop-up windows.

This is the easier way to authorize your account. This approach grants your Team Services account access to GitHub via OAuth.

  1. 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.

    1. Click New Service Endpoint and choose GitHub.

    2. In the Add New GitHub Service Connection dialog box, select Grant authorization, and then click Authorize.

    3. In the new browser window, sign in to GitHub and follow the instructions to authorize Visual Studio Team Services to access your GitHub account.

  2. On the Repository tab, select the Connection you created.

  3. Select the Repository that contains the code you want to build.

Connect using a personal access token

  1. Sign in to GitHub and make sure you have permission to read the repository.

  2. In GitHub, create an access token.

    1. Select the repo, user, and admin:repo_hook scopes.

    2. Copy the token to your clipboard.

  3. Sign on to Team Services and create a build definition.

  4. 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.

    1. Click New Service Endpoint and choose GitHub.

    2. In the Add New GitHub Service Connection dialog box, select Personal access token.

    3. Paste the token and give the connection a name.

  5. On the Repository tab, select the Connection you created.

  6. 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.

If you're using the New Build Editor, then 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

    How can I clean the repo a different way?

  • 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).

  • Team Services: 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.

  • Team Services: 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 Team Services, 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)

  1. Sign in to the external Git service (for example, BitBucket) and make sure you have permission to read the repository.

  2. Sign on to the Visual Studio Team Services or Team Foundation Server web portal and create a build definition.

  3. 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.

    1. Click New Service Endpoint and choose External Git.

    2. Fill in the Add New External Git Repository Connection dialog box.

  4. On the Repository tab, select the Connection you created.

  5. 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.

If you're using the New Build Editor, then 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

    How can I clean the repo a different way?

  • 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).

  • Team Services: 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.

  • Team Services: 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 Team Services, 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:

  • all if you want to delete Agent.BuildDirectory, which is the entire working folder that contains the sources folder, binaries folder, artifact folder, and so on.

  • source if you want to delete Build.SourcesDirectory.

  • binary If 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 (not git 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 mymodule This 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, define Build.SyncSources on the variables tab and set it to false.

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 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.