Build Completed Trigger

Build Completed

This section describes the Build Completed Trigger options. Visit the Triggers page for information regarding options such as 'Build Priority and 'Force Repository Check' which are shared by all trigger types.

Configuration

This property specifies which configuration should trigger a build. Any configuration can be used as the trigger, including configurations in other projects.

Note that a user can only assign a configuration to this property if they have view access for that configuration.

Only Trigger When

This option allows you to limit the status which allows a build to be queued by this trigger. Here you can set whether this configuration should be triggered when another build either finishes successfully or fails to build. Alternatively, you can queue the build regardless of the original's build result.

Trigger when build awaits stage promotion

Tick this to specify that the trigger should start a build when a build from the triggering configuration stops to wait for a stage to be promoted (either manually or automatically)

Allow multiple trigger events

Visible only if the 'Trigger when build awaits stage promotion' checkbox is ticked.

If this is ticked, the trigger runs each time the build awaits promotion and when the build completes.

Note, if the option to transfer any shared resource locks acquired by the triggering build is also checked, then shared resource locks will only be transferred on the first trigger event.

Trigger when a stage promotion times out or is cancelled

This specifies that the trigger should start a build when a build from the triggering configuration completes after a promotion times out or is manually cancelled.

Associate Changesets

Identifies which changesets should be associated with this build.

There are two options for associate changesets:

• Latest: This will only link the latest changeset to the build.
• All since last successful build: This will add all the changesets that have occurred in all repositories since the last successful build.

Options

Priority

Enter a number to indicate the priority of this trigger relative to any other Build Completed triggered by the same configuration event. Triggers with a higher priority with execute before triggers with a lower priority.

Copy artifacts from triggering build

Tick this to automatically copy files from the server workspace of the triggering build to the server workspace of the new build. A new Artifacts tab will be displayed to specify file patterns and destination folder.

Transfer any shared resource locks acquired by the triggering build

If this option is ticked and the triggering build has acquired any shared resource locks, these will be transferred to the triggered build and released once the triggered build has finished. If multiple build completed triggers are started from a single configuration, and there are not enough locks available, the locks will be transferred only to the leading triggered build(s) in order of priority.

Note that shared resources include an option to allow build completed triggers to exceed quotas when transferring locks.

Convert write locks from triggering build to read locks on triggered build

Visible only if the 'Transfer any shared resource locks acquired by the triggering build' checkbox is ticked.

Tick this option convert write locks from triggering build to read locks on triggered build. This allows the trigger to run and lock multiple builds from a single write lock.

Fail trigger with warning if no shared resource locks are available

Visible only if the 'Transfer any shared resource locks acquired by the triggering build' checkbox is ticked.

When this option is set, the triggered build will fail the shared resource quota limit has been reached.

Artifacts

Visible only if the 'Copy artifacts from triggering build' checkbox is ticked on the Options tab.

Artifact File Patterns

Enter patterns to match files to copy the triggering build workspace. Prefix a pattern with - to exclude files from other patterns. Any expressions will be expanded in the context of the triggering build using the current values when the triggering build completes.

Destination Folder

A folder to copy the artifact files to. This is relative to the workspace of the triggered build. Leave this blank to copy the artifacts to the root of workspace folder. Any expressions expand in the context of the triggered build using the default values when the build is queued.

Only copy files registered with the triggering build as artifacts

Tick this option to limit the files copied to those which are registered as artifacts in the stages of the triggering build.

Preserve directory structure when copying artifacts

When this option is set, the original directory structure for each matching file in the triggering build workspace is replicated in the trigger build workspace.

Log copied artifact files

Tick this option to write details of each file copied to the build log.

Variables

See the Triggers page for details on the Variables tab which is shared by all trigger types.

Conditions

Here you can enter expressions which must all evaluate to true before a build is started from this trigger. All expressions are evaluated in the context of the triggering build so $Build.Version$ refers to the version number of the build which initiated the trigger.