Squash Docker Registry

Squash has  a built-in Docker Registry that you can use to easily store and retrieve Docker images from your applications.

How it works

  • When Squash builds a new version of your app it will automatically create a new image and push it to the registry, if the build is successful.
  • New subsequent builds will automatically use the latest image for caching purposes. Squash still builds a new image from scratch and since it starts by loading the previously generated image the build will finish faster.
  • You can easily link images between services/apps if you are using docker-compose.

Use Cases & Benefits

  • The Squash Docker Registry is very helpful for projects with multiple repositories and applications made of services defined in different repos.
  • A common example is a web application with a front-end defined in a separate repository. Squash makes it easy to build the front-end independently and associate it with the backend application by using a docker-compose file (see example below).
  • Squash automatically uses images in its registry to improve the build speed of new deployments, automated checks and pipelines.

Image tags

Squash stores each Docker image using the following tag convention:


  • repository_name: this is the repository name as defined in GitHub/Bitbucket/GitLab
  • application_name: this is the name of the application as defined in the Squash YAML file or simply automatically named as “default” for repositories without a Squash YAML file.
  • branch_name: this is the branch name that originally generated the tag. Use the same name as defined in GitHub/Bitbucket/Gitlab
  • service_name: this is optional and only used when Squash builds images based on docker-compose files (see details below). in that case this is going to be the service name used in the docker-compose file.

Docker Image name example

This is how a Docker image tag would look like for a repository “acme-app”, using branch “master” and without a Squash YAML file (“default” is used as an application name when the Squash YAML file is not present):


Squash YAML file

Using this Squash YAML file as an example, for branch “master” and repository name “acme-app”.

    filename: Dockerfile

Squash will generate the following tag name:acme-app-myapp-master

Using images from the Squash Docker Registry in a docker-compose file

Let’s assume we have two repositories:

  • acme-backend: Backend application defined in a docker-compose file
  • acme-frontend: Front-end application (for instance using a popular Javascript framework such as React, Angular or Vue.js) – let’s assume we have a simple Dockerfile to build this front-end app.

Here is how you can easily use the Squash Docker Registry to automatically build test environments and pipelines for these two repositories:

  • Configure the Squash pipelines to automatically build your front-end app on each commit. You may also just use the Automated Checks feature for this purpose.
  • Update your docker-compose file to reference the front-end app using an image name from the Squash Registry.

These two steps will allow you to start new Squash deployments using a fresh version of both the backend and front-end working together. Squash also allows you to easily match branch names from the backend repo with the front-end repo. For instance, if you are using a branch named “lib-upgrades” in the backend app Squash can automatically fetch the exact same branch from the front-end repo if it’s available (more below).

Docker-compose file using an image from the Squash Registry

This docker-compose sample uses the “${SQUASH_REGISTRY}” environment variable to automatically fetch images from the Squash registry. Note that we are using the following image name for the frontend service: acme-frontend-myapp-master

  • Repository name: acme-frontend
  • App name: myapp
    • as defined in the Squash YAML file of the frontend repo – as described in the previous example above.
  • Branch name: master
    • we are keeping it simple for this example and only consuming images from this branch.
version: '3.2'
    image: ${SQUASH_REGISTRY}:acme-frontend-myapp-master
      - 80:3000

      context: .
        dockerfile: Dockerfile-backend    
      - 8000:8000

Docker-compose file using a dynamic image name with branch matching

Similar to the example above, but now using the “${SQUASH_MATCH_BRANCH}” environment variable. When this env variable is present Squash will do the following:

  • Assuming the branch being built in the acme-backend repo is “branchABC”
  • First check if there is a “branchABC” branch in the acme-frontend repo. If there is one, Squash will use an image for this branch if the image is available.
  • If the above fails, Squash will use an image for the default branch (usually branch master) in the acme-frontend repo.
version: '3.2'
    image: ${SQUASH_REGISTRY}:acme-frontend-myapp-${SQUASH_MATCH_BRANCH}
      - 80:3000

      context: .
        dockerfile: Dockerfile-backend    
      - 8000:8000

How Images affect the build process

Squash automatically uses images from the registry when available to speed up the build process. Squash still normally runs the entire build process of your app after loading an image, whether using a Dockerfile or for builds without Docker. Behind the scenes Squash leverages the layers in a Dockerfile (or defined in a Squash YAML file when you are not providing a Dockerfile) in order to speed up the build.

Browsing and deleting images from the registry

You can browse and delete one or more images from the Squash registry by going to the Squash cache page. On this page you can filter images by repository and also select and delete images.

Expiration of Images

Squash automatically replaces the content of an image name on each new commit that gets pushed to that same repo/branch/app.

Images that have not been accessed (read or by pushing new changes) within a 30 day period are automatically deleted.