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
Output Results
Configuration Example

# Applicable Events

所有事件

# Parameters

dockerfile
by
versionBy
buildArgs
target
sync
ignoreBuildArgsInVersion

# dockerfile

type: String
required: true

The Dockerfile path used for building the cache image.

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

This is used to declare a list of files that are dependencies during the cache image building process. Note: Any files not listed in the by list, except for the Dockerfile, are treated as non-existent during the image building 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

Whether it is in synchronous mode, waiting for the successful docker push of the cache 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 →