Skip to main content

Building your own Docker image on Bitrise

Abstract

You can create your own Docker image and push it to a container registry during a Bitrise build with the Docker Build & Push Step.

You can create your own Docker image and push it to a container registry during a Bitrise build with the Docker Build & Push Step.

The Step uses the docker build command: it requires a Dockerfile that contains the build instructions and a build context. Build context means the set of files located at the specified path. The Step allows you to pass options and build arguments to the build.

To speed up your builds, the Step also supports key-based caching.

To build the image with build options, build arguments and caching used:

Workflow Editor

bitrise.yml

  1. Add the Docker Build & Push Step to your Workflow.

  2. Configure the required inputs for the Step:

    • Image tags: A list of tags to be applied to the name of the built image. You can add one tag per line. For more information about image tags, their function, and their required format, check out the Docker documentation.

    • Build context path: The path to the files that constitute your build context. It should be relative to your Bitrise working directory.

    • Dockerfile path: The path to the Dockerfile you wish to use. It should be relative to your Bitrise working directory.

  3. If you want to push the built image to a container registry, set the Push docker image input to true.

  4. To cache the image, set the Use Bitrise key-value cache input to true.

    The input uses the following cache keys:

    • docker-imagename-{{ .OS }}-{{ .Arch }}-{{ .Branch }}-{{ .CommitHash }}

    • docker-imagename-{{ .OS }}-{{ .Arch }}-{{ .Branch }}

    • docker-imagename-{{ .OS }}-{{ .Arch }}

    Alternative caching method

    The Step also supports caching using the --cache-from and the --cache-to options of the docker build command. The Cache from arguments and Cache to arguments inputs provide this function.

    If using key-based caching, do NOT use these inputs! Leave them empty.

  5. Optionally, customize the build command with build arguments and options.

    • Add build arguments in the Build arguments input: one argument per line in a MY_ARG=my_value format.

    • Add options in the Extra options input: one extra option per line in the format of --option value or --option=value.

      Values with quotes

      When using values with quotes in them (for example, when the value contains spaces) do not use the equal sign. Separate it with spaces instead: --option "value with spaces".

  1. Add the docker-build-push Step to your Workflow.

  2. Configure the required inputs for the Step:

    • tags: A list of tags to be applied to the name of the built image. You can add one tag per line. For more information about image tags, their function, and their required format, check out the Docker documentation.

    • context: The path to the files that constitute your build context. It should be relative to your Bitrise working directory.

    • file: The path to the Dockerfile you wish to use. It should be relative to your Bitrise working directory.

    workflow:
  steps:
    - docker-build-push:
        inputs:
        - tags: myregistry.com/myimage:latest
        - context: "./path"
        - file: "./Dockerfile"

  3. If you want to push the built image to a container registry, set the push input to true.

    workflow:
  steps:
    - docker-build-push:
        inputs:
        - tags: myregistry.com/myimage:latest
        - context: "./path"
        - file: "./Dockerfile"
        - push: "true"

  4. To cache the image, set the use_bitrise_cache input to true.

    The input uses the following cache keys:

    • docker-imagename-{{ .OS }}-{{ .Arch }}-{{ .Branch }}-{{ .CommitHash }}

    • docker-imagename-{{ .OS }}-{{ .Arch }}-{{ .Branch }}

    • docker-imagename-{{ .OS }}-{{ .Arch }}

    Alternative caching method

    The Step also supports caching using the --cache-from and the --cache-to options of the docker build command. The cache_from and cache_to inputs provide this function.

    If using key-based caching, do NOT use these inputs! Leave them empty.

    workflow:
  steps:
    - docker-build-push:
        inputs:
        - tags: myregistry.com/myimage:latest
        - context: "./path"
        - file: "./Dockerfile"
        - push: "true"
        - use_bitrise_cache: "true"

  5. Optionally, customize the build command with build arguments and options.

    • Add build arguments in the build_arg input: one argument per line in a MY_ARG=my_value format.

    • Add options in the extra_options input: one extra option per line in the format of --option value or --option=value.

      Values with quotes

      When using values with quotes in them (for example, when the value contains spaces) do not use the equal sign. Separate it with spaces instead: --option "value with spaces".

    workflow:
  steps:
    - docker-build-push:
        inputs:
        - tags: myregistry.com/myimage:latest
        - context: "./path"
        - file: "./Dockerfile"
        - push: "true"
        - use_bitrise_cache: "true"
        - build_arg: BUILD_ARG=my_value
        - extra_options: "--option value"
In this section: