Skip to main content
Version: 5.16

Image Name & Tagging Schema

The images section in devspace.yaml is a map with keys representing the name of the image and values representing the image definition including tag, dockerfile etc.

images: # map[string]struct | Images to be built and pushed
image1: # string | Name of the image
image: # string | Image repository and name
tags: # string[] | Image tags (may be a tagging schema with variables)
- latest
- 0.0.1
- dev-${USER}-### # Each # will be replaced with a random character

image Image Repository#

The image option expects a string containing the image repository including registry and image name.

  • Make sure you authenticate with the image registry before using in here.
  • For Docker Hub images, do not specify a registry hostname and use just the image name instead (e.g. mysql, my-docker-username/image).

Example: Multiple Images#

image: john/appbackend


  • The first image backend would be tagged as appbackend:[TAG] pushed to Docker Hub using the path john (which generally could be your Docker Hub username).
  • The second image frontend would be tagged as appfrontend:[TAG] and pushed to using the path peter.

tags Tagging Schema#

The tags option expects an array of strings, each containing a static tag or a tagging schema used to automatically tag images before pushing them to the registry. The tagging schema can contain dynamic config variables. While you can define your own config variables, DevSpace provides a set of pre-defined variables. The most commonly used variables for tagging are:

  • DEVSPACE_TIMESTAMP A unix timestamp when the config was loaded
  • DEVSPACE_GIT_COMMIT: A short hash of the local repo's current git commit
  • DEVSPACE_NAMESPACE: The default namespace of your current kube-context

Besides dynamic config variables, DevSpace offers you a possibility to mark certain parts of the image tag as random generated. During image build DevSpace will fill these parts with random characters. The placeholder for a random character is #. For example, let's assume you want to generate tags with the format dev-BRANCH-RANDOM, you would write the tag as:

# The five # are replaced with 5 random characters. The variable ${GIT_BRANCH} is replaced
# with the current branch the user is on
- 'dev-${GIT_BRANCH}-#####'
Unique Tags For Development

Make sure tags are unique when defining a custom tagging schema for development. Unique tags ensure that your application gets started with the newly built image instead of using an older, cached version. Therefore, it is highly recommended for non-production tags to either use # placeholders or DEVSPACE_TIMESTAMP as a suffix in your tagging schema (see example below).

Default Value For tag#

- '#####'

Example: Custom Tagging Schema#

image: john/appbackend
- latest
- dev-backend-${DEVSPACE_GIT_COMMIT}-#####

The above example would always use the tag latest and additionaly generate random tags which could look like this one: dev-backend-b6caf8a-Jak9i. This example tag consists of the following substrings defined by the tagging schema:

  • dev- static string
  • -backend- static string
  • b6caf8a latest git commit hash on current local branch
  • - static string
  • Jak9i auto-generated random string