mirror of https://github.com/docker/docs.git
114 lines
5.0 KiB
Markdown
114 lines
5.0 KiB
Markdown
---
|
|
description: Automated builds
|
|
keywords: automated, build, images
|
|
title: Advanced options for Autobuild and Autotest
|
|
---
|
|
|
|
The following options allow you to customize your automated build and automated test processes.
|
|
|
|
## Environment variables for building and testing
|
|
|
|
Several utility environment variables are set by the build process, and are
|
|
available during automated builds, automated tests, and while executing
|
|
hooks.
|
|
|
|
> **Note**: These environment variables are only available to the build and test
|
|
processes and do not affect your service's run environment.
|
|
|
|
* `SOURCE_BRANCH`: the name of the branch or the tag that is currently being tested.
|
|
* `SOURCE_COMMIT`: the SHA1 hash of the commit being tested.
|
|
* `COMMIT_MSG`: the message from the commit being tested and built.
|
|
* `DOCKER_REPO`: the name of the Docker repository being built.
|
|
* `DOCKER_TAG`: the Docker repository tag being built.
|
|
* `IMAGE_NAME`: the name and tag of the Docker repository being built. (This variable is a combination of `DOCKER_REPO`:`DOCKER_TAG`.)
|
|
|
|
If you are using these build environment variables in a
|
|
`docker-compose.test.yml` file for automated testing, declare them in your `sut`
|
|
service's environment as shown below.
|
|
|
|
```none
|
|
sut:
|
|
build: .
|
|
command: run_tests.sh
|
|
environment:
|
|
- SOURCE_BRANCH
|
|
```
|
|
|
|
## Override build, test or push commands
|
|
|
|
Docker Cloud allows you to override and customize the `build`, `test` and `push`
|
|
commands during automated build and test processes using hooks. For example, you
|
|
might use a build hook to set build arguments used only during the build
|
|
process. (You can also set up [custom build phase hooks](#custom-build-phase-hooks) to perform actions in between these commands.)
|
|
|
|
**Use these hooks with caution.** The contents of these hook files replace the
|
|
basic `docker` commands, so you must include a similar build, test or push
|
|
command in the hook or your automated process will not complete.
|
|
|
|
To override these phases, create a folder called `hooks` in your source code
|
|
repository at the same directory level as your Dockerfile. Create a file called
|
|
`hooks/build`, `hooks/test`, or `hooks/push` and include commands that the
|
|
builder process can execute, such as `docker` and `bash` commands (prefixed appropriately with `#!/bin/bash`).
|
|
|
|
## Custom build phase hooks
|
|
|
|
You can run custom commands between phases of the build process by creating
|
|
hooks. Hooks allow you to provide extra instructions to the autobuild and
|
|
autotest processes.
|
|
|
|
Create a folder called `hooks` in your source code repository at the same
|
|
directory level as your Dockerfile. Place files that define the hooks in that
|
|
folder. Hook files can include both `docker` commands, and `bash` commands as long as they are prefixed appropriately with `#!/bin/bash`. The builder executes the commands in the files before and after each step.
|
|
|
|
The following hooks are available:
|
|
|
|
* `hooks/post_checkout`
|
|
* `hooks/pre_build`
|
|
* `hooks/post_build`
|
|
* `hooks/pre_test`
|
|
* `hooks/post_test`
|
|
* `hooks/pre_push` (only used when executing a build rule or [automated build](automated-build.md) )
|
|
* `hooks/post_push` (only used when executing a build rule or [automated build](automated-build.md) )
|
|
|
|
### Build hook examples
|
|
|
|
#### Override the "build" phase to set variables
|
|
|
|
Docker Cloud allows you to define build environment variables either in the hook files, or from the automated build UI (which you can then reference in hooks).
|
|
|
|
In the following example, we define a build hook that uses `docker build` arguments to set the variable `CUSTOM` based on the value of variable we defined using the Docker Cloud build settings. `$IMAGE_NAME` is a variable that we provide with the name of the image being built.
|
|
|
|
```none
|
|
docker build --build-arg CUSTOM=$VAR -t $IMAGE_NAME
|
|
```
|
|
|
|
> **Caution**: A `hooks/build` file overrides the basic `docker build` command
|
|
used by the builder, so you must include a similar build command in the hook or
|
|
the automated build will fail.
|
|
|
|
To learn more about Docker build-time variables, see the [docker build documentation]( https://docs.docker.com/engine/reference/commandline/build/#/set-build-time-variables---build-arg).
|
|
|
|
#### Two-phase build
|
|
|
|
If your build process requires a component that is not a dependency for your application, you can use a `pre-build` hook to collect and compile required components. In the example below, the hook uses a Docker container to compile a Golang binary required before the build.
|
|
|
|
```bash
|
|
#!/bin/bash
|
|
echo "=> Building the binary"
|
|
docker run --privileged \
|
|
-v $(pwd):/src \
|
|
-v /var/run/docker.sock:/var/run/docker.sock \
|
|
centurylink/golang-builder
|
|
```
|
|
|
|
#### Push to multiple tags
|
|
|
|
By default the build process tags the resulting Docker image with a single tag and pushes the image only to the repository where the build settings are configured.
|
|
|
|
If you needed to give the resulting image multiple tags, or push the same image to multiple repositories, you could set up a `post_push` hook to add additional tags and push to more repositories.
|
|
|
|
```none
|
|
docker tag $IMAGE_NAME $DOCKER_REPO:$SOURCE_COMMIT
|
|
docker push $DOCKER_REPO:$SOURCE_COMMIT
|
|
```
|