Queue a build

  • Article

After you define your build processes by creating one or more build definitions, you can start to reap the benefits of your build system. Most build processes are defined with automatic triggers. Whether your build definition has a manual or automatic trigger, you can manually queue a build whenever necessary.

Important

If you are using Visual Studio 2013 with Visual Studio Team Foundation Server 2013, you might have problems modifying build process parameters when you queue a build. Get the KB 2898341 hotfix.

Common tasks

Supporting content

Queue a public build if you want to build the most recent version of the source code in the version control server.

To queue a public build at a command prompt, use the TFSBuild start command.

Queue a private build if you want to build changes that you have put into a shelveset. You can use a private build (also known as a "buddy build") to validate changes to your code before you check it in.

To queue a private build at a command prompt, use the TFSBuild start command with the /shelveset option.

Retry a completed build if you want to queue a public or a private build using the same options as a completed build.

Retry a completed build

Public Builds

Regardless of whether an automatic trigger is specified in a build definition, you can manually queue the build.

  1. In Team Explorer:

    1. If you are not already connected to the team project that you want to work in, then connect to the team project.

    2. Choose Home icon Home, and then choose Builds Icon Builds (Keyboard: Ctrl + 0, B).

    3. On the Builds page, under Favorite Build Definitions or All Build Definitions, open the context menu for a build definition, and then choose Queue New Build.

    The Queue Build TeamProjectName dialog box appears.

  2. In the Build definition list, the build definition is selected and its description is displayed below. If you want to queue a different build definition, you can select one from the list.

  3. In the What do you want to build? list, make sure Latest sources is selected.

  4. (Optional) In the Build controller list, select a build controller other than the default build controller.

  5. (Optional) In the Priority in queue list, select one of the following values: High, Above Normal, Normal, Below Normal, or Low.

    The Position box displays the build's estimated position in the queue.

  6. (Optional) The Drop folder for this build box displays the location where outputs such as binaries and log files are stored when the build is completed. If you want to store the outputs in a different location, type the path to that location in this box.

    Important

    If you modify this value, you must specify a folder that has been prepared for use as a drop folder. You cannot modify this value if you have specified Copy build output to the server as the staging location for the build definition.

    See Select a staging location and set up a drop folder.

  7. (Optional) On the Parameters tab, view and override other build definition settings for this run only.

    If the build definition is based on either the Default Template or the Upgrade Template, see Use the Default Template for your build process or Resolve issues that can occur when you upgrade for more information about these parameters.

  8. Choose Queue.

Private Builds

You queue a private build if you want to build the changes that you have put into a shelveset. You can use a private build (also known as a "buddy build") to validate changes to your code before you check it in. By performing a private build of your changes before you check them in, you can reduce the chance that they will break any builds that your team runs regularly, such as the nightly build.

How Private Builds Differ from Public Builds

The results of a completed private build differ from a completed public build in the following ways:

  • A private build resembles a gated check-in build in that you are building code that includes changes in a shelveset. However, your changes are not automatically checked in for you after a private build as they are after a gated check-in build.

  • The build does not label your sources, create a work item on failure, or associate changesets and work items.

  • In Build Explorer, the completed build appears next to the following icon: Icon_BldPrivateBuild

  • The completed build is named by using the format Build N where N is a unique integer value. This format differs from that of public builds, which you specify by using the Build Number Format parameter.

  • For each build definition, you specify a separate (and optionally different) retention policy to limit the number of completed private builds that are stored in the system.

Queue a Private Build

  1. In Team Explorer:

    1. If you are not already connected to the team project that you want to work in, then connect to the team project.

    2. Choose Home icon Home, and then choose Builds Icon Builds (Keyboard: Ctrl + 0, B).

    3. On the Builds page, under Favorite Build Definitions or All Build Definitions, open the context menu for a build definition, and then choose Queue New Build.

    The Queue Build TeamProjectName dialog box appears.

  2. In the Build definition list, the build definition is selected and its description is displayed below. If you want to queue a different build definition, you can select one from the list.

  3. In the What do you want to build? list, select Latest sources with shelveset.

    The Shelveset name box appears.

  4. Follow one of these steps:

    • If you already have a shelveset, type its name into the Shelveset name box, or choose the ellipsis (…) button to search for the shelveset.

    • If you want to put some pending changes from your workspace into a shelveset and then build those changes, choose Create.

  5. (Optional) If the build is successful and you want to check in the changes in the shelveset, select the Check in changes after successful build check box.

    Important

    If you select this check box, the build is run as a gated check-in build instead of as a private build. For more information about gated check-in builds, see Use a gated check-in build process to validate changes.

  6. (Optional) In the Build controller list, select a build controller other than the default build controller.

  7. (Optional) In the Priority in queue list, select one of the following values: High, Above Normal, Normal, Below Normal, or Low.

    The Position box displays the build's estimated position in the queue.

  8. (Optional) On the Parameters tab, view and override other build definition settings for this run only.

    If the build definition is based on either the Default Template or the Upgrade Template, see Use the Default Template for your build process or Resolve issues that can occur when you upgrade for more information about these parameters.

  9. Choose Queue.

Retry a completed build

When you are testing some potential changes to a build process or experimenting with options, you can quickly queue a public or private build using the same options you specified when you queued build that is now completed.

  • In Team Explorer:

    1. If you are not already connected to the team project that you want to work in, then connect to the team project.

    2. Choose Home icon Home, and then choose Builds Icon Builds.

    3. On the Builds page, under My Builds, open the context menu for a completed build, and then choose Retry Build.