CNB

Docker caching

docker:cache

Build a Docker cache that can be reused in future builds.

This helps avoid redundant downloads of network resources such as dependencies.

# Applicable Events

所有事件

# Parameters

# dockerfile

  • type: String
  • required: true

The Dockerfile path used for building the cache.

To avoid excessively long build times, the timeout for Docker image builds is controlled by the job.timeout parameter.

# by

  • type: Array<String> | String
  • required: false

The by list is used to declare the list of files that are dependencies during the cache build process. Note: Any files not listed in the by list, except for the Dockerfile, are treated as non-existent during the cache build process.

  • Arrays are supported.
  • String format is supported, where multiple files are separated by commas.

# versionBy

  • type: Array<String> | String
  • required: false

The versionBy parameter is used for version control. If versionBy is not provided, it defaults to using the values from the by list for version control.

If the content of the file pointed to by versionBy changes, it is considered a new version. The specific calculation logic for version control is determined by the following expression: sha1(dockerfile + versionBy + buildArgs + target + arch)

  • Arrays are supported.
  • String format is supported, where multiple files are separated by commas.

# buildArgs

  • type: Object
  • required: false

When building, you can insert additional build arguments using the --build-arg $key=$value syntax. If the value is null, you can include only the key by using --build-arg $key.

# target

  • type: String
  • required: false

Same as the --target parameter in docker build, you can selectively build specific stages of the Dockerfile instead of building the entire Dockerfile.

# sync

  • type: Boolean
  • required: false
  • default: false

In synchronous mode, the execution waits for the successful completion of the docker push command for the cached image before proceeding.

# ignoreBuildArgsInVersion

  • type: Boolean
  • required: false
  • default: false

Determines whether the version calculation ignores buildArgs.

Please refer to "Version Control" for more details.

# Output Results

{
  // Docker image name corresponding to the cache
  name
}

# Configuration Example

main:
  push:
    - docker:
        image: node:14
      stages:
        - name: build cache image
          type: docker:cache
          options:
            dockerfile: cache.dockerfile
            # by supports two forms: array and string
            by:
              - package.json
              - package-lock.json
            # versionBy: package-lock.json
            versionBy:
              - package-lock.json
          exports:
            name: DOCKER_CACHE_IMAGE_NAME
        - name: use cache
          image: $DOCKER_CACHE_IMAGE_NAME
          # Copy files from the cache to use
          commands:
            - cp -r "$NODE_PATH" ./node_modules
        - name: build with cache
          script:
            - npm run build

In the above example, cache.dockerfile is a Dockerfile used to build the cache. Example:

# Choose a base image
FROM node:14

# Set the working directory
WORKDIR /space

# Copy the files listed in `by`
COPY .

# Install dependencies based on the copied files
RUN npm ci

# Set the required environment variables
ENV NODE_PATH=/space/node_modules

await →