Docker Compose — Tagging Built Images

1 minute read

When Compose builds an image, you can tag it for pushing to a registry or for version tracking.

Tag with image: Key

services:
  api:
    build: ./api
    image: myregistry.com/api:1.0.0

This builds the image and tags it as myregistry.com/api:1.0.0.

Dynamic Tags with Variable Substitution

.env:

VERSION=1.2.3
REGISTRY=ghcr.io/myorg

compose.yml:

services:
  api:
    build: ./api
    image: ${REGISTRY}/api:${VERSION}
  web:
    build: ./web
    image: ${REGISTRY}/web:${VERSION}

docker compose build
docker compose push

Build and Push Workflow

# Step 1: Build all images
docker compose build

# Step 2: Push all images
docker compose push

# Step 3: Or build + push together
docker compose build && docker compose push

Push Specific Service

docker compose push api     # Push only the api image

Tag for Multiple Environments

# compose.yml
services:
  api:
    build: ./api
    image: myregistry/api:${TAG:-latest}

TAG=v1.2.3 docker compose build
TAG=v1.2.3 docker compose push

TAG=latest docker compose build
TAG=latest docker compose push

Listing Built Images

docker compose images

CONTAINER           REPOSITORY              TAG       IMAGE ID       SIZE
myapp-api-1         myregistry.com/api      1.0.0     abc123def456   150MB
myapp-web-1         myregistry.com/web      1.0.0     789ghi012jkl   25MB

CI/CD Tagging Pattern

services:
  api:
    build:
      context: ./api
      labels:
        com.example.version: ${VERSION}
        com.example.git-sha: ${GIT_SHA}
    image: ${REGISTRY}/api:${VERSION}

export VERSION=$(git describe --tags)
export GIT_SHA=$(git rev-parse --short HEAD)
export REGISTRY=ghcr.io/myorg
docker compose build && docker compose push

Summary

Task Command / Config
Tag on build image: + build: together
Dynamic tags Use variable substitution
Build all docker compose build
Push all docker compose push
Push one docker compose push <service>
List images docker compose images

Quick Reference

Item Detail
image: + build: Tag the built image
Variable tags image: registry/name:${VERSION}
docker compose build Build all services
docker compose push Push all images
docker compose images List built images

You may also enjoy