Build and push docker images caching each stage to reduce build time
MIT License
This action builds your docker image and caches the stages (supports multi-stage builds) to improve building times in subsequent builds.
By default, it pushes the image with all the stages to a registry (needs username and password), but you can disable this feature by setting push_image_and_stages
to false
.
Built-in support for the most known registries:
Docker updated to 24.0.6
BuildKit is enabled for faster/parallel builds
Cache also works with BuildKit enabled except for old GitHub Docker Registry (docker.pkg.github.com). You can either migrate to ghcr.io or disable BuildKit to use the old registry:
- name: Build with DOCKER_BUILDKIT disabled for old GitHub Docker Registry
uses: whoan/docker-build-with-cache-action@master
env:
DOCKER_BUILDKIT: 0
with:
registry: docker.pkg.github.com
...
or
🌟 New in v5.10.0: Now you can use overrides for your compose file(s) like this:
docker-compose.yml > docker-compose.override.yml > docker-compose.override2.yml
image_tag: Tag(s) of the image. Allows multiple comma-separated tags (e.g. one,another
) (default: latest
).
If you set compose_file and the image(s) already has/have a tag, this is ignored.
context: Docker context (default: ./
). If a compose_file is provided, it will be the context prefixed to any additional context read from the compose file. Look at #133 for more details.
registry: Docker registry (default: Docker Hub's registry). You need a registry to use the cache functionality.
username: Docker registry's user (needed to push images, or to pull from a private repository).
password: Docker registry's password (needed to push images, or to pull from a private repository).
session: Extra auth parameters. For AWS ECR, means setting AWS_SESSION_TOKEN environment variable.
push_git_tag: In addition to image_tag
, you can also push the git tag in your branch tip (default: false
).
pull_image_and_stages: Set to false
to avoid pulling from the registry or to build from scratch (default: true
).
stages_image_name: Set custom name for stages/cache image (default: ${image_name}-stages
). Tags are ignored.
push_image_and_stages: Test a command before pushing. Use false
to not push at all (default: true
).
This input also supports 2 special values, which are useful if your workflow can be triggered by different events:
on:push
: Push only if the workflow was triggered by a push.on:pull_request
: Push only if the workflow was triggered by a pull_request.services_regex: Regex to filter services from compose file. Only valid when compose_file was provided. Default is .+
(all services).
compose_file
is setimage_name
dockerfile: Dockerfile filename path (default: "$context"/Dockerfile
).
build_extra_args: Extra params for docker build
(e.g. "--build-arg=hello=world"
).
🌟 New in v5.11.0: If you need extra args with newlines or spaces, use json format like this:
build_extra_args: '{"--build-arg": "myarg=Hello\nWorld"}'
🌟 If you need multiple args with same key, use an array as the value of the key like this:
build_extra_args: '{"--build-arg": ["foo=bar", "one=two"]}'
docker.pkg.github.com/whoan/hello-world/hello-world
The action does the following every time it is triggered:
registry
(default: https://hub.docker.com)image_tag
<image_name>-stages:<1,2,3,...>
<image_name>:<git_tag>
if you set push_git_tag: true
Find working minimal examples for the most known registries in this repo.
If you don't specify a registry, Docker Hub is the default one
- uses: whoan/docker-build-with-cache-action@v5
with:
username: whoan
password: "${{ secrets.DOCKER_HUB_PASSWORD }}"
image_name: hello-world
GitHub automatically creates a GITHUB_TOKEN secret to use in your workflow. If you are going to use the new GitHub Registry (ghcr.io), be sure to use a Personal Access Token (as the password) with "write:packages" and "read:packages" scopes. More info here.
If you push the image to a public repository's GitHub Registry, please be aware that it will be impossible to delete it because of GitHub's policy (see Deleting a package).
- uses: whoan/docker-build-with-cache-action@v5
with:
username: whoan
password: "${{ secrets.GITHUB_TOKEN }}"
registry: docker.pkg.github.com
#or
#registry: ghcr.io
image_name: hello-world
More info here on how to get GCloud JSON key.
- uses: whoan/docker-build-with-cache-action@v5
with:
username: _json_key
password: "${{ secrets.GCLOUD_JSON_KEY }}"
registry: gcr.io
image_name: hello-world
You don't even need to create the repositories in advance, as this action takes care of that for you! (you'll need the
CreateRepository
permission)
- uses: whoan/docker-build-with-cache-action@v5
with:
username: "${{ secrets.AWS_ACCESS_KEY_ID }}" # no need to provide it if you already logged in with aws-actions/configure-aws-credentials
password: "${{ secrets.AWS_SECRET_ACCESS_KEY }}" # no need to provide it if you already logged in with aws-actions/configure-aws-credentials
session: "${{ secrets.AWS_SESSION_TOKEN }}" # if you need role assumption. no need to provide it if you already logged in with aws-actions/configure-aws-credentials
# private registry
registry: 861729690598.dkr.ecr.us-west-1.amazonaws.com
# or public registry
#registry: public.ecr.aws
image_name: hello-world
The compose file is parsed and the action will run once for each detected image. The registry is also detected from the image name, and if none is provided, DockerHub is assumed.
- uses: whoan/docker-build-with-cache-action@v5
with:
username: whoan
password: "${{ secrets.DOCKER_HUB_PASSWORD }}"
compose_file: docker-compose.yml
- uses: whoan/docker-build-with-cache-action@v5
with:
username: whoan
password: "${{ secrets.GITHUB_TOKEN }}"
registry: docker.pkg.github.com
compose_file: docker-compose.yml
With a compose file override:
- uses: whoan/docker-build-with-cache-action@v5
with:
username: whoan
password: "${{ secrets.DOCKER_HUB_PASSWORD }}"
compose_file: docker-compose.yml > docker-compose.override.yml
Filtering services by regex:
- uses: whoan/docker-build-with-cache-action@v5
with:
username: whoan
password: "${{ secrets.GITHUB_TOKEN }}"
registry: docker.pkg.github.com
compose_file: docker-compose.yml
services_regex: '(service_1|extra_service.*)' # eg: builds services called exactly "service_1" plus the ones which start with "extra_service" and may have extra chars after
- uses: whoan/docker-build-with-cache-action@v5
with:
username: whoan
password: "${{ secrets.GITHUB_TOKEN }}"
image_name: whoan/docker-images/node
image_tag: alpine-slim,another-tag,latest
push_git_tag: true
registry: docker.pkg.github.com
context: node-alpine-slim
dockerfile: custom.Dockerfile
build_extra_args: "--compress=true --build-arg=hello=world"
push_image_and_stages: docker run my_awesome_image:latest # eg: push only if docker run succeed
latest
tag, it may download different versions when the action is triggered, and it will invalidate the cache.The tests for this action are run in a separate repo as I need to set credentials for each registry with GitHub secrets and doing so in this repo is not practical.