Buildkite Agent hooks

This page references the out-of-date Buildkite Agent v2.

For docs referencing the Buildkite Agent v3, see the latest version of this document.

Every agent installer comes with a hooks directory which can be used to override and extend the built-in agent behavior. For example you could create a global checkout hook which speeds up a fresh git clone on a new build machine, a global environment hook which exports secret API keys as environment variables, or a pipeline-level command hook which runs the pipeline's steps inside a custom containerized environment.

Windows support

Agent hooks aren't available in this version. They are introduced in Agent v3

Overview

There are two types of hooks: global hooks which exist on the agent's machine and are the same for every pipeline, and pipeline level hooks which exist in each repository in the .buildkite/hooks directory.

Available hooks

Hooks are called in the following order:

  1. environment (global) - runs before all other commands, useful for exporting secret keys etc.
  2. pre-checkout (global) - runs before checkout
  3. checkout (global) - overrides the default git checkout behavior
  4. post-checkout (global) - runs after checkout
  5. post-checkout (local) - runs after checkout
  6. pre-command (global) - runs before the build command
  7. pre-command (local) - runs before the build command
  8. command (global) - overrides the default script running behavior, useful for changing how the command is evaluated (such as running it inside a container)
  9. post-command (local) - runs after the command
  10. post-command (global) - runs after the command
  11. pre-artifact (local) - runs before artifacts are uploaded, if an artifact upload pattern was defined for the job
  12. pre-artifact (global) - runs before artifacts are uploaded, if an artifact upload pattern was defined for the job
  13. post-artifact (local) - runs after artifacts have been uploaded, if an artifact upload pattern was defined for the job
  14. post-artifact (global) - runs after artifacts have been uploaded, if an artifact upload pattern was defined for the job
  15. pre-exit (local) - runs before the job finishes, useful for performing cleanup tasks
  16. pre-exit (global) - runs before the job finishes, useful for performing cleanup tasks

Creating hook scripts

Hooks are bash scripts you can use to execute commands and export environment variables. All the standard Buildkite environment variables are available to be used inside your hook scripts.

The following is an example of a custom environment hook which exports a GitHub API key for the pipeline's release build step:

set -eu
echo '--- :house_with_garden: Setting up the environment'

export GITHUB_RELEASE_ACCESS_KEY='xxx'

The following is an example of a custom pre-command hook which changes the working directory before the command is run:

set -eu
echo '--- :sparkles: Changing to the CI directory'

cd ci

Global hooks

Each agent installer comes with a hooks directory containing a sample set of hooks. You can find the location of your global hooks directory in your platform's installation documentation.

To get started with global hooks copy the relevant example script and remove the .sample file extension.

Pipeline hooks

Pipeline hooks allow you to execute pipeline-specific scripts. Pipeline hooks live alongside your pipeline's source code under the directory .buildkite/hooks.

To get started create a .buildkite/hooks directory, and your hook script, and make it executable, for example:

mkdir -p .buildkite/hooks

cat << 'HOOK_SCRIPT' > .buildkite/hooks/pre-command
set -eu
echo "--- :checkered_flag: Running pre-command"

echo "About to run command: $BUILDKITE_COMMAND"
HOOK_SCRIPT

chmod +x .buildkite/hooks/pre-command