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 repository-specific environment variables.
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
- Plugin hooks - these are provided by any plugins you've defined in your
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 allow you to execute repository-specific scripts. Repository hooks live alongside your repository’s source code under the directory
To get started, create a shell script in
It will be sourced and run every build, after the Agent checks your repository out.
You can also use one of the other available Repository hooks, according to when you want your custom script to run.
Plugin hooks allow plugins you’ve defined in your Pipeline to override default behavior.
See the plugin documentation for how to implement plugin hooks.
The following is a complete list of available hooks, and the order in which they are called:
||Agent, Plugin||Runs before all other hooks. Useful for exposing secret keys and adding strict checks.|
||Agent, Plugin||Runs before checkout.|
||Plugin, Agent||Overrides the default
Note: As of Agent v3.15.0, if multiple checkout hooks are found, only the first will be run.
||Agent, Repository, Plugin||Runs after checkout.|
||Agent, Repository, Plugin||Runs before the build command.|
||Plugin, Repository, Agent||Overrides the default command running behavior. Note: If multiple command hooks are found, only the first will be run.|
||Agent, Repository, Plugin||Runs after the command.|
||Agent, Repository, Plugin||Runs before artifacts are uploaded, if an artifact upload pattern was defined for the job.|
||Agent, Repository, Plugin||Runs after artifacts have been uploaded, if an artifact upload pattern was defined for the job.|
||Agent, Repository, Plugin||Runs before the job finishes. Useful for performing cleanup tasks.|
||Agent||Runs when each agent shuts down, and prints output only to the agent log. Useful for performing cleanup tasks for the entire agent, outside of the job lifecycle.|
Creating hook scripts
Hooks are shell scripts you can use to run commands and export environment variables. Hooks have access to all the standard Buildkite environment variables.
Hooks are copied to
$TMPDIR directory and sourced by the default shell on the Agent that is running the build, which has a few implications:
$BASH_SOURCEcontains the location the hook is sourced from
$0contains the location of the copy of the script that is running from
- the shebang line of the hook script has no effect
To write hooks in another programming language, you need to call them from within the shell script, and explicitly pass any Buildkite environment variables you need to the script when you call it.
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'
Hooks on Windows
Agents running Windows require hook files to have either:
.batextension, and be written in Windows Batch, or
- Access to Git for Windows, which includes bash
An example of a windows
@ECHO OFF ECHO "--- :house_with_garden: Setting up the environment" SET GITHUB_RELEASE_ACCESS_KEY='xxx'