Includes allow you to separate your configuration into multiple files or share configuration between projects.
Includes can be from files, or from a Git repository.
Git repositories designed to be used in this way are referred to as 'bundles'. The bundles page lists some publicly-available bundles you can use in your own projects.
The format for included files is the same as for standard configuration files, but cannot have a project name. Included files can include further files.
File includes can be specified in either of these two formats:
Concise format:include:- some-include.yml
Expanded format:include:- type: filepath: some-include.yml
The path to the included file is relative to the directory containing the configuration file. (For example, if
/my-project/dir-a/batect.yml has an include
/my-project/dir-b/extra-config.yml will be used.)
Git includes must be specified in this format:
repois the URL of the repository, as you would pass to
refis the name of the tag or branch, or commit hash to use.
It's highly recommended that you use an immutable tag, as this ensures that you always get the same bundle contents each time.
pathis the path to the configuration file from the repository to include. It is optional and defaults to
The bundles page lists some publicly-available bundles you can use in your own projects.
Only use bundles that you trust, as they can contain arbitrary code that will be executed when you run a task or use a container from a bundle.
Relative paths in included files such as paths for volume mounts or build directories will be resolved relative to that file's directory.
Use the built-in
batect.project_directory config variable to get the path to the root project directory,
Then the resulting configuration is as if
The following configuration file includes version 0.2.0 of the hello world bundle:
This bundle adds a single
say-hello task that can be run just like any other task:
The following are some tips for building bundles:
Pulling a pre-built image is generally faster than building an image from a Dockerfile.
It also prevents issues when packages or other external resources are removed.
Batect clones the repository and checks out the given tag or branch, and shares this working copy between projects to save time and disk space. Storing state in this working copy would mean that different projects could interfere with one another.
Instead, store any state in the project's directory. Use the
batect.project_directory config variable
to get the path to the project's directory. See the paths in included files section above for an example.
Similar to Docker's behaviour when pulling image tags, Batect only checks that it has previously cloned the Git reference (branch name, tag name or commit) - it does not check that the local clone is up-to-date with that reference. Therefore, using an immutable reference such as a tag ensures that everyone using the project gets the exact same version of the bundle.
It is recommended you use semantic versioning when versioning bundles.
Testing your bundle ensures that it works as expected. The hello world bundle has an example of how to do this.