Buildkite Agent Hooks

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 an agent checkout hook which speeds up a fresh git clone on a new build machine, an agent environment hook which exports secret API keys as environment variables, or a repository pre-command hook which sets up some repository-specific environment variables.

On this page:

Types of hooks
Available hooks
Creating hook scripts
Agent hooks
Repository hooks
Plugin hooks
Hooks on Windows

Types of hooks

There are three types of hooks:

Agent hooks - these exist on the agent’s machine, and are run for every job on any pipeline.
Repository hooks - these exist in your pipeline repository’s .buildkite/hooks directory.
Plugin hooks - these are provided by any plugins you've defined in your pipeline.yml.

Available hooks

The following is a complete list of hooks that can be implemented, and the order in which they are called:

Hook	Order	Description
`environment`	Agent, Plugin	Runs before all other hooks. Useful for exposing secret keys and adding strict checks.
`pre-checkout`	Agent, Plugin	Runs before checkout.
`checkout`	Plugin, Agent	Overrides the default `git checkout` behavior. Note: As of Agent v3.15.0, if multiple checkout hooks are found, only the first will be run.
`post-checkout`	Agent, Repository, Plugin	Runs after checkout.
`pre-command`	Agent, Repository, Plugin	Runs before the build command.
`command`	Plugin, Repository, Agent	Overrides the default command running behavior. Note: If multiple command hooks are found, only the first will be run.
`post-command`	Agent, Repository, Plugin	Runs after the command.
`pre-artifact`	Agent, Repository, Plugin	Runs before artifacts are uploaded, if an artifact upload pattern was defined for the job.
`post-artifact`	Agent, Repository, Plugin	Runs after artifacts have been uploaded, if an artifact upload pattern was defined for the job.
`pre-exit`	Agent, Repository, Plugin	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

Agent hooks

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

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

Repository hooks

Repository hooks allow you to execute repository-specific scripts. Repository hooks live alongside your repository’s source code under the directory .buildkite/hooks.

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

Plugin hooks

Plugin hooks allow any plugins you’ve defined to execute and override any of the default behavior.

See the plugin documentation for how to implement plugin hooks.

Hooks on Windows

Agents running Windows require hook files to have either:

A .bat extension, and be written in Windows Batch, or
Access to Git for Windows, which includes bash

An example of a windows environment.bat hook:

@ECHO OFF
ECHO "--- :house_with_garden: Setting up the environment"
SET GITHUB_RELEASE_ACCESS_KEY='xxx'