Build hooks allow behavior to be injected into the build process.
Use the postCommit field to execute commands inside a temporary container
that is running the build output image. The hook is executed immediately after
the last layer of the image has been committed and before the image is pushed to
a registry.
The current working directory is set to the image’s WORKDIR, which is the
default working directory of the container image. For most images, this is where
the source code is located.
The hook fails if the script or command returns a non-zero exit code or if
starting the temporary container fails. When the hook fails it marks the build
as failed and the image is not pushed to a registry. The reason for failing can
be inspected by looking at the build logs.
Build hooks can be used to run unit tests to verify the image before the build
is marked complete and the image is made available in a registry. If all tests
pass and the test runner returns with exit code 0, the build is marked
successful. In case of any test failure, the build is marked as failed. In all
cases, the build log will contain the output of the test runner, which can be
used to identify failed tests.
The postCommit hook is not only limited to running tests, but can be used
for other commands as well. Since it runs in a temporary container, changes made
by the hook do not persist, meaning that the hook execution cannot affect the
final image. This behavior allows for, among other uses, the installation and
usage of test dependencies that are automatically discarded and will be not
present in the final image.
There are different ways to configure the post build hook. All forms in the
following examples are equivalent and execute bundle exec rake test
--verbose:
-
Shell script:
postCommit:
script: "bundle exec rake test --verbose"
The script value is a shell script to be run with /bin/sh -ic. Use
this when a shell script is appropriate to execute the build hook. For example,
for running unit tests as above. To control the image entry point,
or if the image does not have /bin/sh, use command and/or args.
|
|
The additional -i flag was introduced to improve the experience
working with CentOS and RHeL images, and may be removed in a future release.
|
-
Command as the image entry point:
postCommit:
command: ["/bin/bash", "-c", "bundle exec rake test --verbose"]
In this form, command is the command to run, which overrides the image
entry point in the exec form, as documented in the
Dockerfile
reference. This is needed if the image does not have /bin/sh, or if
you do not want to use a shell. In all other cases, using script might be
more convenient.
-
Pass arguments to the default entry point:
postCommit:
args: ["bundle", "exec", "rake", "test", "--verbose"]
In this form, args is a list of arguments that are provided to the default
entry point of the image. The image entry point must be able to handle
arguments.
-
Shell script with arguments:
postCommit:
script: "bundle exec rake test $1"
args: ["--verbose"]
Use this form if you need to pass arguments that would otherwise be hard
to quote properly in the shell script. In the script, $0 will be "/bin/sh"
and $1, $2, etc, are the positional arguments from args.
-
Command with arguments:
postCommit:
command: ["bundle", "exec", "rake", "test"]
args: ["--verbose"]
This form is equivalent to appending the arguments to command.
|
|
Providing both script and command simultaneously creates an invalid
build hook.
|
Using the Command Line
The oc set build-hook command can be used to set the build hook for a build configuration.
To set a command as the post-commit build hook:
$ oc set build-hook bc/mybc --post-commit --command -- bundle exec rake test --verbose
To set a script as the post-commit build hook:
$ oc set build-hook bc/mybc --post-commit --script="bundle exec rake test --verbose"
