Trigger Build Task
This build task enables the chaining of builds within TFS.
Supported TFS Versions
The Build Task is supported for both VSTS and TFS on-Premises from Version 2015 Update 2 upwards.
If you are having problems installing the extension on you on Prem TFS and getting the following error message:
A new Task "Cancel Builds" is available that can be used to cancel builds that were triggered with the Trigger Build Task in any previous step
The latest release notes can be found on Github.
Version 3 now available
This version of the tasks are making use now of the official node.js library from Microsoft to access the VSTS/TFS instead of relying on a custom implementation. This brings the advantage of having many things built-in by design, being more uptodate with the current state of the REST API and making it easier to extend functionality.
The basic functionality was retested and worked fine. However there might be some cases where some things now look or behave a bit different (for example the logging). If you experience anything please let me know by creating a new issue on github.
Updating from Version 2.* to 3.*
There are only slight interface changes. If a custom TFS/VSTS Server address is used, the Team Project has to be specified now in a seperate variable instead of being part of the URL. If you don't use a custom URL, everything stays the same.
Updating from Version 1.* to 2.0.0
In order to update your Task from Version 1.* to the new Version 2.0.0, you have to manually switch the Version in the Build Definition:
The interface including mainly stays the same. Your configuration will work as before. The only changes were made in the authentication and how to access the stored variable when this was used before (see Release Notes) and that a flag was added to the Basic Configuration that untrusted certificate errors are ignored (see Basic Configuration below).
Removed Default Credentials Options
The option to authenticate via default credentials was removed as it is not well supported within Node.js. Please do switch to another authentication method. The task currently automatically will switch to OAuth if Default is still used - however this option will be removed in an upcoming version.
Stored Environment Variable
The Powershell version stored the triggered build id as an environment variable that was available even after the build. The new script will only use variables in scope of the build, however if there is still an id stored from the previous version, you have to delete it manually. If you have access to the Agent(s) directly you can simply delete the environment variable "TriggeredBuildIds".
A list of all current issues can be found on Github.
If you find any Bugs, you have feature- or change requests or questions in general about the Task, feel free to raise an issue over at Github.
The configuration is quite simple. After adding the task to your current build, you can select under Basic Configuration the Name of the Build you would like to trigger.
Important: If your build definition name contains a '&', the task will fail (see Known Issues above).
If your build would be in another Team Project, another collection on the same server or a completly different server, uncheck the checkbox and fill in the URL to the server including the collection and the team project. This would look something like this:
Furthermore you can select whether the subsequent builds that are triggered should be run as it would be requested by the same user that triggered the original build or not. This can be useful if you have any kind of query that is based on the name, for example if you want to filter for builds triggered by you or if you have setup email alerts.
If you do not select this option, it depends on the method of authentication (see below) for whom the builds will be triggered:
The Ignore SSL Certificate Errors flag can be used if you need to ignore SSL errors caused by untrusted certificates.
Important Configuration Options when Triggered Build is not located on the VSTS/TFS Instance or Team Project
If the target build is on a different TFS some special circumstances apply. First and foremost the authentication options (see below) are limited. You cannot use OAuth authentication, either use a Personal Access Token (recommended) or Basic Authentication.
As well it's not possible to have conditions based on builds of the current VSTS/TFS, due to the authentication being setup for the VSTS/TFS Instance that hosts the triggered build. Conditions based on builds of this Instance however would be possible.
If you want to trigger a build from a different Team Project but within the same VSTS/TFS instance you can still use OAuth Authentication.
In any case if you trigger a build from a different team project, no matter if on the same or a different server instance, the following Advanced Configuration options shall not be enabled to prevent issues:
Use Same Source Version
If this option is enabled, the triggered build will use the same source version as the build that includes the task. This means if the build was triggered for a specific changeset or label, the same source version will used in the triggered build. This option is disabled by default, which means the triggered build will use the latest sources.
Use Same Source Branch
If this is enabled, the triggered build will use the same source branch as the build that includes the task. This means if the build is triggered for the source branch master, the triggered build will as well.
If you disable this option, you can specify the source-branch that shall be used yourself. If you don't define anything, the source-branch parameter will not be specified and the default will be used.
Wait for Completion of Triggered Builds
If you enable this option, the build task will wait for the completion of all the triggered builds.
There is as well the option to cancel all awaited builds if you are failing the task due to a build that failed. This will then stop other builds and free up the build queue.
Important: If you don't have an additional available build agent you will get stuck, as the original build is waiting for the completion of the other build, which can only be started once the original build is finished and the agent will be available!
####Wait for Triggered Build Task There is a dedicated Task that can be used in order to wait for triggered Builds to finish. When using this Task instead of the above mentioned option, you can do other Tasks in between and just start waiting at the latest possible moment. The Task uses as an input the Stored Build ID's (see below) of any Trigger Build Task that was running before and that set the option of storing the IDs. The rest of the configuration is as described above.
Cancel Build Task
There is as well a dedicated task to cancel builds. This can be used for example to cancel all builds if anything in the build itself fails after triggering. Just add the task in the end of the build and set it to be executed only if a previous task failed. The task works against the Stored Build ID's in the same way as the Wait for Triggered Build Task does.
###Store Build IDs in Variable If any subsequent task needs the info of which builds were triggered by this Task, this information is available as an environment variable to the subsequent Tasks. The name of the variable is TriggeredBuildIds. If more than one build will be triggered, the values will be written comma separated. If there is already a value in the variable from a previous Task, it not overwritten but keep the original value and append his resulting build id's.
In for example a PowerShell Script the variable can be accessed like this:
Write-Output "Fetching variable TriggeredBuildIds:"
The possible output could then look like this for 2 triggered builds:
The variable is as well available as an input in the configuration for any subsequent Task. Just access it like this: $(TriggeredBuildIds)
Depending on your build definition a ceratin set of demands will be required from the agent to be built. When queuing a build additional demands can be specified, for example to filter for a special build agent. If additional demands need to be specified, they can be added here. Multiple demands can be specified when they are separated by a comma.
####Syntax The syntax is as follows. If you just want to check if the demand exists on the agent, just specify the value (see image above the demand "MySpecialDemandForThisBuild". Furthermore a demand can be checked if it has a certain value. To add this kind of demands you can write it like this: "OtherDemand = 42".
Note: If no suitable agent is available with the specified demands, the build cannot be triggered and the Task will fail!
Specify here the name or the id of the agent queue that you want to use. If not specified, the default queue will be used.
Note: When specifying a Queue you have to make sure that the user triggering the build has no access to it, for example when using the OAuth Authentication Method. This is the case when the error Error message: Error: No agent pool found with identifier 769 is shown. An option to work around this would be to switch to Personal Access Token Authentication and making sure that the Token has enough access rights. More details can be found on github.
Delay between triggering builds
Define here if you wish to delay the builds that are triggered by the specified amount of seconds. This might be useful if you have some issues when triggering builds at nearly the same time.
This field allows to parametrize the triggered build. The option you can specify via the GUI if you queue the build manually can be passed here. As you can see in the screenshot above, the syntax to specify those parameters is a bit tricky.
Caution: Be cautious when you have a variable value that contains itself a comma. As this is used in the task for separating the parameter key's and values it can cause some issues. However it is supported that you have Variable values that include a comma, however then your parameter cannot contain a colon.
However, the following will not work:
Please see the following Issue for a more detailed explanation. If you cannot work around this, please open a new Issue on github.
An exception to the rules above is if the value is a complete Json object, this will be treated specially. For example the following will be allowed:
Json values are detected only when the value is enclosed by curly braces. More details can be found on the following github issue.
Note: If you set a variable via these parameters that is not settable at queue time, the Build Task will still succeed. However, the build that is triggered might fail. For example if the build configuration is not settable at queue time but fix set to Release, and you specify the parameter anyway and will pass "Debug", you will get the following error:
In this section can be set how you authenticate against your TFS.
This option is not supported anymore - when used the script will automatically try to use the OAuth Token instead to provide support for. However it will create a warning and you should change it yourself to another Authentication Method as this will option will be removed in the future.
If you want to use OAuth, you can select this option. If you leave the Token field empty, the task will try to access the System.AccessToken environment variable of your build agent. If you use this option, make sure that you enabled the option Allow Scripts to Access OAuth Token in the options of your Build Definition.
On TFS Instances (2015 - 2018) this is located under the Options of the Build Definition.
This option will work with Hosted Build Agents from VSTS.
Personal Access Token
If you want to use a Personal Access Token, you have to make sure that it at least has the following right: Build (read and execute)
If you have enabled Basic Authentication, you can as well use this sort of authentication by providing the username and password.
If the specified user will not have sufficient rights, the task will fail!
The build tasks supports two different kinds of conditions.
Build In Queue Condition
The first condition is called Build In Queue condition.
As with the build to trigger, you specify the builds by name. You can add multiple builds separated by a comma. If you want to include the build you are currently modifying you can do this via the provided checkbox.
Build Dependency Condition
The second supported condition is the Dependency Condition. This condition will check the latest builds of the provided build definitions and will only trigger the new build if those last builds were successful.
Failed Build Dependency Condition
This condition is very similar to the Build Dependency Condition mentioned above. The difference is that it will check whether the latest builds of the provided build definitions were failing and will only trigger the new build if the builds failed.
Filter Builds that are specified in the Condition
If this option is enabled, all the builds that are looked at in any of the conditions are filtered whether they were triggered in the context of the same branch as the current source build.
Warning: This does only make sense if your build to trigger is:
Fail Task if Any Condition is not fulfilled
This option allows to fail the task if a condition was setup and is not met. It has no effect if you don't specify any of the other conditions.
In case you have issues, for example exceptions when you run the Task make sure that the Authentication Option selected is valid. If you still have problems, please open a new issue at github.