Skip to content

Latest commit

 

History

History
113 lines (83 loc) · 4.97 KB

advanced.md

File metadata and controls

113 lines (83 loc) · 4.97 KB
Raw
description keywords title
Automated builds
automated, build, images
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.

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 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 )
  • hooks/post_push (only used when executing a build rule or automated build )

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.

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.

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.

#!/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.

docker tag $IMAGE_NAME $DOCKER_REPO:$SOURCE_COMMIT
docker push $DOCKER_REPO:$SOURCE_COMMIT