Overview

Build hooks are tasks carried out at certain hook points in a build. The tasks may optionally be restricted to chosen build states when run after a stage or build. For example, you may only want the task to run after successful nightly builds. Note that hooks differ from commands in a couple of key ways:

• Commands run as part of a recipe executing on an agent, whereas hooks run outside of the recipe and always on the master.
• Commands are reported on as part of the build result, and are considered more directly as part of the build.

If you find yourself wanting to run a hook on an agent, consider adding a command to the beginning or end of your recipe instead.

Build hooks are typically not used for build notifications, as pulse™ provides a flexible and user-centric notification system (see User Subscriptions for details). However, the send emails and run executable tasks may be used for notifications if desired.

Hook Points

Hooks points are the times within a build where tasks may be run. The available points are described below.

Pre Build

This hook point occurs just after a build becomes active. This is before the build has commenced, in fact before any recipes are queued to the recipe queue. At this point many properties are not yet defined.

Post Build

This point occurs just after a build has completed. At this point all stages are complete, the build result is known and all artifacts have been captured back to the master. The most common hook point, post-build tasks are often used for tagging source code, publishing artifacts and custom notifications.

Post Stage

This point occurs just after a stage has completed, and all stage artifacts have been collected back to the master. At this time the stage result and stage-specific properties will be available to the task.

This hook point has been specifically designed to allow custom cleanup on the agent to occur, as the agent status is set to an unknown state when the hooks are complete. Thus the master will not use the agent again until it receives an idle ping result from that agent. This allows, for example, the agent to be rebooted in a post-stage hook. Care must be taken to ensure that the hook shuts down the original agent synchronously before the hook completes, however, or the master may successfully ping the old agent before it is shut down and dispatch another recipe to it in parallel with the agent cleanup/reboot taking place.

Note Post stage hooks, like all hooks, are executed on the pulse™ master, not on the agent that executed the stage.

Manual

Manual hooks are never triggered automatically. Instead, you can trigger them as desired by using the links on the build summary tab. This allows hook tasks to form part of a manual workflow. Most build properties are made available to the task, although some may be different to when the build itself was run if configuration has been changed in the mean time.

Manual Triggering Note also that some hook tasks can be manually triggered even though they are also triggered automatically at a hook point. This can be useful to repeat or retry a failed task.

Hook Tasks

Hooks tasks described the actual action to perform at a hook point. The following tasks are available:

Refer to the page of the chosen type for more details.

Hook Task Context

Hook tasks execute in a context dependent on the hook point and the build they are running against. This context includes properties that can be used in the task configuration. The available properties for all tasks includes the standard built-in properties that are not specific to a single stage or recipe. Tasks run post stage also have access to the built-in properties specific to that stage. In addition, hooks run post stage or post build have access to further properties containing information about the build or stage result, as outlined below.

Additional Properties

These properties are available to tasks triggered post build (including manual triggers) and post stage.

Note For post stage actions, the "stage.<name>" prefix should be replaced simply with "stage" for stage-level properties and removed completely for command-level properties. The table below shows both forms.