How to use YAML builds


When you define a CI build on VSTS, you've got a fundamental choice: use a web-based interface or configure your CI process as code in a YAML build. YAML build definitions give you the advantages of configuration as code.


To use this capability, you must have the Build YAML definitions preview feature enabled on your account.

In a YAML build definition, your CI build process configured as code, which means:

  • The definition is versioned with your code and follows the same branching structure as your code. So you get validation of your changes through code reviews in pull requests and branch build policies.

  • If a change to the build process causes a break or results in an unexpected outcome, you can much more easily identify the issue because the change is in version control with the rest of your codebase. This way you can more clearly see the issue and fix it like any other kind of bug.

Get started

If you're new to YAML builds, or to VSTS, we suggest you begin learning with either our ASP.NET Core or Node.js tutorial.

How do YAML builds compare to web-interface builds?

Capability YAML Web interface
Git and GitHub Yes Yes
Bitbucket Not yet Yes
External Git, Subversion No Yes
Configuration as code Yes No
Fan out and fan in Yes Not yet
Variables across phases Yes Not yet
Test and debug the process locally Not yet No
Set environment variables for scripts (useful for secrets) Yes Not yet
Badge enabled Not yet Yes
Pause/disable definition from web editor Not yet Yes
Link work items Not yet Yes
Create work item on failure Not yet Yes
Allow scripts to access OAuth token Not yet Yes
Build job authorization scope Not yet Yes
Checkout options: Tag sources, Report build status, Checkout submodules Not yet Yes

Automatically create a YAML build definition

To make it more convenient to create YAML build definitions, VSTS automatically creates a definition when you add a file named .vsts-ci.yml to the root of your repository. It creates the build definition in a folder that has the same name as your repository.

  1. Navigate to the Code hub, choose the Files tab, and then choose the repository you created in the above steps.

  2. In the root folder of the repo, create a new file called .vsts-ci.yml.

  3. Paste the following content into the file:

- script: echo hello world 

If your code is in VSTS, then a new build is automatically created and queued.


If your team project already has a build definition that's pointing to the file, then the system does not automatically create another build definition.

Manually create a YAML build definition

If your code is in GitHub, or if you want to create multiple YAML build definitions, then after you have published the YAML file in your repo, you can manually create a build definition.

  1. Navigate to the Builds tab of the Build and Release hub in VSTS or TFS, and then click + New. You are asked to Select a template for the new build definition.

  2. Choose YAML, and then click Apply.

  3. Click Get sources.

  4. Select the repo that contains your .YML file.

  5. Click Process.

  6. For the Agent queue select any of the hosted options.

  7. For YAML path, click the ... button, and then choose your .YML file.

  8. Choose Save & queue.

Example: Hello world

To see a more interesting example in action, replace the content in .vsts-ci.yml with this content:


- script: |
    echo hello world from %MyName%
    echo Agent.HomeDirectory is %CD%
  workingDirectory: $(Agent.HomeDirectory)
    MyName: $(Agent.MachineName)
  condition: and(succeeded(), eq(variables['agent.os'], 'windows_nt'))
  displayName: Greeting from Windows machine

- script: |
    echo hello world from $MyName
    echo Agent.HomeDirectory is $PWD
  workingDirectory: $(Agent.HomeDirectory)
    MyName: $(Agent.MachineName)
  condition: and(succeeded(), in(variables['agent.os'], 'darwin', 'linux'))
  displayName: Greeting from macOS or Linux machine

Queue the build on any of our hosted agent pools, including Hosted VS 2017, Hosted Linux Preview or Hosted macOS Preview. You'll get different kinds of greetings from each of these typs of agent.

Look up tasks

To look up the syntax of the tasks that are built into VSTS and TFS, see

For example, if you want to use the Copy Files task, go to and then click the task.json file. In this file you'll find the name of task, which in this case is CopyFiles. You'll also find the valid inputs, for example the SourceFolder input.

Learn more

To learn more about what you can do with YAML builds, see